MkDocs 真棒页面插件

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

awesome-pages 插件允许您自定义页面如何显示 MkDocs 的导航，而无需在mkdocs.yml. 它使用直接放置在文档相关目录中的小型配置文件为您提供详细控制。

注意：mkdocs.yml如果你定义了一个nav或pages条目，这个插件不会做任何事情。要使用下面列出的功能，您必须完全删除该条目或添加一个...条目。

安装

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

使用 pip 安装软件包：

pip install mkdocs-awesome-pages-plugin

在您的mkdocs.yml：

plugins:
    - search
    - awesome-pages

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

MkDocs 文档中有关插件的更多信息

特征

自定义导航

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

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

休息

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

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

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

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

注意：模式是根据剩余项目的基本名称（文件夹/文件名）检查的，而不是它们的整个路径。

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

标题

您可以选择指定导航条目的标题。

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

注意：.pages为包含定义 a 的文件的目录指定标题title无效。

链接

您还可以使用该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

折叠单个嵌套页面

注意：默认情况下禁用此功能。更多关于如何在下面使用它

如果您的目录仅包含一个页面，则 awesome-pages 可以“折叠”它们，因此该文件夹不会显示在导航中。

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

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

这些页面将出现在您的导航中的根级别：

• 第 1 节
• 第 2 节

而不是 MkDocs 默认显示它们的方式：

• 第 1 节
  • 指数
• 第 2 节
  • 指数

对于所有页面

可以使用以下选项全局启用collapse_single_pages折叠mkdocs.yml

对于一个小节

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

collapse_single_pages: true

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

注意：此功能以递归方式工作。这意味着它还将折叠多个级别的单页。

对于单页

如果要启用或禁用单个页面的折叠，而不递归地应用设置，请在目录中创建一个名为.pages的文件并设置collapse为trueor false：

collapse: true

隐藏目录

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

hide: true

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

设置目录标题

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

title: Page Title

排列页面

已弃用： arrange将在下一个主要版本中删除 -改为使用nav。

创建一个.pages在目录中命名的文件并设置arrange属性以更改子页面在导航中的显示顺序。这适用于实际页面和子目录。

title: Page Title
安排：
    - page1.md 
    - page2.md 
    -子目录 

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

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

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

在此示例introduction.md中，位于开头、summary.md结尾以及介于两者之间的任何其他页面。

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

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

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

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

以下示例基于此文件结构：

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

如果你想要introduction.md，page1.md并page2.md出现在他们自己的部分下，你可以这样做：

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

这将导致以下导航：

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

该...条目也可以放在更深的层次：

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

这将导致以下导航：

• 第 1 页
• 休息
  • 介绍
  • 第2页
  • 文件夹
    • 介绍
    • 第 3 页
    • 第 4 页

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

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

结果如下：

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

注意：模式会根据相对于 docs 目录的路径进行检查。

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

默认情况下，其余项目保持其层次结构。您可以添加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：

插件：
    -真棒页面： 
        文件名：.index 
        collapse_single_pages: true
        严格：假 

filename

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

collapse_single_pages

启用单个嵌套页面的折叠。默认为false

strict

在以下情况下引发错误而不是警告：

• arrange找不到条目
• nav找不到条目

默认为true

贡献

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