MkDocs Awesome Pages Plugin

一个简化配置页面标题及其顺序的MkDocs插件

awesome-pages插件允许您自定义MkDocs导航中页面的显示方式，而无需在mkdocs.yml中配置完整结构。它通过直接放置在文档相关目录中的小配置文件，为您提供详细控制。

注意：如果您的mkdocs.yml中定义了nav或pages条目，此插件将不会执行任何操作。为了使用以下列出的功能，您必须完全删除条目或向其中添加...条目。

安装

注意：此软件包需要Python >=3.8.1和MkDocs版本1.0或更高。
如果您仍在使用MkDocs 0.17，请使用此插件的1.0版本。

使用pip安装软件包

pip install mkdocs-awesome-pages-plugin

在您的mkdocs.yml中启用插件

plugins:
    - search
    - awesome-pages

注意： 如果您的配置文件中还没有 plugins 条目，您可能还希望添加 search 插件。MkDocs 默认启用它（如果没有设置 plugins 条目），但现在您需要显式启用它。

有关插件的更多信息，请参阅 MkDocs 文档

功能

自定义导航

在目录中创建一个名为 .pages 的文件，并使用 nav 属性来自定义该级别的导航。按照它们应在导航中出现的顺序列出文件和子目录。

nav:
    - subdirectory
    - page1.md
    - page2.md

剩余部分

列表中未提到的页面或部分将不会出现在导航中。但是，您可以包含一个 ... 条目来指定剩余所有项应插入的位置。

nav:
    - introduction.md
    - ...
    - summary.md

此外，您可以使用通配符模式或正则表达式来过滤剩余项。例如，仅匹配以 introduction- 开头的 Markdown 文件。

nav:
    - ... | introduction-*.md
    - ...
    - summary.md

注意： 模式与剩余项的基本名（文件夹- / 文件名）进行比较，而不是它们的整个路径。

有关更多详细信息，请参阅下面的 剩余部分过滤模式 部分。

标题

您可以可选地为导航条目指定标题。

nav:
    - ...
    - First page: page1.md

注意： 为包含定义 title 的 .pages 文件的目录指定标题没有任何效果。

链接

您还可以使用 nav 属性向导航中添加其他链接。

nav:
    - ...
    - Link Title: https://lukasgeiter.com

部分

您可以通过创建新部分来分组项。

nav:
    - introduction.md
    - Section 1:
        - page1.md
        - page2.md
    - Section 2:
        - ...

更改排序顺序

在目录中创建一个名为 .pages 的文件，并将 order 属性设置为 asc 或 desc 以更改导航项的顺序。

order: desc

注意： 与默认顺序不同，这不会区分文件和目录。因此，页面和部分可能会混合。

自然排序类型

在目录中创建一个名为 .pages 的文件，并将 sort_type 属性设置为 natural 以使用 自然排序顺序。

这可以与上面的 order 结合使用。

sort_type: natural

按优先级排序导航

在目录中创建一个名为 .pages 的文件，并将 order_by 属性设置为 filename 或 title 以更改导航项的顺序。

order_by: title

这可以与上面的 order 和/或 sort_type 结合使用。如果没有设置 order，则按升序排序。如果没有设置优先级，则按文件名排序。

折叠嵌套页面

注意： 此功能默认禁用。有关如何使用它的更多信息，请参阅以下内容

如果您有只包含单个页面的目录，awesome-pages 可以“折叠”它们，这样文件夹就不会出现在导航中。

例如，如果您有以下文件结构

docs/
├─ section1/
│  ├─ img/
│  │  ├─ image1.png
│  │  └─ image2.png
│  └─ index.md # Section 1
└─ section2/
   └─ index.md # Section 2

页面将在您的导航的根级别中显示

• 部分 1
• 部分 2

而不是MkDocs默认显示的方式

• 部分 1
  • 索引
• 部分 2
  • 索引

对于所有页面

可以使用 mkdocs.yml 中的 collapse_single_pages 选项 在全局范围内启用折叠。

对于子部分

如果您只想折叠某些页面，在目录中创建一个名为 .pages 的文件，并将 collapse_single_pages 设置为 true

collapse_single_pages: true

您还可以通过插件选项全局启用折叠，然后使用 .pages 文件来防止某些子部分被折叠，通过将 collapse_single_pages 设置为 false。

注意： 此功能是递归的。这意味着它也会折叠多级单个页面。

对于单个页面

如果您想单独启用或禁用单页的折叠功能，而不递归应用此设置，请在目录中创建一个名为 .pages 的文件，并将 collapse 设置为 true 或 false

collapse: true

隐藏目录

在目录中创建一个名为 .pages 的文件，并将 hide 属性设置为 true 以隐藏目录，包括所有子页和子节，从导航中

hide: true

注意： 此选项仅隐藏该部分从导航中。它仍然包含在构建中，并且可以通过其 URL 访问。

