mkdocs-literate-nav

插件 用于 MkDocs，用Markdown而不是YAML指定导航

pip install mkdocs-literate-nav

与 section-index 和 gen-files 兼容。取代了 awesome-pages。

用法

在 mkdocs.yml 中激活插件

plugins:
  - search
  - literate-nav:
      nav_file: SUMMARY.md

并且如果存在，则 删除 nav 部分；现在将忽略它。（除非您想保留它？）

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

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

重要：导航文件必须放在 docs 目录 中 -- 在它的根目录。

因此，该插件允许您使用按照常规Markdown规则解析的链接列表指定您网站的导航。

请注意，我们编写的Markdown中，一个章节似乎还关联了一个页面。MkDocs实际上不支持这一点，也无法直接在YAML中表示，因此插件尝试做下一件最好的事情：将链接包含为章节的第一页。然而，这种结构非常适合section-index插件，它实际上使这一功能得以实现。或者你也可以不将链接与章节关联

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

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

查看关于literate nav文件的语法细节。

你可以在测试用例目录中找到更多“literate nav”语法的示例。

导航交叉链接

但为什么止步于此？每个目录都可以有自己的独立导航列表（看看尾部斜杠如何启动导航交叉链接）

* [Frob](index.md)
* [Baz](baz.md)
* [Borgs](borgs/)

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

* [Bar](bar.md)
* [Foo](foo.md)

注意：仅在父导航文件中明确提及目录的情况下，才会收集子目录中的导航文件。SUMMARY.md（通常nav-file）文件不会被隐式收集（只有根导航文件是“隐式的”）。

因此，可以说导航构建方法正好与awesome-pages插件相反。

话虽如此，一个推断的交叉链接目录（无论是直接还是通过通配符）将被递归解析，这样你实际上又回到了隐式解析。

推断子目录

或者，你可能不关心borgs/目录下页面的顺序？只需删除文件borgs/SUMMARY.md，让它被推断（递归地，如果适用）。在我们的特定例子中，最终结果将是相同的。

后备行为遵循MkDocs在未指定导航时的默认行为，除了你可以排除一些目录树，而不是全部或全部的选择。

通配符

在完全指定导航和完全推断导航的两个极端之间，可以选择应用通配符。

你不需要在导航列表中放入像[Foo 1](foo_1.md)、[Foo 2](foo_2.md)这样的链接，你可以写一个通配符项：foo_*.md（裸的，不是作为链接）。星号表示可以放置任意数量的字符，并且文件名必须与模式的其他部分匹配。

通配符项总是需要至少有一个*星号，因为如果没有，那么它就只是一个裸项，这是不允许的。

查看关于通配符的详细信息。

因此，这可以用来完全指定重要项目的顺序，并为所有其他情况应用通配符。示例

- [Welcome](index.md)
- Usage
    - [Foo](usage/foo.md)
    - usage/*.md
- */
- *.md
- [API docs](api/)
- [License](license.md)

- Welcome: index.md
- Usage:
    - Foo: usage/foo.md
    - usage/bar.md
    - usage/baz.md
- Tips:
    - tips/other-stuff.md
    - tips/stuff.md
- changelog.md
- credits.md
- API docs:
    - api/Foo.md
    - Bar:
        - api/Bar/index.md
        - api/Bar/Baz.md
- License: license.md

提示：说到API文档...想要在大型的目录树中调整文件顺序？查看与其他插件的集成。

路径相对于包含导航文件的目录。匹配子目录中的文件也有效，两种方式都适用：*/foo.md和foo/*.md。

由于用户无法指定由通配符产生的项目标题，因此必须根据MkDocs的正常规则进行推断。

提示：项目的排序与MkDocs的默认排序相同，因此首先列出所有文件，按字母顺序（但首先是索引文件），然后列出所有目录。但是，以一个例子来说，您实际上可以通过编写来交换这个顺序

- */
- *

