Skip to content

Building This Docs Site

This documentation site is built with MkDocs Material.

Only docs/ is the authored documentation tree.

The source Markdown and assets live in docs/, while the MkDocs config, container image, and generated output live under mkdocs-material/.

That means:

  • edit pages in docs/
  • treat mkdocs-material/site/ as generated output
  • do not leave parallel edited copies under mkdocs-material/docs/

The site now uses the standard Material docs pattern: left navigation, content in the middle, and the page table of contents on the right.

It outputs a normal static site, so you can preview it locally and publish it to any ordinary web server.

Local preview with Podman

The repo already includes a small Node wrapper plus lightweight Podman entrypoints.

From the repo root on any platform:

pnpm docs:dev

If you prefer the direct platform wrappers, they still work too.

From the repo root on PowerShell:

.\podman-mkdocs.ps1

From Git Bash or another Unix-like shell:

./podman-mkdocs.sh

Both scripts automatically build a local image called buttonscli-docs on the first run. This image extends the official squidfunk/mkdocs-material image with pillow and cairosvg, which are required by the social card plugin. Subsequent runs reuse the cached image.

Open http://127.0.0.1:8000 in your browser to review the site.

If Podman is installed but the wrapper says it cannot connect to the Podman socket, start the local machine first:

podman machine start

If you change mkdocs-material/Dockerfile (for example to update the base image version), remove the cached image first so it gets rebuilt:

podman rmi localhost/buttonscli-docs
.\podman-mkdocs.ps1

Static build output

To build the static site from the repo root:

pnpm docs:build

If you want to run the container directly, use the same repo-root mount that the wrapper uses:

podman run --rm -v "$PWD:/workspace" localhost/buttonscli-docs build -f /workspace/mkdocs-material/mkdocs.yml

Build the image first if you have not run the serve script yet:

podman build -t localhost/buttonscli-docs mkdocs-material

The generated site is written here:

mkdocs-material/site/

Do not judge the generated output by double-clicking files from the file system. Preview it through the MkDocs server, another local web server, or your real deployed server.

Copying the site to a server

Any static web server can host the generated folder.

Examples:

scp -r mkdocs-material/site/* user@your-server:/var/www/your-domain/

rsync -av --delete mkdocs-material/site/ user@your-server:/var/www/your-domain/

Keeping docs current

Feature changes should update the matching pages in docs/ in the same change.

In practice that means:

  • new user-visible features should be documented when they land
  • removed features should be removed from the docs the same day
  • partial or experimental behavior should be described plainly

That keeps the site aligned with the app instead of drifting into stale copy.