Automate mkdocs nav generation

[campb303]

Background

mkdocs currently allows two ways to generate its navigation: automated and manual. (See mkdocs navigation docs)

Automated

When the nav entry is absent from the mkdocs configuration file (default: mkdocs.yml), the entire documentation directory (default: docs/) is parsed and looks for files with a valid markdown extension to generate a navigation with section headers for each folder and documents for each markdown file.

Example

With no nav entry in the mkdocs configuration file and a directory structure like this:

.
├── docs
│   ├── Dev Environment Setup Guide.md
│   ├── Testing Docs
│   │   └── Material for mkdocs Formatting.md
│   ├── ecnqueue.md
│   ├── images/
│   │   ├── (listings removed; non markdown files are ignored by mkdocs)
│   ├── index.md
│   └── javascript/ 
│   │   ├── (listings removed; non markdown files are ignored by mkdocs)
├── mkdocs.yml

mkdocs will generate a navigation menu like this:

Manual

Allows a nav entry to be put into the mkdocs configuration file to specify the files/sections included in the navigations as well as their order however all files must be explicitly configured.

Example:

With a directory structure like this:

.
├── docs
│   ├── Dev Environment Setup Guide.md
│   ├── Testing Docs
│   │   └── Material for mkdocs Formatting.md
│   ├── ecnqueue.md
│   ├── images/
│   │   ├── (listings removed; non markdown files are ignored by mkdocs)
│   ├── index.md
│   └── javascript/ 
│   │   ├── (listings removed; non markdown files are ignored by mkdocs)
├── mkdocs.yml

And a configuration file containing a nav section like this:

nav:
  - index.md
  - Testing Docs:
    - Testing Docs/Material for mkdocs Formatting.md

mkdocs will generate a navigation menu like this:

Note that the directory structure is the same, files note explicitly configured in the nav section are ignored.

Problem

The automated method of navigation generation allows for all files to be included in the navigation with little effort but allows no control over order. The manual method of navigation generation allows for control over order but requires all files to be linked to manually.

For documentation, the ability to order documents is important as the flow of information implies where to start and allows for a path to be made showing others how to use whatever is being documented. Therefore, the ability to control document order is imperative. However, the overhead of manually linking to every new document is cumbersome and presents a barrier both to documentation maintenance and third party contribution.

We need a way to control the order of documents while also automating the generation of the navigation menu.

Work So Far

This is an issue that the greater mkdocs community is already aware of as evident in this GItHub issue requesting the same feature The useful suggestions from this thread include:

• Awesome Pages for mkdocs plugin
• A nav generation script

I spent a few days creating a script inspired by the nav generation script with slow but promising success before seeing the plugin mentioned. The plugin claims to achieve the same outcome with a different approach. If it actually works, processing with the plugin makes more sense than writing our own tool. However, if the management of the plugin still proves more difficult than helpful we will fall back to developing our own tool.

[benne238]

Awesome Docs Configuration syntax

Following this guide, I attempted to set up the awesome docs configuration. However, due to a special syntax, was unable to get it to function. When setting up the the .pages config file, it is important that it doesn't have a file extension of any sort, other wise the awesome docs plugin will not recognize it.

[campb303]

Using the Awesome Pages plugin for MkDocs and the ... (elipses) function, I'm able to get partially ordered nav with "the rest" to following.

First, place an Awesome Pages config file (defaults to .pages) in the MkDocs docs directory (default to docs/) like this:

.
├── docs                                        # MkDocs Docs Directory
│   ├── .pages                                  # Awesome Pages Config
│   ├── Dev Environment Setup Guide.md
│   ├── Im-First
│   │   └── index.md
│   ├── No-Im-First
│   │   └── index.md
│   ├── Other_Files
│   │   └── Material for mkdocs Formatting.md
│   ├── ecnqueue.md
│   ├── index.md
├── mkdocs.yml

Then add a single nav entry to the Awesome Pages configuration file containing list items in the order they should appear in navigation. Here are some examples:

Include all files in alphabetical order (equivalent to omitting the nav entry in MkDocs)

# .pages
nav:
  - ...

Place one sub section first and the rest after (sub sections are referenced by case sensitive directory names)

# .pages
nav:
  - Im-First
  - ...

Place one document first, a sub section last, and the rest in between (documents are references by their path relative to the directory containing the Awesome Pages config file and full filename)

# .pages
nav:
  - Dev Environment Setup Guide.md
  - ...
  - Im-First

[campb303]

It appears this extension does what we want it to do. Closing the issue.