您可以在测试用例目录中找到更多通配符语法的示例。

自定义nav_file

我们一直在使用SUMMARY.md作为指定导航的文件名（实际上这也是nav_file的默认值），但当然，您可以使用任何其他文件名。

查看关于nav_file配置的详细信息。

插件会注意，如果您最终没有将导航文档作为您的文档网站的实际页面使用，MkDocs不会抱怨。

在首页展示您的导航

或者，也许您想相反——使导航页面非常突出？您实际上可以使用索引页面，即README.md，作为导航！

为什么有人会这样做呢？好吧，GitHub（或另一个源托管）也会显示Markdown文件，将导航直接显示在目录的索引页面上是一个相当不错的优势。当然，那么您可能就会避免使用通配符。不过，目录交叉链接看起来仍然很棒。

如果您问这个问题，那么如果索引页面被导航占用，我们还能在哪里放置其他内容呢？实际上，我们可以！导航列表可以放在页面的底部，该页面还包含之前的其他内容。

查看所有这些功能在实际中的示例

显式导航标记

如果插件在文档中不清楚导航在哪里，或者您想明确地将它放置在特定位置，请在该Markdown列表之前使用此HTML注释（逐字逐句）单独一行。

<!--nav-->

混合导航

这个插件的功能是否吸引您，但您又不想迁移整个导航？

您实际上可以继续使用MkDocs自己的导航规范在根目录，但仅将一些子目录推迟到literate-nav插件。在这种情况下，请确保不要在docs根目录放置导航文件，否则本地导航将被忽略。

nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs: borgs/

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

* [Bar](bar.md)
* [Foo](foo.md)

将子目录推迟的语法与在文献导航中相同，即编写以正斜杠结束的项目。

注意：无法使用YAML导航子目录，只有文献导航可以推迟。

通配符也以非常相似的方式工作。

查看关于MkDocs本地导航语法添加的详细信息。

您可以在测试用例目录中找到混合导航语法的示例。

MkDocs本地导航与推断子目录

像以前一样，无论何时您有使用文献导航文件为子目录提供选项，您也可以不放置任何导航文件，而是推断子目录。所以，在上面的例子中，不创建文件borgs/SUMMARY.md会产生相同的结果。

因此，基本上，您可以使用literate-nav插件仅利用其推断子目录的能力，而不必编写任何实际的“文献导航”。

关于混合导航的详细信息

作为一个最终的例子，请注意有两种方法可以包含子目录，这两种方法有显著的不同。

nav:
  - Frob: index.md
  - Baz: baz.md
  - Borgs: borgs/

nav:
  - Frob: index.md
  - Baz: baz.md
  - borgs/*

因此，一个带有标题的目录项变成了一个标题为该名称的章节。通配符（不能指定标题）则内联到现有章节中。这个简单的例子没有子子目录，但如果有的话，这两种情况下都会保留相对子目录结构。

附加功能

对导航的编程控制

假设你需要推断子目录的导航，但又不喜欢默认的命名/布局行为，而且也不想手动编写所有内容。那么，绝对要检查一下 gen-files 插件。它的正常用法是在构建过程中编程式地添加文件到网站，但也包括文献导航文件！此外，你甚至不需要教你的程序如何编写Markdown。有一个更直接的集成方式：mkdocs_gen_files.Nav.build_literate_nav。

查看一个同时生成文件和覆盖它们的导航的示例.

缩进列表为2个空格，而不是4个

通过 tab_length 或 markdown_extensions 来配置它

从GitBook迁移？

可能非常简单！但请注意更严格的Markdown解析器；它 不会 接受子列表的2个空格缩进。

并且使用以下内容来 mkdocs.yml

use_directory_urls: false

plugins:
  - search
  - same-dir
  - section-index
  - literate-nav:
      nav_file: SUMMARY.md

theme:
  name: material

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.magiclink
  - pymdownx.superfences