Documentation¶

This documentation site is built with Zensical — the modern static site generator from the Material for MkDocs team — and published to GitHub Pages automatically on every push to main.

This page explains how to work on the docs locally and how the deployment pipeline is set up, so you can reproduce it from scratch.

Project layout¶

.
├─ .github/workflows/docs.yml   # GitHub Pages build + deploy workflow
├─ docs/                        # Markdown sources for this site
│  ├─ index.md
│  ├─ getting-started/
│  ├─ reference/
│  ├─ concepts/
│  └─ contributing/
└─ zensical.toml                # Site configuration

• zensical.toml holds all site configuration — name, theme, navigation, and Markdown extensions.
• docs/ holds the Markdown content. The navigation is defined explicitly in zensical.toml; if you remove the nav block, Zensical derives the navigation from this directory structure instead.
• site/ is the build output. It is generated by zensical build and is git-ignored — never commit it.

Working on the docs locally¶

Zensical is a Python package. Install it into a virtual environment:

uv venv
uv pip install zensical

python3 -m venv .venv
source .venv/bin/activate
pip install zensical

Then start the live-reloading preview server from the repository root:

zensical serve

Open http://localhost:8000 — the site rebuilds automatically as you edit files under docs/. To preview on a different address, pass --dev-addr <ip:port>.

To produce a production build into site/:

zensical build --clean

Use --strict to make the build fail on warnings (for example, broken internal links) — this is worth running before pushing.

How deployment works¶

Publishing is handled by .github/workflows/docs.yml, which uses GitHub's first-party Pages actions. On every push to main it:

1. Configures the GitHub Pages environment.
2. Checks out the repository and sets up Python.
3. Installs Zensical and runs zensical build --clean, producing site/.
4. Uploads site/ as a Pages artifact and deploys it.

name: Documentation
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/configure-pages@v6
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: 3.x
      - run: pip install zensical
      - run: zensical build --clean
      - uses: actions/upload-pages-artifact@v5
        with:
          path: site
      - uses: actions/deploy-pages@v5
        id: deployment

One-time repository setup¶

The workflow deploys via the GitHub Pages Actions source, which has to be enabled once per repository:

1. Go to Settings → Pages.
2. Under Build and deployment → Source, choose GitHub Actions.

That's it — there is no gh-pages branch to manage. The permissions block in the workflow grants the deploy-pages action the pages: write and id-token: write scopes it needs; no personal access token or secret is required.

The published site lives at the site_url configured in zensical.toml:

[project]
site_url = "https://shyim.github.io/akari/"

For a GitHub Pages project site the URL is https://<user>.github.io/<repo>/. Keep site_url in sync if the repository is ever renamed or moved to a custom domain — it drives canonical links, the sitemap, and instant navigation.

Recreating this setup from scratch¶

If you ever need to regenerate the scaffolding, zensical new produces exactly this layout — a zensical.toml, a starter docs/, and the .github/workflows/docs.yml workflow shown above:

zensical new .

It will not overwrite existing files, so it is safe to run in a populated directory; it only fills in the pieces that are missing.

Adding a page¶

1. Create a Markdown file under docs/ (e.g. docs/reference/my-page.md). An optional front-matter icon: sets the page's nav icon.
2. Add it to the nav array in zensical.toml so it appears in the navigation.
3. Run zensical serve and check it renders as expected.

Zensical supports the full Material for MkDocs authoring feature set — admonitions, content tabs, code annotations, Mermaid diagrams, and more. See the Zensical documentation for the complete authoring reference.