Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Conflict with literate-nav plugin #106

Open
osamimi opened this issue Feb 1, 2025 · 1 comment
Open

Conflict with literate-nav plugin #106

osamimi opened this issue Feb 1, 2025 · 1 comment

Comments

@osamimi
Copy link

osamimi commented Feb 1, 2025

It appears that this plugin breaks mkdocs-literate-nav.

literate-nav plugin is used along with mkdocstrings to create automatically generated API docs as detailed here : https://mkdocstrings.github.io/recipes/

This is not too surprising because both this plugin and literate-nav try to do magic with something like - Page Title : folder/ in the nav. So for example with a mkdocs/yaml like this:

nav:
  - Start Here: index.md
  - Examples: gallery
  - API Reference: api/
  - About: about.md

plugins:

  - search
  - gen-files
  - section-index 
  - mkdocstrings
  - gallery:
      examples_dirs: docs/examples        
      gallery_dirs: docs/gallery   
  - literate-nav:
      nav_file: SUMMARY.md

The side bar navigation for "API Reference" which is usually handled by literate-nav (from api/SUMMARY.md) breaks. See screenshots below.

Any ideas on how to avoid this? I tried reordering the two plugins in mkdocs.yml with no luck.

With gallery enabled:
Image

With gallery disabled:
Image

@osamimi
Copy link
Author

osamimi commented Feb 5, 2025

if someone runs into this, this new plugin offers an alternative way of automating nav for mkdocstrings which avoids literate-nav: https://github.com/tlambert03/mkdocs-api-autonav
Seems to work pretty well!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant