dokk

A tiny static docs generator in pure Python.
Folders of Markdown in, a fast static docs site out. No Node.

Live demo and docs · Quick start · Components · Themes · Theme showcase · PyPI

Quick start

pip install "dokk[serve,search]"
dokk init --root my-docs
dokk serve --root my-docs     # http://127.0.0.1:8002/

dokk build writes plain HTML to .dokk/build/, ready for GitHub Pages or any static host. dokk init also creates a workflow that publishes it on every push.

What you get

• A sidebar built from your folder tree, or arranged in dokk.toml.
• Markdown with tables, footnotes, task lists, definition lists and heading anchors.
• Components as Markdown directives: callouts, tabs, cards, steps, file trees, badges and more.
• Code highlighting at build time, in light and dark.
• Full-text search with Pagefind, fully static.
• Eight Basecoat styles and the shadcn/ui colors, vendored: no CDN, no third-party requests.
• dokk serve with live reload, and dokk check for broken links and anchors.
• A sitemap, a Markdown copy of every page and optional llms.txt, for search engines and AI tools.

The documentation is built with dokk from the docs/ folder in this repository.

Development

Install everything (dev tools, dev server, search, browser tests):

uv sync --all-extras          # .venv with the exact versions from uv.lock
uv run playwright install chromium   # once, for the browser tests in tests/e2e

Run tools through make (below) or activate .venv. Plain uv sync without --all-extras removes the extras again.

Run the checks:

make lint        # all of the below
make format      # ruff: fix lint issues, then format
make typecheck   # ty
make test        # pytest

Serving the sites

The repo has two sites. Without --root, dokk uses the current folder.

dokk serve rebuilds on every change and reloads the browser. It includes draft pages and ignores the base path; --search also rebuilds the search index.

To look at a production build instead:

dokk build --root examples/basic
python -m http.server 8002 -d examples/basic/.dokk/build

Releasing

The version comes from the git tag (hatch-vcs); there is nothing to bump. Push a tag such as v0.0.2 and .github/workflows/release.yml builds the wheel and sdist and tests the wheel. Once the pypi environment is approved, it publishes to PyPI and creates the GitHub release. CI tests Linux, macOS and Windows on every push.

Vendored assets

Basecoat and the shadcn/ui color themes are vendored; see VENDORED.md. Update them with python scripts/vendor_basecoat.py and python scripts/vendor_shadcn_themes.py (standard library only, no Node).