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