设置目录标题

在目录中创建一个名为 .pages 的文件，并将 title 设置为覆盖导航中该目录的标题

title: Page Title

排列页面

已弃用： arrange 将在下一个主要版本中删除 - 请使用 nav 代替.

在目录中创建一个名为 .pages 的文件，并将 arrange 属性设置为更改子页面在导航中出现的顺序。这对实际页面和子目录都有效。

title: Page Title
arrange:
    - page1.md
    - page2.md
    - subdirectory

如果您只指定 一些 页面，它们将被放置在开头，然后是其他页面按其原始顺序排列。

您还可以在某个位置包含一个 ... 条目，以指定其余页面应插入的位置

arrange:
    - introduction.md
    - ...
    - summary.md

在此示例中，introduction.md 被放置在开头，summary.md 在结尾，中间是任何其他页面。

合并自定义导航和文件结构

MkDocs 提供了两种定义导航结构的方法。您可以在 mkdocs.yml 中手动创建自定义导航，或使用文件结构来生成导航。此功能使得可以结合这两种方法。允许您手动定义导航的一部分，而无需列出所有文件。

注意： 您可以自由地结合此插件的所有其他功能。但是，它们只会影响未手动定义的导航部分。

使用 mkdocs.yml 中的 nav 条目来定义您导航的自定义部分。在您希望插入所有剩余页面导航树的位置包含一个 ... 条目。

以下示例基于此文件结构

docs/
├─ introduction.md
├─ page1.md
├─ page2.md
└─ folder/
   ├─ introduction.md
   ├─ page3.md
   └─ page4.md

如果您想将 introduction.md、page1.md 和 page2.md 显示在各自的节中，可以这样做

nav:
    - Start:
        - introduction.md
        - page1.md
        - page2.md
    - ...

这将导致以下导航

• 开始
  • 简介
  • 第1页
  • 第2页
• 文件夹
  • 简介
  • 第3页
  • 第4页

... 条目也可以放置在更深的级别

nav:
    - page1.md
    - Rest:
        - ...

这将导致以下导航

• 第1页
• 剩余部分
  • 简介
  • 第2页
  • 文件夹
    • 简介
    • 第3页
    • 第4页

此外，还可以使用 glob 模式或正则表达式来过滤剩余的项目。例如，仅匹配名为 introduction.md 的文件。

nav:
    - Introductions:
        - ... | **/introduction.md
    - ...

以下结果

• 简介
  • 简介
  • 简介
• 第1页
• 第2页
• 文件夹
  • 第3页
  • 第4页

注意： 模式与相对于文档目录的路径进行比较。

有关更多详细信息，请参阅下面的 剩余部分过滤模式 部分。

默认情况下，剩余项目保持其层次结构。您可以在匹配的页面中添加 flat 以扁平化所有匹配的页面

nav:
    - page1.md
    - Rest:
        - ... | flat | **/introduction.md
        - ... | flat

• 第1页
• 剩余部分
  • 简介
  • 简介
  • 第2页
  • 第3页
  • 第4页

剩余过滤器模式

在允许使用 rest 条目（...）的所有位置，您还可以包含 glob 模式或正则表达式来过滤要显示的项目。

nav:
    - ... | page-*.md
    - ... | regex=page-[0-9]+.md

过滤器仅对剩余项目操作。这意味着它不会包括在导航中明确列出或在配置中较早出现另一个过滤器的匹配项。

您还可以包含一个没有过滤器的 rest 条目作为通配符，插入所有未由过滤器匹配的项目。

语法细节

除非过滤器以regex=开头，否则它被解释为glob模式，但是您也可以使用glob=明确表示。在...周围的空格是可选的，但为了可读性建议使用。

注意：根据您的过滤器中的字符，您可能还需要在整条记录周围使用引号。

nav:
    # equivalent glob entries
    - ... | page-*.md
    - ... | glob=page-*.md
    - ...|page-*.md
    - '... | page-*.md'

    # equivalent regex entries
    - ... | regex=page-[0-9]+.md
    - ...|regex=page-[0-9]+.md
    - '... | regex=page-[0-9]+.md'

选项

您可以通过在mkdocs.yml中传递选项来自定义插件。

plugins:
    - awesome-pages:
        filename: .index
        collapse_single_pages: true
        strict: false
        order: asc
        sort_type: natural
        order_by: title

filename

用于配置目录页面的文件名。默认为.pages。

collapse_single_pages

启用单层页面的折叠。默认为false。

strict

当无法找到arrange条目时，引发错误而不是警告。

• nav条目无法找到时
• nav条目无法找到时

默认为true。

order、sort_type和order_by

全局回退值用于Meta属性。默认为None或filename。

贡献

从报告错误到提交拉取请求：每个贡献都受到赞赏和欢迎。使用Github issues报告错误、提出问题和请求功能。如果您想为这个项目的代码做出贡献，请阅读贡献指南。