这是一个优秀的mkdocs项目的小插件,它对导航做了一些增强。
mkdocs-nav-enhancements的Python项目详细描述
mkdocs导航增强功能
这是优秀的MkDocs项目的一个小插件,它对导航进行了一些增强。
功能
增强标题
默认情况下,mkdocs查找位于文档顶部的级别1 atx样式的标题,并将其用于页面标题。
如果您正在处理来自第三方的文档,您可能会发现其中一些文档的标题是从第2级开始的(可能是出于美观的原因),或者使用setext样式的标题。
此插件将通过查看每个标记文档并使用以下规则检测页面标题来提供帮助:
使用文档中位于1到6之间任何级别的第一个ATX样式标题,即以1到6个字符开头的任何行。
或者使用第一个setext样式的标题,这是紧跟其后的行只包含“=”或“-”字符的任何行,实际上是该行的“下划线”。
它还将删除在标题中找到的任何其他标记,例如图像或链接标记,否则这些标记将在生成的html中呈现为字符串文本。
减少文件夹
为了消除导航的混乱,插件会查找任何只包含一个页面的部分,并尝试将该页面向上折叠到其父级。这有助于处理充满单页文件夹的导航栏,以保持事物整洁。
用法
安装插件:
pip install mkdocs-nav-enhancements
将插件添加到mkdocs.yml
MkDocs configuration文件:
plugins:-mkdocs-nav-enhancements
已知问题
当更改页面标题或折叠单个页面文件夹时,这有时会导致有效页面标题完全不同。目前,这个插件不会重新排序导航栏时,发生这种情况。
第二个问题是,这些选项不是独立可控的,至少在第一个版本中是不可控的;现在是全部还是全部都没有!
贡献
源代码托管在GitHub。
请在GitHub Issues上报告问题和功能请求。
拉请求也欢迎!