Python API to generated nav?

[ms-lolo]

Is there any way for me to get the generated navigation as if I was parsing the nav value in mkdocs.yml? Before using this plugin, I was parsing mkdocs.yml in order to generate a matching navigation structure in other parts of our site that were not managed by mkdocs. Is this possible? It looks like maybe I can call AwesomePagesPlugin.on_nav() in some way to get what I want? Not being very familiar with the mkdocs plugin system and this codebase, I'm a little hesitant to guess my way through and possibly have future releases break my hacky logic.

[lukasgeiter]

I'd suggest you create your own plugin that implements the on_nav event hook. As first argument, the method will receive a Navigation object. You'll mostly be using the items property which gives you a nested list of all sections, pages and links.

Make sure to register your plugin after awesome-pages in mkdocs.yml. That way your plugin is called after awesome-pages has made its changes to the navigation.

[ms-lolo]

that's only less ideal because it would require me to run the full mkdocs build before being able to generate the other site components but I get how this is probably the most reliable way for me to get the exact navigation generated without poking into this plugin's internal classes. looking at the mkdocs plugin docs, this doesn't seem too daunting so I'll give that a shot. thanks for the help!

[lukasgeiter]

Of course I don't know any details about your setup, but it might also have some advantages to do it this way. If you generate the other site components as part of the MkDocs build you can ensure that both navigations will always be in sync.

If you want you could also abort the build process in your plugin's on_nav method (e.g. by raising SystemExit). Then you would have access to the navigation without the overhead of generating the actual documentation.

[ms-lolo]

forgot to come back and mention that creating a little plugin worked just fine! it looked a little like this:

class MkdocsPlugin(BasePlugin):  # type: ignore
    def on_nav(self, nav: Navigation, config: Config, files: Files) -> Navigation:  # type: ignore
        result = []
        # The mkdocs.yml file in the project .tmp directory
        config_path = Path(config["config_file_path"])
        # The directory containing the mkdocs.yml file
        config_dir_path = (config_path / "..").resolve()
        # We will be creating a top-nav.yml file for us here to use in sphinx builds
        output_path = config_dir_path / "top-nav.yml"

        def find_first_path(i: Union[Section, Page]) -> str:  # type: ignore
            if isinstance(i, Page):
                return f"/{i.url}"

            return find_first_path(i.children[0])

        for item in nav.items:
            result.append({
                "name": item.title,
                "path": find_first_path(item),
            })

        output_path.write_text(yaml.dump(result, indent=2))

        return nav

We're mostly writing out the top navigation items so I can generate the same thing in the various sphinx docs steps.

Thanks again for the suggestion :)