Skip to content

Contributing to documentation

This website is rendered from Markdown documentation in the Purdue AF GitHub repository.

To contribute to the documentation, please open a pull request — or simply click the "edit" icon at the top of any page to edit it directly on GitHub.

How the site is built

  • The documentation is written in Markdown (sources in docs/docs/) and built with Zensical, a static site generator from the authors of Material for MkDocs.
  • The site configuration (navigation, theme, Markdown extensions) lives in a single file: docs/zensical.toml.
  • On every push to the main branch that touches the docs, a GitHub Actions workflow (.github/workflows/docs.yml) rebuilds the site and deploys it to GitHub Pages.

Previewing changes locally

pip install zensical

cd docs
zensical serve

The site will be available at http://localhost:8000 and rebuilt automatically as you edit the files. To produce a one-off production build instead, run zensical build --clean (output goes to docs/site/).

Style conventions

  • One page per topic; cross-link related pages liberally.
  • Use admonitions (!!! note, !!! warning, !!! tip) for asides, and collapsible blocks (??? note) for long optional content.
  • Always state explicitly whether a feature applies to Purdue users, CERN/FNAL users, or everyone.
  • Prefer copy-pasteable code blocks over screenshots of terminals.