Skip to content

Last Updated: 2026-05-04 Owner: Ops-Dev Summary: Step-by-step checklist for publishing the QuantMatrix MkDocs site to GitHub Pages safely and cleanly.

QuantMatrix GitHub Pages Publishing Checklist

This checklist turns the documentation site from a local-only preview into a hosted documentation surface.

Use it when you are ready to publish the MkDocs site through GitHub Pages.

1. Purpose

The purpose of this checklist is to make sure the docs publishing path is: - easy to follow - repeatable - low risk - aligned with the current repository structure

2. Before You Start

Confirm these are already true:

  • the Markdown files in documentation/docs/ are the source of truth
  • documentation/mkdocs.yml exists and builds successfully
  • documentation/requirements-docs.txt is current
  • .github/workflows/docs-site.yml exists
  • the strict MkDocs build passes locally
  • the docs navigation feels stable enough to publish

3. Repository Checklist

  • [ ] Push this project into a real GitHub repository
  • [ ] Confirm the default branch is main
  • [ ] Confirm GitHub Actions is enabled
  • [ ] Confirm GitHub Pages is available for the repository
  • [ ] Confirm maintainers have access to repository settings

4. MkDocs Configuration Checklist

Review and update documentation/mkdocs.yml:

  • [ ] Replace placeholder repo_url with the real GitHub repository URL
  • [ ] Replace placeholder repo_name if needed
  • [ ] Replace placeholder site_url with the real GitHub Pages URL
  • [ ] Confirm docs_dir is docs
  • [ ] Confirm site_dir is site
  • [ ] Confirm the navigation reflects the current document set

5. Documentation Quality Checklist

  • [ ] Confirm each maintained Markdown doc has:
  • Title
  • Tags
  • Last Updated
  • Owner
  • Summary
  • [ ] Regenerate documentation_catalog.md
  • [ ] Refresh the legacy portal bundle if it is still being maintained
  • [ ] Regenerate PDF mirrors if the PDF set is still part of the workflow
  • [ ] Check the docs home page for correct local and hosted links

6. Local Validation Checklist

Before publishing, run local checks:

  • [ ] Install docs dependencies
  • [ ] Run mkdocs build -f documentation/mkdocs.yml --strict
  • [ ] Open the local docs site and browse core sections
  • [ ] Verify search works
  • [ ] Verify the new documents appear in navigation
  • [ ] Verify PDF links still resolve correctly
  • [ ] Verify no placeholder URLs remain in reader-facing docs

7. GitHub Actions Checklist

Review .github/workflows/docs-site.yml:

  • [ ] Trigger on main
  • [ ] Include docs-related file paths
  • [ ] Install docs dependencies from documentation/requirements-docs.txt
  • [ ] Run mkdocs build -f documentation/mkdocs.yml --strict
  • [ ] Upload the documentation/site/ output
  • [ ] Deploy to GitHub Pages

8. GitHub Pages Settings Checklist

In the GitHub repository settings:

  • [ ] Enable GitHub Pages
  • [ ] Set the source to GitHub Actions
  • [ ] Confirm the Pages environment is created successfully
  • [ ] Confirm no branch-based Pages source is conflicting with the workflow

9. First Publish Checklist

For the first hosted release:

  • [ ] Merge the docs-ready branch into main
  • [ ] Watch the docs-site workflow run
  • [ ] Confirm the build job succeeds
  • [ ] Confirm the deploy job succeeds
  • [ ] Open the published GitHub Pages URL
  • [ ] Check the home page, search, navigation, and a few key documents
  • [ ] Check that PDF links behave as expected in the hosted environment

10. Post-Publish Validation

After the first successful publish:

  • [ ] Open the hosted docs site in a normal browser session
  • [ ] Test search with a few terms like:
  • Momentum Radar
  • Operations Runbook
  • API Reference
  • [ ] Confirm core pages load correctly
  • [ ] Confirm the hosted URL matches site_url
  • [ ] Confirm internal Markdown links render correctly
  • [ ] Confirm there are no broken navigation sections

11. Current Versioning Model

The current documentation versioning model is repository-based:

  • documentation changes are versioned in Git
  • the hosted site reflects the current main branch
  • Last Updated metadata gives a human-readable freshness signal

There is not yet release-by-release hosted doc versioning.

That is acceptable for now because the project is still in an early implementation phase.

12. When To Add Hosted Versioning

Hosted versioning should be considered when:

  • the API changes meaningfully across releases
  • paper-trading and live-trading documentation diverge
  • external collaborators need stable historic references

Likely future path:

  • add MkDocs versioning with mike

13. Repository Storage Reminder

Keep this distinction clear:

  • source content lives in documentation/docs/
  • built static output lives in documentation/site/
  • GitHub Pages publishes the built output, not handwritten HTML

14. Failure Recovery Checklist

If the publish fails:

  • [ ] inspect the GitHub Actions build logs
  • [ ] fix strict MkDocs warnings or link issues locally first
  • [ ] rerun mkdocs build -f documentation/mkdocs.yml --strict locally
  • [ ] push the fix and rerun the workflow

If the hosted site is stale:

  • [ ] confirm the workflow actually ran on the latest commit
  • [ ] confirm the deploy job completed
  • [ ] confirm site_url and Pages settings are correct

15. Definition Of Done

This task is done when:

  • the docs build successfully in GitHub Actions
  • GitHub Pages serves the MkDocs site
  • the hosted URL is correct in documentation/mkdocs.yml
  • the team can access the published docs without needing the local machine

16. Best Next Step

Once publishing is live, the next useful improvement is:

  • decide whether to keep the legacy local portal or retire it in favor of MkDocs as the single primary docs surface