AuthorHowTo.md

How To for Authors

MkDocs

MkDocs are used to create the site from the contents of the docs directory. The Material for MkDocs template is used to format the markdown. The file mkdocs.yml controls the site organization and navigation. The Mkdocs user guide contains excellent information on configuration and writing docs.

Github Pages are used to host the site from the gh-pages branch.

All source content is stored in docs, written in Markdown and committed to the main branch. When the site is built, it is built, committed to the gh-pages branch (overwriting anything else on that branch), and served by Github Pages.

Getting started

Do the following steps to get started.

1. Clone the shasta-docs repo
2. In shasta-docs clone:

• Using Python3, create a virtual environment and activate it, eg, python3 -m venv ./venv ; source ./venv/bin/activate
• Install the contents of requirements.txt, eg, pip install -r ./requirements.txt

3. Confirm it is installed by running mkdocs --help.

The remainder of this How To assumes you have the Python virtual environment activated, ie, you can run mkdocs.

How To Create and Preview Content

All content should be in the docs directory. Pages should be defined in Markdown. If you want to add a page to the top-level navigation, you must add it the mkdocs.yml nav definition.

For a good overview, see:

• MkDocs getting started
• Material for MkDocs getting started

While you are creating content, you can preview the site in a browser. To do so, run

mkdocs serve

And navigate to the URL displayed (normally http://localhost:8000/shasta-docs/). This will hot-reload anytime you edit content in the docs directory.

How to Deploy Content

The contents of the gh-pages branch is hosted (ie, available on the web). The deployed pages are generated by mkdocs and automatically pushed to the gh-pages branch. Do NOT edit the contents of this branch, as it will be destroyed whenever new content is deployed.

To deploy new content:

1. Make content changes, and confirm the changes using mkdocs serve on your local machine.
2. Commit or merge to the main branch of this repo.
3. Checkout the main branch on your local repo.
4. Run the mkdocs deployment command:

mkdocs gh-deploy

After a few minutes, your new content should be visible.

More Information

Additional links that may be helpful:

• Markdown Cheat Sheet