use include_yaml macro to add the nav section does not work

[sdellwig]

I wanted to load the navigation from an external file.
I included

plugins:
  - macros:
      include_yaml:
        - nav.yml

where the file includes the 'nav:' tag.
The file is loaded, because other tags like variables in the extra section were loaded but unfortunately the nav section seems to be ignored.

Has anyone successfully managed to load the nav from an external file? Do you know why this might not work properly?

[fralau]

I don't think that would work by itself, since the data are loaded into the namespace of extra.

If you wish to influence the navigation, you might have to write a piece of code in macros.py to read that namespace and then somehow influence the navigation. That would require knowing how mkdocs' data structures for navigation are organized.

I see more questions on navigation, lately. 🤔 What is the issue you wish to solve concerning it?

More generally, do you have any insight on why others would want to influence navigation?

[sdellwig]

ok, that explains, why it does not work. I was not aware that it is loaded into the extra section.

I can only tell my case. I want to create a documentation template and for tailoring the template, people should easily switch between different version of the navigation (different content). Therefor I thought that I write multiple versions of the navigation and for tailoring you just need to include the right file in the mkdocs.yml.

[fralau]

Thanks for the quick answer. Those multiple versions, you would use them to generate several versions of the website, or allow the user to select dynamically between them?

The macros are executed (as the name suggests) at the server side when producing the HTML pages, i.e. the end result is static pages which are stored on the server.

MkDocs does not provide a way to change navigation when the page is being served (since that would go against the definition of a static site generator). Normaly, when you wish something to happen in the browser, then you would have to use some javascript in a page (that is what is done with Mkdocs-Mermaid2, display diagrams). But I do not see well how one could influence navigation with javascript.

[sdellwig]

I would use them to generate several versions of the website. Each is then static again.

My usecase is to provide some kind of project documentation template. Depending on the kind of project, you need to provide different information. My idea is to put all pages in one project and just select, through the nav tag, which project configuration is actually needed. I think I will solve this with some kind of script, which runs before the mkdocs build.

[fralau]

I would say that for the moment, it's a little too advanced for the state of the art. 🙂

[pedro-psb]

I'm working on a multirepo site where I needed to dynamically define the navigation. I was able to do it like that in my macro file:

def define_env(env):
    BASEPATPH = Path("some/base/path/for/files/")
    env.conf["docs_dir"] = BASEPATH
    env.conf["nav"] = [
        {"Section A": BASEPATH / "index.md"}, # dict, where key is the Title
        "foo.md", # just path, where markdown title is the Title
    ]

This way you can programmatically generate the nav, so it may help with part of your project.

[fralau]

Thanks for your input!