mkdocs-section-index

插件 为 MkDocs 允许点击的章节链接到索引页面

pip install mkdocs-section-index

示例

在 mkdocs.yml 中的此 nav （或没有 nav 但有 等效的目录结构）

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

plugins:
  - search
  - section-index

“Borgs”章节的索引合并为 borgs/index.md 页面。通常，在 MkDocs 中，章节不能作为页面本身进行点击，但此插件使其成为可能。

另请参阅： 一个真实的演示网站。

主题支持

此插件需要每个主题的覆盖（在插件内部实现），或 主题本身的支持。

当前支持的 主题 有

• material
• readthedocs
• nature

使用说明

上图中显示的这种导航类型恰好也是MkDocs在省略nav时产生的结果；它会检测index.md和README.md页面，并将其自动设置为第一个项目。

为了使编写这种nav更自然（在YAML中没有更好的选择），请考虑使用此插件与literate-nav一起使用；然后上面的nav可以写成这样

* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/index.md)
    * [Bar](borgs/bar.md)
    * [Foo](borgs/foo.md)

实现

"协议"

在MkDocs中，通常在nav中，项目可以是以下之一：

• a Section，它有一个title和children。
  • （url始终为None）
• a Page，它有一个title和url。
  • （title可以省略，以后可以从页面内容中推断出来）
  • （children始终为None）
• a Link（对我们来说无关紧要）。

此插件引入了一种混合类型的Page，它具有所有这些属性

• title: str
• url: str
• children: list
• is_page = True
• is_section = True

这种特殊的项目被放置在nav中，代替了具有一个故意省略标题的Page作为其第一个子项的Section。这两者自然组合成了一个特殊的section-page，它是两者的混合。

主题内的实现

然后，主题的模板需要做的就是有意义地支持此类nav项——即同时具有url和children的项。该项应直接可点击，以跳转到相应的页面，并能够容纳子项。

当然，目前模板并不期望这种情况；或者如果它们确实期望，那也是纯属偶然。因此，目前这个插件“黑客”支持的主题的模板，即时修补它们的源代码以满足其需求。希望一旦这个插件获得足够的关注度，主题作者将乐意直接支持这种场景（这完全是非侵入性和向后兼容的），然后可以取消修补。

"考虑过的替代方案"

即使所有模板修补都已消失，此插件仍将是特殊nav“协议”的实现，以及强制的机制。在作者看来，这种做法的优点是

• 这太有争议了，不能默认启用，甚至不能成为MkDocs的一部分。这已经被讨论过并放弃了。主要原因是在MkDocs中，没有要求nav的结构遵循文档文件的实际目录结构。因此，没有自然的方法可以仅从其位置推断出文档应该成为某个部分的索引页，即使它被命名为index.md。虽然如果省略了nav并生成，那么这样的假设是成立的。在大多数实际使用中，这也适用于nav，但这并没有帮助。

• 主题本身可能也不应该直接尝试检测逻辑，例如“如果一个部分没有标题，则它的第一个子项”，并在 Jinja 模板代码中手动折叠子项（这会很混乱）。默认情况下也不应该启用此功能。尽管模板也可以选择性地实现此功能，但像这样集中的方法可以确保以统一的方式访问此功能。更不用说模板可能永远不会自行实现此功能。