MkDocs Windmill

MkDocs Windmill is a documentation theme for the MkDocs static site generator from Grist Labs, built to make navigation and search usable for larger documentation projects. It turns a MkDocs project into a static documentation site with persistent navigation state, highlighted search results, and a quick-search dropdown.

What is MkDocs Windmill?

MkDocs Windmill is a theme for MkDocs, the Python-based static site generator for project documentation. It takes a MkDocs project configured with the theme: windmill directive and produces a static HTML documentation site. The theme is developed and maintained by Grist Labs and distributed as a Python package on PyPI under the name mkdocs-windmill.

Key Features

• Convenient navigation for large documentation sets — The theme structures navigation to handle projects with many pages without overwhelming the user.
• Stateful navigation menu — The navigation menu retains its open/closed state across page transitions, so users do not have to re-expand sections.
• Search with term highlighting — Search results highlight the matching terms in the page, making it easier to find the relevant portion.
• Quick dropdown and full-page search — Users can either type in a dropdown for immediate results or load a full results page for deeper searching.
• Standard MkDocs page rendering — Within pages, MkDocs Windmill uses the default MkDocs theme styling, including syntax highlighting for code blocks.
• Simple installation — Install with pip install mkdocs-windmill, then set theme: windmill in mkdocs.yml.
• Homepage requirement — The theme requires a homepage defined as a top-level root element in the nav, e.g. nav: - Home: index.md.

Who is it for?

• Documentation maintainers — For projects with a large number of pages, the stateful navigation and quick search help users find content.
• Technical writers — Writers who need a theme that emphasizes navigation structure and supports term-highlighted search results.
• Open-source project maintainers — Projects using MkDocs to publish docs can adopt this theme to give their users a better browsing experience.

What can you do with MkDocs Windmill?

• Structure large docs — Create a documentation site where the navigation menu remembers where users have been, reducing friction in multi-page reference material.
• Improve searchability — Offer both dropdown and full-page search with term highlighting, helping users locate specific sections quickly.
• Customize further — Use the customization options described on the project's documentation site to tweak the theme beyond its defaults.