配置导航

清晰简明的导航结构是良好项目文档的重要组成部分。Material for MkDocs 提供了多种选项来配置导航元素的行为，包括选项卡和章节，以及其旗舰功能之一：即时加载。

配置

即时加载

功能标志

启用即时加载后，单击所有内部链接将被拦截并通过XHR分发，而无需完全重新加载页面。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.instant

解析并注入生成的页面，所有事件处理程序和组件将自动重新绑定，即Material for MkDocs 现在的行为类似于单页应用程序。现在，搜索索引在导航过程中保留，这对于大型文档站点特别有用。

即时预取：于 2023 年 6 月 15 日添加

仅限赞助商 | 实验性

即时预取是一个新的实验性功能，当用户将鼠标悬停在链接上时，它将开始获取页面。这将减少用户的感知加载时间，特别是在网络连接较慢的情况下，因为页面将在导航后立即可用。使用以下配置启用它：

theme:
  features:
    - navigation.instant
    - navigation.instant.prefetch

锚点跟踪

功能标志

启用锚点跟踪后，地址栏中的 URL 将自动更新为目录中突出显示的活动锚点。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.tracking

导航选项卡

功能标志

启用选项卡后，顶级章节将在视口宽度大于1220px时以菜单层形式呈现在标题下方，但在移动设备上保持不变。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.tabs

启用选项卡

禁用

固定导航选项卡

功能标志

启用固定选项卡后，导航选项卡将在标题下方锁定，并在向下滚动时始终保持可见。只需在mkdocs.yml中添加以下两个功能标志：

theme:
  features:
    - navigation.tabs
    - navigation.tabs.sticky

启用固定选项卡

禁用

导航章节

功能标志

启用章节后，顶级章节将在视口宽度大于1220px时作为侧边栏中的组呈现，但在移动设备上保持不变。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.sections

启用章节

禁用

navigation.tabs和navigation.sections两个功能标志可以相互组合。如果同时启用了两个功能标志，则会为 2 级导航项呈现章节。

导航展开

功能标志

启用展开后，左侧侧边栏将默认展开所有可折叠的子节，因此用户无需手动打开子节。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.expand

启用展开

禁用

仅限赞助商 | 实验性

启用导航路径后，将在每个页面标题上方呈现一个面包屑导航，这对于在较小屏幕的设备上访问您的文档的用户来说可能更容易定位。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.path

启用导航路径

禁用

导航修剪

实验性

启用修剪后，只有可见的导航项将包含在渲染的 HTML 中，将内置站点的大小减小 33%或更多。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.prune # (1)!

此功能标志与navigation.expand不兼容，因为导航展开需要完整的导航结构。

对于包含 100 个或甚至 1000 个页面的文档站点，此功能标志特别有用，因为导航占据了 HTML 的重要部分。导航修剪将所有可展开的章节替换为指向该章节中的第一页（或章节索引页）的链接。

章节索引页

功能标志

启用章节索引页后，可以直接将文档附加到章节中，这对于提供概览页面特别有用。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.indexes # (1)!

此功能标志与toc.integrate不兼容，因为由于空间不足，章节无法承载目录。

启用章节索引页

禁用

为了将页面链接到章节，请在相应的文件夹中创建一个名为index.md的新文档，并将其添加到导航节的开头：

nav:
  - 章节:
    - section/index.md # (1)!
    - 页面 1: section/page-1.md
    ...
    - 页面 n: section/page-n.md

MkDocs 还将名为README.md的文件视为索引页。

返回顶部按钮

功能标志

当用户在向上滚动后再次开始向上滚动时，可以显示返回顶部按钮。它以居中的方式呈现在标题下方。在mkdocs.yml中添加以下行：

theme:
  features:
    - navigation.top

用法

隐藏侧边栏

可以使用前置属性hide为文档隐藏导航和/或目录侧边栏。在 Markdown 文件的顶部添加以下行：

---
hide:
  - navigation
  - toc
---
# 文档标题

隐藏导航

隐藏目录

隐藏两者

隐藏导航路径

虽然导航路径在主标题上方呈现，但有时可能希望在特定页面上隐藏它，可以通过前置属性hide实现：

---
hide:
  - path
---
# 文档标题

自定义

键盘快捷键

Material for MkDocs 包括几个键盘快捷键，使您可以通过键盘导航项目文档。有两种模式：

search

当搜索聚焦时，此模式处于活动状态。它提供了几个键绑定，使搜索可通过键盘访问和导航：

* ++arrow-down++ , ++arrow-up++ ：选择下一个/上一个结果
* ++esc++ , ++tab++ ：关闭搜索对话框
* ++enter++ ：跟随选定的结果

global

当搜索未聚焦且没有其他聚焦的元素可以接受键盘输入时，此模式处于活动状态。以下键已绑定：

* ++f++ , ++s++ , ++slash++ ：打开搜索对话框
* ++p++ , ++comma++ ：转到上一页
* ++n++ , ++period++ ：转到下一页

假设您想要将某个操作绑定到X键。通过使用[附加的 JavaScript]，您可以订阅keyboard可观察对象并附加自定义事件侦听器：

docs/javascripts/shortcuts.js

keyboard$.subscribe(function(key) {
  if (key.mode !!! info "global" && key.type !!! info "x") {
    /* 在此处添加自定义键盘处理程序 */
    key.claim() // (1)!
  }
})

调用key.claim()将在底层事件上执行preventDefault()，因此按键将不会进一步传播并触发其他事件侦听器。

mkdocs.yml

extra_javascript:
  - javascripts/shortcuts.js

内容区域宽度

内容区域的宽度设置为每行的长度不超过 80-100 个字符，具体取决于字符的宽度。虽然这是一个合理的默认值，因为较长的行往往更难阅读，但可能希望增加内容区域的整体宽度，甚至使其延伸到整个可用空间。

这可以通过附加样式表和几行 CSS 轻松实现：

docs/stylesheets/extra.css

.md-grid {
  max-width: 1440px; /* (1)! */
}

如果希望内容区域始终延伸到可用的屏幕空间，请使用以下CSS重置max-width：
```
.md-grid {
  max-width: initial;
}
```

mkdocs.yml

extra_css:
  - stylesheets/extra.css

配置导航

配置

即时加载

即时预取：于 2023 年 6 月 15 日添加

锚点跟踪

导航选项卡

固定导航选项卡

导航章节

导航展开

导航路径面包屑

导航修剪

章节索引页

目录

锚点跟随

导航集成

返回顶部按钮

用法

隐藏侧边栏

隐藏导航路径

自定义

键盘快捷键

内容区域宽度