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.
pip install mkdocs-literate-navNo compatibility data collected yet for this library.
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).
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`.
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.
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.
Always ensure your `mkdocs` installation is up-to-date, preferably `mkdocs>=1.6`, to avoid compatibility issues and benefit from recent bug fixes.
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.
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/`).
First, install the plugin: `pip install mkdocs-literate-nav`. Then, enable it in your `mkdocs.yml`: ```yaml plugins: - search - literate-nav ```
Ensure all links in your navigation Markdown file have a title, like `* [Page Title](path/to/page.md)`.
If `mkdocs-literate-nav` is managing all your navigation, remove the entire `nav` section from `mkdocs.yml`. If you intend to use a hybrid approach, ensure your `mkdocs.yml` `nav` refers to directories that explicitly contain `literate-nav` files (e.g., `[Section](path/to/dir/)` which would then look for `path/to/dir/SUMMARY.md`).
Ensure that plugins generating files explicitly manage their inclusion levels. For `mkdocs-gen-files`, you might use `mkdocs_gen_files.Nav.build_literate_nav` for programmatic control over the generated navigation structure, ensuring files are properly included.