Material for MkDocs
otsumami.mkdocs
A Docker Compose file for Material for MkDocs alone, generated from the catalog and checked by the safety inspector. No account needed.
Documentation site generator built on MkDocs with the Material theme, producing a static site from Markdown with client-side search, versioned navigation and code annotation.
MkDocs builds a documentation site from a directory of Markdown files and a single YAML configuration that declares the navigation tree, and the Material theme supplies the layout, search index, dark mode and a large set of Markdown extensions. Those extensions cover admonitions, tabbed content, annotated code blocks, task lists and diagram rendering, which is most of what technical documentation needs without custom templates. A development server rebuilds and reloads on save, and the built output is plain HTML with no runtime service behind it. A first deployment mounts the docs directory and configuration, serves it locally and checks that search returns results.
You know it worked when
- The development server starts and the site loads in a browser.
- A change to a Markdown file appears after an automatic rebuild.
- Every page in the configured navigation is reachable from the menu.
- A search query returns matching pages.
- A production build writes a self-contained static site.
Known sharp edges
- Documentation that describes an Insiders-only feature is easy to follow into a configuration the public build rejects at startup.
- The navigation tree is declared explicitly in configuration, so a new Markdown file is built but unreachable until it is added there.
- Several theme features depend on Markdown extensions and plugins that must be enabled in configuration, and omitting one produces silently unstyled output rather than an error.
- Search is a client-side index generated at build time and grows with the site, which makes first page load noticeably slower on large documentation sets.