rtfm site is built with MkDocs.
- Fork the rtfm repo to your user on github
- Go to your copy of the repo (eg https://github/USERNAME/rtfm) and clone it
- if you haven't already, install mkdocs on your local machine.
- create a branch, make your edits
- run "mkdocs build" and verify that the changes look good locally.
- commit your changes them and push the branch up to your github rtfm repo
- create a pull request for your branch against master on the main rtfm repo
A SYN Shop member will review and merge your request if it all looks good!
How content is pushed live
There are two repos to house content. One repo, rtfm houses the raw, unprocessed markdown files. Another repo rtfm-generated hosts the processed files that mkdocs generates. Every time a commit is merged to the
master branch in
rtfm the following happens:
- A GitHub Action is fired based off of the ci.yml file. All actions are executed in VMs called runners. GitHub gives a certain amount of runner hours for free to non-profits.
- Following the
ci.ymlfile, the runner checks out
master branch, installs
mkdocsand generates the HTML for the site in the runner's VM. The site is checked out using a robot account (
monitoring-synshop-bot) that only has access to push to
- The runner then pushes the site from
rtfmrepo to the
rtfm-generatedrepo. This is destructive, so any pages not on
rtfmwill be deleted.
- The GitHub Pages for
rtfm-generatedare configured so that the contents of the repo are served up under
rtfm.synshop.orgis a CNAME for
synshop.github.iowhich is set at an org level to show the contents of
How to regenerate the token to push the site live
The robot account (
monitoring-synshop-bot) needs to regenerate the personal access token every 90 days. We set it to expire in 90 days so we remember how to regenerate it - if we set it for a year we'll never remember. These are the steps:
- get a copy of the password safe
- using the credentials in that safe for
monitoring-synshop-bot, log into https://github.com
- Create a new access token. It should have full "repo" perms. Set it to expire in 90 days. Be sure to copy the token - it will only be shown once!!
- Log out of that account, and log into an account that is in the SYN Shop org
- Find the
DEPOLY_TO_RTFM_SITEon the Actions secrets page and click the pencel to edit the value
- Where it says "Secret values are encrypted and cannot be displayed, but you can enter a new value" - click the link to enter a new value.
- paste in the value from step 3 above and save