MkDocs plugin to specify the navigation in Markdown instead of YAML. The current version is 0.6.3. It follows an irregular release cadence, often tied to MkDocs compatibility or new features.
Warnings
breaking The default value of `nav_file` changed from `index.md` to `SUMMARY.md`.
Fix: If upgrading from an older version, rename your root navigation file from `index.md` to `SUMMARY.md`, or explicitly configure `nav_file` in `mkdocs.yml`.
breaking Navigation files (e.g., `SUMMARY.md`) will no longer be picked up by wildcards when defining navigation.
Fix: Ensure `nav_file`s are explicitly referenced or rely on the plugin's default behavior for locating them, rather than expecting wildcard matches to include them.
gotcha The plugin will issue a warning when used from the `mkdocs` executable (specifically `v0.6.3` onwards). This is related to the 'ProperDocs' initiative, a community continuation of MkDocs.
Fix: If you understand and accept the warning, you can disable it by setting the environment variable `DISABLE_MKDOCS_2_WARNING=true` or `NO_MKDOCS_2_WARNING=true`. Alternatively, consider migrating to ProperDocs if its goals align with your project.
gotcha Requires specific versions of MkDocs for full compatibility, with recent versions requiring `MkDocs >= 1.6`.
Fix: Always ensure your `mkdocs` installation is up-to-date, preferably `mkdocs>=1.6`, to avoid compatibility issues and benefit from recent bug fixes.
gotcha When defining navigation in a Markdown file (e.g., `SUMMARY.md`), the navigation list must be a top-level Markdown list. Links must include a title (e.g., `[Page title](path/to/page.md)`), unless they are wildcards.
Fix: Format your navigation Markdown files strictly according to the plugin's syntax, ensuring links have titles and the main navigation is a top-level list. Bare paths for non-wildcard entries will result in errors.
gotcha If you maintain an `mkdocs.yml` with a native `nav` section at the root, placing a literate nav file (like `SUMMARY.md`) at the root of your `docs_dir` will cause the native `nav` to be entirely ignored.
Fix: To use a 'hybrid nav' approach where MkDocs' native `nav` specifies some sections and `mkdocs-literate-nav` handles subdirectories, ensure there is no literate nav file (e.g., `SUMMARY.md`) at the root of your `docs_dir`. Defer to literate nav only for specific subdirectories using trailing slashes in your `mkdocs.yml` `nav` entries (e.g., `- Subdir: subdir/`).
Install
pip install mkdocs-literate-navInstall stable version
Quickstart
To use the plugin, enable it in your `mkdocs.yml` under the `plugins` section. By default, it looks for `SUMMARY.md` files in your documentation directories to define navigation. The example `SUMMARY.md` shows basic page links, nested sections, and a directory cross-link for 'API Reference' (assuming an `api/` directory with its own `SUMMARY.md` or inferred navigation).
plugins:
- literate-nav:
nav_file: SUMMARY.md
# In your docs/SUMMARY.md file:
# * [Home](index.md)
# * About
# * [Team](about/team.md)
# * [History](about/history.md)
# * API Reference: api/