This guide outlines how to contribute to, test, build, and deploy the static documentation site for Panurus.
Documentation is built using MkDocs with the premium, responsive Material for MkDocs theme.
To preview changes locally, you will need Python 3 installed on your system.
Install the pinned documentation tools (including MkDocs and the Material theme) using the requirements file:
make docs-install
This target runs:
pip install -r requirements.txt
You can start a local development server that watches for file changes and automatically refreshes your browser:
make docs-serve
Once started, open your browser and navigate to:
π http://127.0.0.1:8000
To verify that all links are resolved and the site builds cleanly without any warnings:
make docs-build
This runs the strict compiler command:
mkdocs build --strict
[!IMPORTANT] The
--strictflag ensures that the build will fail if there are any warnings (such as orphaned files or broken internal links). Always verify your build withmake docs-buildbefore committing changes!
The Check Markdown links workflow (.github/workflows/md_links.yml) runs three checks:
lychee --offline --include-fragments): fails on any broken relative link or #anchor in docs/ and the root *.md files. Run it locally with:
lychee --offline --include-fragments --no-progress 'docs/**/*.md' '*.md'
[!NOTE] Anchors follow GitHubβs heading slugs (e.g.
### 3. Finality Trackingbecomes#3--finality-tracking), which differ from the slugs MkDocs generates.
The static documentation site is automatically built and deployed to GitHub Pages whenever changes are merged into the main branch.
If this is being set up on a new fork or repository for the first time, follow these steps to configure GitHub Pages:
gh-pages and set the folder to / (root).The GitHub Actions workflow .github/workflows/docs.yml will automatically create and update the gh-pages branch on every merge.
All documentation source markdown files are located in the docs/ directory of the project:
docs/
βββ README.md # Home page
βββ configuration.md # Configuration guide
βββ development/ # Developer guidelines and guides
β βββ ai_agents.md # AI Agent context
β βββ documentation.md # This guide
β βββ ... # Other development guidelines
βββ drivers/ # Fabric and ZK driver specs
βββ services/ # Core services (auditor, storage, ttx, etc.)
βββ imgs/ # Images and static assets
docs/.mkdocs.yml located at the root of the project.make docs-serve or make docs-build.