{"id":2994,"library":"mkdocs-literate-nav","title":"MkDocs Literate Nav","description":"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.","status":"active","version":"0.6.3","language":"en","source_language":"en","source_url":"https://github.com/oprypin/mkdocs-literate-nav","tags":["mkdocs","documentation","navigation","markdown","plugin","static-site-generator"],"install":[{"cmd":"pip install mkdocs-literate-nav","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency as this is an MkDocs plugin. Requires MkDocs >=1.6 for full compatibility.","package":"mkdocs","optional":false}],"imports":[],"quickstart":{"code":"plugins:\n  - literate-nav: \n      nav_file: SUMMARY.md\n\n# In your docs/SUMMARY.md file:\n# * [Home](index.md)\n# * About\n#   * [Team](about/team.md)\n#   * [History](about/history.md)\n# * API Reference: api/","lang":"yaml","description":"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)."},"warnings":[{"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`.","message":"The default value of `nav_file` changed from `index.md` to `SUMMARY.md`.","severity":"breaking","affected_versions":"0.4.0 and later"},{"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.","message":"Navigation files (e.g., `SUMMARY.md`) will no longer be picked up by wildcards when defining navigation.","severity":"breaking","affected_versions":"0.4.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.6.3 and later"},{"fix":"Always ensure your `mkdocs` installation is up-to-date, preferably `mkdocs>=1.6`, to avoid compatibility issues and benefit from recent bug fixes.","message":"Requires specific versions of MkDocs for full compatibility, with recent versions requiring `MkDocs >= 1.6`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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/`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}