vexy-mkdocs-tools

Documentation: https://vexy.dev/vexy-mkdocs-tools/

Fire-based CLI that bundles ProperDocs + MaterialX and the standard vexy- plugin set, so a site builds in one shot:

uvx vexy-mkdocs-tools build

Why

Every FontLab/Vexy MkDocs-style site repeats the same dependency list and the same wrapper script (clean docs/ but keep CNAME, optionally Flowmark-format src_docs/md/ first, then properdocs build, then write .nojekyll). This package owns the dependency set and the wrapper, so site repos shrink to "Markdown + mkdocs.yml".

Install

uv pip install vexy-mkdocs-tools           # site builds
uv pip install "vexy-mkdocs-tools[flowmark]" # also Flowmark formatting

Or ad-hoc without installing:

uvx vexy-mkdocs-tools build
uvx --with flowmark vexy-mkdocs-tools build

Commands

vexy-mkdocs-tools and vmt are aliases.

Site layout assumed

<repo>/
├── mkdocs/mkdocs.yml     # config (--config to override)
├── src_docs/md/          # Markdown source (--src to override)
└── docs/                 # build output (--docs to override)

The CLI walks up from cwd until it finds a directory containing both mkdocs/mkdocs.yml and src_docs/. Pass --root to skip the walk.

Bundled dependencies

ProperDocs 1.6.7+, MaterialX 10.1.4+, plus pymdown-extensions, mkdocs-awesome-nav, mkdocs-include-markdown-plugin, mkdocs-llmstxt, mkdocs-copy-to-llm, mkdocs-rss-plugin. The [flowmark] extra adds flowmark.

Develop

uv sync --extra dev
uv run python -m pytest -q
uvx ruff check src tests
./build.sh    # docs (src_docs/ → docs/) + wheel/sdist + twine check
./publish.sh  # gitnextver tag → build → uv publish (needs UV_PUBLISH_TOKEN)

Releases are tag-driven — push a vX.Y.Z tag and the release workflow ships to PyPI.

Docs

Full documentation, including the site-layout contract and the materialx theme note: https://vexy.dev/vexy-mkdocs-tools/.

License

Apache-2.0.