MkDocs插件允许指向索引页的可单击部分
mkdocs-section-index的Python项目详细描述
mkdocs节索引
Pluginfor MkDocs允许指向索引页的可单击部分。在
pip install mkdocs-section-index
Example
在^{em1}中使用nav
$mkdocs.yml公司(或不带nav
,但有an equivalent directory structure):
borgs人/索引.md页面合并为“Borgs”部分的索引。通常,MkDocs中的部分不能作为页面本身单击,但是这个插件使之成为可能。在
另请参阅:a realistic demo site。
主题支持
此插件需要每个主题重写(在插件中实现),或support from themes themselves。在
当前支持的themes包括:
使用说明
上面所示的nav恰好也是省略nav
时MkDocs生成的;它检测^{
为了使编写这种nav
更自然(in YAML there's no better option),考虑使用^{str1}$literate-nav插件;然后上面的nav可以这样写:
* [Frob](index.md) * [Baz](baz.md) * [Borgs](borgs/index.md) * [Bar](borgs/bar.md) * [Foo](borgs/foo.md)
Implementation
“协议”
通常在MkDocs ^{
- 一个^{
} ,它有一个title
和{}。 - (
url
总是None
)
- (
- 一个^{
} ,它有一个title
和{}。 - (
title
可以省略,稍后根据页面内容推断) - (^{
} 总是None
)
- (
- (对我们来说无关紧要)。在
此插件引入了一个hybrid kind of ^{
title
:str
url
:str
children
:list
is_page
=True
is_section
=True
这样一个特殊的项被放入nav中,代替一个Section
,它有一个Page
,它的第一个子元素是一个有意省略的标题。这两者自然地结合成一个特殊的section-page,这是两者的混合体。在
主题实施
然后,主题模板需要做的就是有意义地支持这样的导航项——既有url
和{
当然,目前的模板并不期望这样的情况;或者如果他们有,那纯粹是偶然的。所以目前这个插件“侵入”了支持主题的模板,patching their source on the fly以满足其需要。希望是,一旦这个插件获得足够的吸引力,主题作者会很乐意直接支持这个场景(这是完全非侵入性和向后兼容的),然后补丁可以被删除。在
“考虑的备选方案”
即使所有的模板补丁都没有了,这个插件仍然是这个特殊的nav“protocol”的实现,以及opt-in机制。作者认为,这种做法是有利的,因为:
- 在
这是一个有争议的问题,不能默认启用,甚至不能成为MkDocs的一部分。这是discussed in the past and dropped。主要原因是在MkDocs中,没有要求nav的结构遵循doc文件的实际目录结构。因此,没有一种自然的方法可以从文档的位置推断出文档应该成为节的索引页,即使它的名称是索引.md。虽然如果nav是omitted & generated,那么是的,这样的假设是可行的。它也适用于绝大多数实际用法withanav,但这没有帮助。在
在 - 在
主题本身也可能不应该直接尝试检测逻辑,比如“如果没有标题,则为节的第一个子项”,并在Jinja模板代码中手动折叠子项,因为这太混乱了。这也不应该启用默认为ed。即使模板也可以选择加入,但像这样的集中化方法可以确保统一地访问这个特性。更不用说模板可能永远不会实现这一点。在
在
- 项目
标签: