Mkdocs 文档排序插件

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

项目地址: https://pypi.org/project/mkdocs-awesome-pages-plugin/

GitHub: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin

---

简介

mkdocs-awesome-pages-plugin 允许你通过简单的配置文件自定义 MkDocs 文档导航结构，而无需在 mkdocs.yml 中完整配置整个页面结构。只需在相关目录中放置一个小配置文件即可实现精细控制。

⚠️ 注意: 如果你的 mkdocs.yml 中定义了 nav 或 pages 条目，此插件将不会生效。你需要完全删除该条目，或在其中添加 ... 条目来结合自定义导航与文件结构。

---

安装

系统要求: Python >= 3.8.1，MkDocs >= 1.0

pip install mkdocs-awesome-pages-plugin

在 mkdocs.yml 中启用插件：

plugins:
  - search
  - awesome-pages

⚠️ 注意: 如果配置文件中之前没有 plugins 条目，MkDocs 默认会启用 search 插件。但一旦你定义了 plugins 条目，就需要显式添加 search 插件。

---

核心功能

1. 自定义导航 (.pages 文件)

在任意目录中创建名为 .pages 的文件，使用 nav 属性自定义该层级的导航顺序。

基本用法:

# docs/guide/.pages
nav:
  - subdirectory      # 子目录
  - page1.md          # 页面文件
  - page2.md

1.1 剩余项处理 (...)

未在列表中提及的页面或章节不会出现在导航中。使用 ... 条目指定剩余项的插入位置：

nav:
  - introduction.md   # 置顶
  - ...               # 其余文件按默认顺序
  - summary.md        # 置底

1.2 剩余项过滤

可以使用 glob 模式或正则表达式过滤剩余项：

nav:
  - ... | introduction-*.md    # 仅匹配以 introduction- 开头的 Markdown 文件
  - ...
  - summary.md

📌 注意: 模式匹配针对的是剩余项的basename（文件夹/文件名），而非完整路径。

1.3 自定义标题

为导航条目指定自定义标题：

nav:
  - ...
  - 第一页：page1.md

⚠️ 注意: 如果目录中包含定义了 title 的 .pages 文件，则为该目录指定标题无效。

1.4 添加外部链接

nav:
  - ...
  - 作者博客：https://lukasgeiter.com

1.5 创建分组

nav:
  - introduction.md
  - 第一节:
    - page1.md
    - page2.md
  - 第二节:
    - ...

---

2. 更改排序顺序

在 .pages 文件中设置 order 属性：

# 降序排列
order: desc

⚠️ 注意: 与默认排序不同，此设置不区分文件和目录，页面和章节可能会混排。

---

3. 自然排序

启用自然排序顺序（例如：file2 排在 file10 之前）：

sort_type: natural

可与 order 组合使用。

---

4. 排序大小写敏感性

默认排序区分大小写。设置为不区分：

ignore_case: true

---

5. 按偏好排序

使用 order_by 属性指定排序依据：

# 按标题排序（而非文件名）
order_by: title

可与 order 和/或 sort_type 组合使用。如果未设置 order，默认升序排列。

---

6. 折叠单层页面

如果某个目录只包含单个页面，可以"折叠"该目录，使其不在导航中显示文件夹。

示例文件结构:

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

折叠前 (MkDocs 默认):

- Section 1
  - Index
- Section 2
  - Index

折叠后:

- Section 1
- Section 2

6.1 全局启用

在 mkdocs.yml 中配置：

plugins:
  - awesome-pages:
      collapse_single_pages: true

6.2 针对子章节

在特定目录的 .pages 文件中：

collapse_single_pages: true

📌 注意: 此功能递归生效，会折叠多层级的单页面目录。

6.3 针对单个页面

# 仅控制当前目录，不递归
collapse: true

---

7. 隐藏目录

隐藏整个目录及其所有子页面和子章节：

hide: true

⚠️ 注意: 此选项仅从导航中隐藏章节，构建时仍会包含这些页面，可通过 URL 访问。

---

8. 设置目录标题

覆盖目录在导航中的显示标题：

title: 页面标题

---

9. 排列页面 (已弃用)

⚠️ 弃用警告: arrange 将在下一个主版本中移除，请使用 nav 替代。

title: 页面标题
arrange:
  - page1.md
  - page2.md
  - subdirectory

如果只指定部分页面，它们将置顶，其余页面保持原有顺序。

---

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

此功能允许你结合两种方法：在 mkdocs.yml 中手动定义部分导航，其余部分由文件结构自动生成。

文件结构示例:

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

示例 1: 自定义章节 + 自动剩余

# mkdocs.yml
nav:
  - 开始:
    - introduction.md
    - page1.md
    - page2.md
  - ...

结果:

- 开始
  - Introduction
  - Page 1
  - Page 2
- Folder
  - Introduction
  - Page 3
  - Page 4

示例 2: 深层剩余项

nav:
  - page1.md
  - 其余:
    - ...

结果:

- Page 1
- 其余
  - Introduction
  - Page 2
  - Folder
    - Introduction
    - Page 3
    - Page 4

示例 3: 过滤剩余项

nav:
  - 介绍:
    - ... | **/introduction.md
  - ...

结果:

- 介绍
  - Introduction (根目录)
  - Introduction (folder 内)
- Page 1
- Page 2
- Folder
  - Page 3
  - Page 4

📌 注意: 此处的模式匹配针对的是相对于 docs 目录的路径。

示例 4: 扁平化剩余项

nav:
  - page1.md
  - 其余:
    - ... | flat | **/introduction.md
    - ... | flat

结果:

- Page 1
- 其余
  - Introduction (根目录)
  - Introduction (folder 内)
  - Page 2
  - Page 3
  - Page 4

---

剩余项过滤模式详解

在任何允许 ... 条目的地方，都可以使用 glob 模式或正则表达式过滤剩余项：

nav:
  - ... | page-*.md              # glob 模式
  - ... | regex=page-[0-9]+.md   # 正则表达式

过滤器仅作用于剩余项，不会包含已显式列出的条目或被先前过滤器匹配的项。

语法详情

• 除非以 regex= 开头，否则默认为 glob 模式
• 也可显式使用 glob= 声明
• ... 周围的空格可选，但建议保留以提高可读性

nav:
  # 等价的 glob 写法
  - ... | page-*.md
  - ... | glob=page-*.md
  - ...|page-*.md
  - '... | page-*.md'

  # 等价的 regex 写法
  - ... | 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               # 按标题排序
      ignore_case: true             # 忽略大小写

选项说明

选项	默认值	说明
filename	.pages	用于配置目录页面的文件名
collapse_single_pages	false	全局启用单层页面折叠
strict	true	设为 false 时，arrange/nav 条目找不到时仅警告而非报错
order	None	全局默认排序（升序/降序）
sort_type	None	全局排序类型（natural 或默认）
order_by	filename	全局排序依据（filename 或 title）
ignore_case	false	全局大小写敏感性设置

---

快速参考

常用 .pages 配置模板

基础排序:

nav:
  - intro.md
  - ...
  - summary.md

按标题自然排序:

order: asc
sort_type: natural
order_by: title
ignore_case: true

折叠单页面目录:

collapse_single_pages: true

隐藏敏感章节:

hide: true

自定义目录标题:

title: API 参考文档