Support dynamic navigation in main and subfolder mkdocs.yml files

[jalaziz]

While this plugin is awesome for monorepos, it does introduce the burden of having to define the complete navigation structure manually.

It would be great if functionality similar to mkdocs-awesome-pages-plugin could be included. The point would be to allow navigation structures to be partially defined (i.e. to add !include directives) yet still end up with a complete navigation tree.

As for why? Well, it would allow team members to add new docs without having to also update and maintain the mkdocs.yml file.

[bih]

Hey, thanks for reaching out! What you're saying is totally valid, and something we did discuss, but I think in the end we decided that it didn't fit our vision for what Spotify needed. Maintaining the mkdocs.yml is additional work, yes, but it adds clarity to codebases where there's a considerable number of users.

Of course, any features you would like relating to this could fit into this repository, or if that doesn't end up being the case, maybe a fork of this which allows you to optimize for a different use case (i.e. repositories with only a single maintainer, etc).

[jalaziz]

Maintaining the mkdocs.yml is additional work, yes, but it adds clarity to codebases where there's a considerable number of users.

I can see your point here, but one thing that is nice about mkdocs-awesome-pages-plugin is that it allows navigation to be defined separately from the mkdocs.yml, separating concerns between writing documentation and the "build" process.

In our case, we have a similar situation where our "customers" happens to be the rest of the engineering team. One thing we'd like to accomplish is allowing users to easily add documentation without having to worry about things like extensions, themes, etc. I do realize the opposite argument could be made, especially for serving a local site from the team's own docs folder. For smaller teams, dynamic navigation could be useful, but the separation of concerns is what we're mostly going for.

I appreciate that you'd be willing to fit it into this repo if it makes sense. We're in the early stages of getting things rolled out, but we'll definitely contribute any changes we make, if any.

[tjdavis3]

I for one would like to see this reconsidered. Getting my developers to create and update documentation pages is enough of a struggle, but getting the navigation updated is even harder. It would be nice if new pages automatically appeared in the automatically built documentation even if no one remembered to add it. mkdocs-awesome-pages-plugin allows to have a "catchall" location for this new documentation if building it individually, but unfortunately it just gets skipped if building the top-level documentation.

[maciejmatczak]

@tjdavis3, I just got back to reviewing functionality of this plugin to check whether it's worth using it or symlinks in my "build system" are enough for now ;)

You are talking about the top level config, right? If the nav is the section that needs an automation, why not create on your side mkdocs-source.yml with empty nav, load in in python, populate with you custom docs discovery, done.

[tjdavis3]

@maciejmatczak when you say mkdocs-source.yml I'm assuming you mean the mkdocs.yml in the source repos (since I don't see mkdocs-source.yml referenced anywhere in the docs). What you propose is an all or nothing solution. One of the advantages of mkdocs-awesome-pages-plugin is that you can define the navigation, but then have a place for any files that weren't explicitly in the navigation so they at least appear in the generated documentation and with the filter options can even get them to appear in the logical place in the navigation based on the filename.

[legoguy1000]

I would love to see this feature as well. We have one repo that is dynamically generated content and has 100's of nested pages that would be untenable to manually define them all in mkdocs.yml file

[l13t]

Hey, any chance to have dynamic links as they are generated with plain mkdocs? We also have 100's of nested pages and sometimes under 3 or 4 levels.

[ReessKennedy]

+1 ... we find it much easier when we don't have to manually define the navigation and have it generated just based on the presence of a page. It's just one less thing that we could forget to do that could cause problems. It's nice to just know that if I create the page and commit, it's there and visible to everyone easily.

[rocha-bruno]

+1 ... adding the newly created pages in the nav is often forgotten and we have hundreds of repos.