MkDocs Zettelkasten

This is a Zettelkasten theme and plugin for MkDocs. It renders the MkDocs pages as cards (zettels).

For more information, head on over to the documentation

Install

pip install mkdocs-zettelkasten

Development

uv sync                    # install deps
uv run playwright install  # install browsers (first time only)

Testing

Three levels of testing, from fast to thorough:

1. Unit tests — plugin logic without building the site:

make test      # ~0.3s, 143 tests

2. E2E tests — playwright builds the site from docs/, serves it, and checks the UI automatically:

make test-e2e  # ~27s, 81 tests

3. Manual acceptance — build and serve the site from docs/, open localhost:8000 in a browser and walk through the checklists in .local/testscripts/:

make run                # default (solarized, validation on)
make run-selenized      # selenized color scheme
make run-editor         # markdown editor enabled
make run-no-validation  # validation disabled

Release

mise adds dev/bin to PATH. Tags with rc in the name publish to TestPyPI; stable tags go to PyPI. Manual workflow dispatch defaults to TestPyPI.

release patch|minor|major              # tag and push -> CI publishes to PyPI
release --pre rc1                      # pre-release current version to TestPyPI
release --pre rc1 minor                # bump + pre-release to TestPyPI
release                                # after rc: strip suffix, release stable to PyPI
release --dry-run patch                # preview without doing anything

First-time setup (already done for mkdocs-zettelkasten):

pypi.org: add trusted publisher (owner: buvis, repo: mkdocs-zettelkasten, workflow: publish.yml, env: pypi)
test.pypi.org: same, env: testpypi
GitHub repo settings: create pypi and testpypi environments

The release script updates the pinned version in .github/workflows/requirements.txt (used by docs deployment), commits, tags, and pushes both. Version derives from git tags via hatch-vcs — no version field in pyproject.toml. This works for pure Python packages. Projects with native extensions (like buvis/gems with maturin/Rust) need an explicit version in pyproject.toml because maturin reads it at build time.

Stable releases (no rc in tag) auto-create a GitHub Release with a changelog generated from conventional commits since the previous tag.

Metadata

Release files for mkdocs-zettelkasten 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-zettelkasten 0.6.1
File	Size	Uploaded
mkdocs_zettelkasten-0.6.1.tar.gz	932.0 kB	Feb 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mkdocs-zettelkasten 0.6.1
File	Interpreter	ABI	Platform	Reset
mkdocs_zettelkasten-0.6.1-py3-none-any.whl 897.6 kB Feb 24, 2026	Python 3	none	any	Details

Total release size: 1.8 MB

Release files / mkdocs_zettelkasten-0.6.1.tar.gz

Download URL	mkdocs_zettelkasten-0.6.1.tar.gz
Size	932.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`741cc444f778425dd6505a753b1102046619ff95b512e1a157e00eaa4bcdc921`
BLAKE2b-256 checksum How to use checksums	`7cbcd097189453c5b1e10a661cd594f20cf50ef057c38c5357949eac1a45210a`
Upload date	Feb 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/buvis/mkdocs-zettelkasten
Publishing commit: github.com/buvis/mkdocs-zettelkasten/tree/12516fb5fa29bb36fdde33cc88abb84daf47de16

Workflow

Publishing configuration: github.com/buvis/mkdocs-zettelkasten/blob/12516fb5fa29bb36fdde33cc88abb84daf47de16/.github/workflows/publish.yml
Publishing logs: github.com/buvis/mkdocs-zettelkasten/actions/runs/22350050559/attempts/1

Artifact

Subject: mkdocs_zettelkasten-0.6.1.tar.gz
SHA-256 checksum: 741cc444f778425dd6505a753b1102046619ff95b512e1a157e00eaa4bcdc921 Verifying attestations

Release files / mkdocs_zettelkasten-0.6.1-py3-none-any.whl

Download URL	mkdocs_zettelkasten-0.6.1-py3-none-any.whl
Size	897.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`aa081e24a34ce04c90ba1a56897e279c89ffe25ed5b1f8e333d5ee26ff05648c`
BLAKE2b-256 checksum How to use checksums	`a29e70c0ddeac08697f32ef8101a0e80f64d83c94babacd33ce741e883b757a3`
Upload date	Feb 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/buvis/mkdocs-zettelkasten
Publishing commit: github.com/buvis/mkdocs-zettelkasten/tree/12516fb5fa29bb36fdde33cc88abb84daf47de16

Workflow

Publishing configuration: github.com/buvis/mkdocs-zettelkasten/blob/12516fb5fa29bb36fdde33cc88abb84daf47de16/.github/workflows/publish.yml
Publishing logs: github.com/buvis/mkdocs-zettelkasten/actions/runs/22350050559/attempts/1

Artifact

Subject: mkdocs_zettelkasten-0.6.1-py3-none-any.whl
SHA-256 checksum: aa081e24a34ce04c90ba1a56897e279c89ffe25ed5b1f8e333d5ee26ff05648c Verifying attestations