https://github.com/buvis/mkdocs-zettelkasten
This is a Zettelkasten theme and plugin for MkDocs. It renders the MkDocs pages as cards (zettels).
https://github.com/buvis/mkdocs-zettelkasten
Last synced: 4 months ago
JSON representation
This is a Zettelkasten theme and plugin for MkDocs. It renders the MkDocs pages as cards (zettels).
- Host: GitHub
- URL: https://github.com/buvis/mkdocs-zettelkasten
- Owner: buvis
- License: mit
- Created: 2021-11-24T19:48:08.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2026-04-04T20:13:29.000Z (4 months ago)
- Last Synced: 2026-04-04T21:59:35.657Z (4 months ago)
- Language: Python
- Homepage: https://buvis.github.io/mkdocs-zettelkasten/
- Size: 2.19 MB
- Stars: 25
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MkDocs Zettelkasten
This is a [Zettelkasten](https://zettelkasten.de) theme and plugin for [MkDocs](https://www.mkdocs.org). It renders the MkDocs pages as cards (zettels).
For more information, head on over to [the documentation](https://buvis.github.io/mkdocs-zettelkasten/)
## Install
```bash
pip install mkdocs-zettelkasten
```
## Development
```bash
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:
```bash
make test # ~0.3s, ~430 tests
```
**2. E2E tests** — playwright builds the site from `docs/`, serves it, and checks the UI automatically:
```bash
make test-e2e # ~35s, ~190 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/`:
```bash
make run # default (solarized, validation on)
make run-selenized # selenized color scheme
make run-editor # markdown editor enabled
make run-no-validation # validation disabled
make run-graph # knowledge graph enabled
make run-preview # hover previews enabled
make run-math # math rendering 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.
```bash
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.