Getting started¶

Enable zensical for your project¶

1. Ensure you have at least docs/index.md.
2. Copy zensical.toml to your repo. Update the block at the top and remove unneeded plugins.
3. Copy .github/workflows/docs.yaml. In your repo, set Settings | Pages | Source to GitHub Actions.
4. Add dependencies.
   • At a minimum, zensical.
   • We also recommend mdx-truly-sane-lists.
   • If you are building python API docs, also mkdocstrings-python.
   • You may want to add these to a separate group, for example using uv add --group docs or uv add --dev.
5. Ensure that site/ is git-ignored but docs/ is not.
6. Check that you can zensical serve.
7. See the example static page and zensical docs for more information about features like math rendering.
8. See the example API docs, which document the toy code in mkdtemp/.

Migrating from mkdocs¶

The workflow is somewhat different if you are migrating from mkdocs.

1. uv remove mkdocs mkdocs-material. You may need a --group argument.
2. uv add zensical mdx-truly-sane-lists. You might want a --group argument.
3. Remove mkdocs.yaml
4. Copy and update zensical.toml
5. Consider deleting docs/javascript
6. Update GitHub workflow
   • Change the filename
   • Change name of the workflow
   • Use zensical, not mkdocs
7. Update notes in the readme

Interactive tool¶

This repo implements an experimental, interactive tool that automates new zensical setup and mkdocs migration. Run the tool using uv:

uvx --from git+https://github.com/CDCgov/cfa-zensical-template cfadoc

See the API reference for details about the cfadoc package.