Support a plugin to allow clickable sections that lead to an index page

I have developed a plugin for MkDocs, “section-index” that allows sections in the left-side nav to be not just expandable, but also have a link to a page directly associated with them.

The plugin already fully works as-is (you can use it!), but the implementation currently needs to “hack into” the templates of themes (such as mkdocs-material and others). So I am reaching out to ensure good long-term support of this idea.

mkdocs-material theme could integrate optional “code paths” directly into its templates in a way that has 0 effect when the plugin isn’t loaded, and if it is loaded, the template directly works with the “protocol” provided by it, without hacks.

Demos

A real website using this

Screencast with comparison

nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs:
    - borgs/index.md
    - Bar: borgs/bar.md
    - Foo: borgs/foo.md

plugins:
  - section-index

The above demo features this^ mkdocs.yml config. Obviously by default in MkDocs this means something else, but with this plugin, the borgs/index.md page is merged as the index of the “Borgs” section.

Details

Other than the part that rewrites theme templates, the core of this plugin is the code that modifies the nav object. When it encounters a Section and a Page in a configuration like above, it collapses the two into one object, which is a hybrid of properties of both:

• title: str
• url: str (normally exclusive to Page)
• children: list (normally exclusive to Section)
• is_page = True
• is_section = True

The condition for this collapsing is up for discussion, but currently it’s very “permissive”. Just any page that’s specified only as a link (no title), if it’s the first item of a section, becomes merged as the index page of the section. The idea is for people to always specify names for all pages in the nav except for the section-title ones.

Other approaches are possible, but it’s certainly not as easy as just checking against index.md.

With this, all that a theme needs to do is consider the case where both url and children are present (without this plugin that can never happen), and render a “section-page” as part of the navigation menu.

An individual theme could actually implement this feature on its own (no plugin), by checking for such conditions directly within Jinja templates, but I personally find that less clean. See my further arguments on this.

[squidfunk]

@jaceklaskowski it was the wrong link in the issue here, yeah, haven’t seen the localhost part when I copied it. This is now fixed in my comment.

[squidfunk]

Awesome, any feedback appreciated 😎