Skip to content

Documentation Workflow

This project uses MkDocs with the Material theme plus the mkdocs-encryptcontent-plugin to build the public "gh-doc" site. All editable markdown lives under the docs/ folder and the navigation menu is defined in mkdocs.yml.

1. Update the content

  • In the Sanevec-docs repo, make all the modifications under the main branch or create a feature branch off fom it.
  • Edit existing markdown files in docs/ or add a new file (keep names short and URL friendly).
  • When adding a new page, list it inside the nav: section of mkdocs.yml so it shows up in the sidebar.
  • Avoid committing the generated site/ folder; the build step recreates it automatically.
  1. Create or activate a Python environment.
  2. Install the required packages: 
    pip install -r requirements.txt
    OR 
    pip install mkdocs mkdocs-material mkdocs-encryptcontent-plugin
  3. Serve the site locally and browse to http://127.0.0.1:8000/: 
    mkdocs serve
    MkDocs rebuilds on every save, so you can iterate quickly.

3. Publish via GitHub Actions

  • Push or merge your changes into the documentation branch.
  • The Build and Deploy MkDocs workflow (.github/workflows/gh-pages.yml) installs MkDocs and runs mkdocs gh-deploy --force --no-history.
  • On success the static site is published to the gh-pages branch, updating the GitHub Pages site automatically.
  • You can monitor progress and logs in the Actions tab; the run kicks off on every push to documentation or via a manual dispatch.

4. Quick checklist

  • Markdown updated under docs/
  • Navigation updated in mkdocs.yml
  • Local preview (optional) looks correct
  • Changes committed and pushed to main
  • GitHub Action completes successfully and the public site reflects the update