Package: mkdocs-section-index
mkdocs-section-indexPluginforMkDocsto allow clickable sections that lead to an index pagepipinstallmkdocs-section-indexExampleWith thisnavinmkdocs.yml(or withoutnavbut withan equivalent directory structure):nav:-Frob:index.md-Baz:baz.md-Borgs:-borgs/index.md-Bar:borgs/bar.md-Foo:borgs/foo.mdplugins:-search-section-indexTheborgs/index.mdpage is merged as the index of the "Borgs" section. Normally sections inMkDocscannot be clickable as pages themselves, but this plugin makes that possible.See also:a realistic demo site.Theme supportThis plugin requires per-theme overrides (implemented within the plugin), orsupport from themes themselves.Currently supportedthemesare:materialreadthedocsnatureUsage notesThe kind ofnavas shown above also happens to be what MkDocs produces whennavis omitted; it detectsindex.mdandREADME.mdpages and automatically puts them as the first item.To make writing this kind ofnavmore natural (in YAML there's no better option), consider using theliterate-navpluginalong with this; then the abovenavmight be written like this:*[Frob](index.md)*[Baz](baz.md)*[Borgs](borgs/index.md)*[Bar](borgs/bar.md)*[Foo](borgs/foo.md)Implementation"Protocol"Normally in MkDocsnav, the items can be one of:aSection, which has atitleandchildren.(urlis alwaysNone)aPage, which has atitleandurl.(titlecan be omitted, and later deduced from the page content)(childrenis alwaysNone)aLink(inconsequential for our purposes).This plugin introduces ahybrid kind ofPage, which has all of these properties:title:strurl:strchildren:listis_page=Trueis_section=TrueSuch a special item gets put into a nav in the place of aSectionwhich has aPagewith an intentionally omitted title as its first child. Those two are naturally combined into a specialsection-pagethat's a hybrid of the two.Implementation within themesThen all that a theme's template needs to do is to meaningfully support such nav items -- ones that have both aurlandchildren. The item should be directly clickable to go to the corresponding page, and also be able to house sub-items.Of course, currently templates don't expect such a case; or if they did, it would be purely by chance. So currently this plugin "hacks into" templates of supported themes,patching their source on the flyto fit its needs. The hope is that, once this plugin gains enough traction, theme authors will be happy to directly support this scenario (which is totally non-intrusive and backwards-compatible), and then the patches could be dropped."Alternatives considered"Even if all the template patches are gone, this plugin will still remain as the implementation of this special nav "protocol", and as theopt-in mechanism. In the author's view, such an approach is advantageous, because:This is too controversial to be enabled by default, or even be part of MkDocs at all. This has beendiscussed in the past and dropped. The main reason is that in MkDocs there's no requirement for anav's structure to follow the actual directory structure of the doc files. Consequently, there's no natural way to deduce that a document should become the index page of a section just from its location, even if it's namedindex.md. Although if thenavisomitted & generated, then yes, such an assumption works. It also works in the vast majority of actual usageswithanav, but that doesn't help.Themes themselves also probably shouldn't directly try to detect logic such as "first child of a section if it has no title" and manually collapse the childwithin Jinja template code, as that's too messy. This also shouldn't be enabled by default. And even though templates could also make this opt-in, a centralized approach like this one ensures that accessing this feature is done uniformly. Not to mention that templates might never implement this themselves.