Migrate docs to MkDocs Material + GitHub Pages#44
Merged
sbryngelson merged 11 commits intocomp-physics:masterfrom Mar 5, 2026
Merged
Migrate docs to MkDocs Material + GitHub Pages#44sbryngelson merged 11 commits intocomp-physics:masterfrom
sbryngelson merged 11 commits intocomp-physics:masterfrom
Conversation
Move content into docs/, add MkDocs config with Material theme matching comp-physics.group branding, add .readthedocs.yaml for deployment via Zensical, fix markdown rendering issues, add markdownlint CI, remove stale TOC workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Review Summary by QodoMigrate documentation to MkDocs Material theme with GitHub Pages deployment
WalkthroughsDescription• Migrate documentation from traditional markdown to MkDocs Material theme for improved presentation and maintainability • Normalize heading levels across all syllabus documents (convert ## to # for main headings, ### to ## for sections) for MkDocs compatibility • Remove auto-generated doctoc table of contents comments and manual TOC entries from all documentation files • Create new MkDocs configuration (mkdocs.yml) with Material theme, dark/light mode support, and custom branding colors (#292929 primary, #c0995e accent) • Add custom CSS styling (docs/assets/extra.css) for Material theme customization matching comp-physics.group branding • Configure MathJax support (docs/assets/mathjax.js) for mathematical equation rendering • Create documentation site homepage (docs/index.md) with organized navigation and links to resources • Set up GitHub Actions workflows for automated deployment to GitHub Pages, markdown linting, and spell checking • Update relative links to GitHub URLs for template references and external resources • Simplify README to focus on MkDocs documentation site with minimal landing page content • Add markdownlint configuration and Python dependencies for documentation build process • Remove deprecated TOC generator workflow and configuration files Diagramflowchart LR
A["Markdown Files<br/>with doctoc"] -->|"Normalize headings<br/>Remove TOC"| B["MkDocs<br/>Compatible Docs"]
B -->|"Apply theme<br/>& styling"| C["Material Theme<br/>Site"]
C -->|"GitHub Actions<br/>Deploy"| D["GitHub Pages<br/>comp-physics.group"]
E["mkdocs.yml<br/>Configuration"] -->|"Configure"| C
F["Custom CSS<br/>& MathJax"] -->|"Style & Render"| C
File Changes1. docs/group-syllabus/improving-your-writing.md
|
Code Review by Qodo
1. Non-reproducible docs deploy
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+24
to
+27
| - name: Build docs | ||
| run: | | ||
| pip install zensical | ||
| zensical build |
There was a problem hiding this comment.
1. Non-reproducible docs deploy 🐞 Bug ⛯ Reliability
The Pages deploy workflow installs zensical from PyPI without version pinning and ignores docs/requirements.txt, so builds can drift/break over time and local vs CI dependencies can diverge.
Agent Prompt
### Issue description
The GitHub Pages deploy workflow installs `zensical` with `pip install zensical`, which pulls whatever the latest version is at build time. The repo also includes `docs/requirements.txt`, but CI never uses it. This creates non-reproducible deploys and can cause sudden build failures.
### Issue Context
The workflow is responsible for building and publishing the docs to GitHub Pages. For reliable docs deployments, dependency versions should be deterministic and shared between local and CI.
### Fix Focus Areas
- .github/workflows/deploy.yml[24-28]
- docs/requirements.txt[1-1]
### Suggested change
1) Change the workflow to install from requirements:
```sh
python -m pip install --upgrade pip
pip install -r docs/requirements.txt
```
2) Pin `zensical` in `docs/requirements.txt` (e.g., `zensical==<known-good-version>`), or introduce a constraints file.
3) (Optional) Add caching for pip to speed builds.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
15
to
16
| - name: Spell Check | ||
| uses: crate-ci/typos@master |
There was a problem hiding this comment.
2. Typos action not pinned 🐞 Bug ⛨ Security
The spell-check workflow uses crate-ci/typos@master, which is a mutable branch reference and increases supply-chain risk and non-deterministic CI behavior.
Agent Prompt
### Issue description
The workflow references `crate-ci/typos@master`, which can change over time and introduces supply-chain and reproducibility risk.
### Issue Context
CI workflows should avoid floating branches for actions, especially for third-party repositories.
### Fix Focus Areas
- .github/workflows/spelling.yml[15-16]
### Suggested change
Replace `@master` with either:
- a specific release tag (preferred for readability), or
- a commit SHA (preferred for immutability).
Example:
```yaml
uses: crate-ci/typos@<tag-or-sha>
```
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan