设置导航¶
清晰简洁的导航结构是良好项目文档的重要方面。Material for MkDocs 提供了多种选项来配置导航元素的行为，包括 tabs 和 sections，以及其旗舰特性之一：instant loading。
额外的导航可以在 [footer] 中配置，以及使用 tags plugin。 blog plugin 也会设置额外的导航。
配置¶
即时加载¶
启用即时加载后，所有内部链接的点击将被拦截，并通过 XHR 分发，而无需完全重新加载页面。将以下行添加到 mkdocs.yml：
生成的页面会被解析和注入，所有事件处理程序和组件会自动重新绑定，即 Material for MkDocs 现在表现得像一个单页面应用程序。现在，搜索索引在导航中得以保留，这对于大型文档网站尤其有用。
即时预取¶
即时预取是一项新的实验性功能，当用户悬停在链接上时，它将开始获取页面。这将减少用户的感知加载时间，尤其是在慢速连接上，因为页面在导航时将立即可用。通过以下方式启用：
进度指示器¶
为了在使用即时导航时为慢速连接提供更好的用户体验，可以启用进度指示器。它将在页面顶部显示，并在页面完全加载后隐藏。您可以在 mkdocs.yml 中通过以下方式启用：
进度指示器仅在页面在 400 毫秒后尚未完成加载时显示，因此快速连接将不会显示它，以提供更好的即时体验。
即时预览¶
即时预览是一项全新的功能，允许用户在不导航到其他页面的情况下预览文档的另一部分。它们对于保持用户的上下文非常有帮助。可以在任何带有 data-preview 属性的标题链接上启用即时预览：
限制
即时预览仍然是一项实验性功能，目前仅限于标题链接。这意味着，您可以在指向其他页面标题的任何内部链接上使用它，但不能在具有 id 属性的其他元素上使用。在我们收集到足够的反馈后，我们将考虑将此功能扩展到其他可能的任意元素。
自动预览¶
使用 Material for MkDocs 中包含的 Markdown 扩展是处理即时预览的推荐方式，因为它允许您在文档的每个页面或每个部分级别启用即时预览：
markdown_extensions:
- material.extensions.preview:
configurations:
- targets:
include:
- changelog/index.md
- customization.md
- insiders/changelog/*
- setup/extensions/*
上述配置是我们用于文档的配置。我们已为我们的变更日志、自定义指南和内部人员部分启用了即时预览，以及我们支持的所有 Markdown 扩展。
完整配置示例
markdown_extensions:
- material.extensions.preview:
configurations:
- sources: # (1)!
include:
- ...
exclude:
- ...
targets: # (2)!
include:
- ...
exclude:
- ...
-
Sources 指定应启用即时预览的页面。如果省略此设置，则将在所有页面上启用即时预览。您可以使用模式来包含或排除页面。排除在包含之上进行评估，因此如果一个页面同时被包含和排除，则将被排除。
请注意，您可以在
configurations设置下定义多个项目，这允许精确控制在哪里显示即时预览。 -
Targets 指定应启用即时预览的页面。这是启用即时预览的推荐方式。
即时预览也可以通过将以下行添加到 mkdocs.yml 全局启用，这将为所有标题链接启用即时预览，减轻添加数据属性的需要：
锚点跟踪¶
启用锚点跟踪后，地址栏中的 URL 将自动更新为活动锚点，如目录中所突出显示的。将以下行添加到 mkdocs.yml：
导航标签¶
当启用标签时，顶级部分将在 1220px 以上的视口中呈现在标题下方的菜单层中，但在移动设备上保持不变。1 将以下行添加到 mkdocs.yml：
粘性导航标签¶
当启用粘性标签时，导航标签将在标题下方锁定，并在向下滚动时始终保持可见。只需将以下两个功能标志添加到 mkdocs.yml：
导航部分¶
当启用部分时，顶级部分将在 1220px 以上的视口中作为组呈现在侧边栏中，但在移动设备上保持不变。将以下行添加到 mkdocs.yml：
这两个功能标志 navigation.tabs 和 navigation.sections 可以相互结合。如果同时启用这两个功能标志，则为级别 2 的导航项呈现部分。
导航扩展¶
当启用扩展时，左侧边栏将默认展开所有可折叠的子部分，因此用户不必手动打开子部分。将以下行添加到 mkdocs.yml：
导航路径 面包屑¶
当激活导航路径时，在每个页面标题上方呈现面包屑导航，这可能会使访问您文档的用户在小屏幕设备上更容易定位。将以下行添加到 mkdocs.yml：
导航修剪¶
当启用修剪时，仅包含可见的导航项在渲染的 HTML 中，减少构建站点的大小 33% 或更多。将以下行添加到 mkdocs.yml：
- 此功能标志与
navigation.expand不兼容，因为导航扩展需要完整的导航结构。
此功能标志对于具有 100+ 或甚至 1,000+ 页的文档网站特别有用，因为导航占 HTML 的显著比例。导航修剪将用指向该部分中第一页（或部分索引页面）的链接替换所有可展开的部分。
部分索引页面¶
当启用部分索引页面时，文档可以直接附加到部分，这对于提供概述页面特别有用。将以下行添加到 mkdocs.yml：
- 此功能标志与
toc.integrate不兼容，因为部分无法由于空间不足而容纳目录。
要将页面链接到部分，请在相应文件夹中创建一个名为 index.md 的新文档，并将其添加到导航部分的开头：
nav:
- Section:
- section/index.md # (1)!
- Page 1: section/page-1.md
...
- Page n: section/page-n.md
- MkDocs 还将名为
README.md的文件视为 [索引页面]。
目录¶
锚点跟随¶
当启用 目录 的锚点跟随时，侧边栏会自动滚动，以便活动锚点始终可见。将以下行添加到 mkdocs.yml：
导航集成¶
当启用 目录 的导航集成时，它始终作为左侧导航侧边栏的一部分呈现。将以下行添加到 mkdocs.yml：
- 此功能标志与
navigation.indexes不兼容，因为部分无法由于空间不足而容纳目录。
返回顶部按钮¶
当用户在向下滚动后开始向上滚动时，可以显示返回顶部按钮。它在标题下方居中呈现。将以下行添加到 mkdocs.yml：
使用¶
隐藏侧边栏¶
可以通过文档的前置内容 hide 属性隐藏导航和/或目录侧边栏。在 Markdown 文件的顶部添加以下行：
隐藏导航路径¶
虽然 [导航路径] 在主标题上方呈现，但有时可能希望为特定页面隐藏它，这可以通过前置内容 hide 属性实现：
自定义¶
键盘快捷键¶
Material for MkDocs 包含几种键盘快捷键，使您可以通过键盘导航项目文档。共有两种模式：
search-
当 搜索被聚焦 时，此模式处于活动状态。它提供了几种键绑定，使搜索可以通过键盘访问和导航：
- Down , Up : 选择下一个/上一个结果
- Esc , Tab : 关闭搜索对话框
- Enter : 跟随选定结果
global-
当 搜索未聚焦 且没有其他可接受键盘输入的聚焦元素时，此模式处于活动状态。以下键被绑定：
- F , S , / : 打开搜索对话框
- P , , : 转到上一页
- N , . : 转到下一页
假设您想将某个操作绑定到 X 键。通过使用 additional JavaScript，您可以订阅 keyboard$ 可观察对象并附加自定义事件监听器：
内容区域宽度¶
内容区域的宽度设置为每行长度不超过 80-100 个字符，具体取决于字符的宽度。虽然这是一个合理的默认值，因为较长的行往往更难阅读，但可能希望增加内容区域的整体宽度，甚至使其延伸到整个可用空间。
这可以通过 additional style sheet 和几行 CSS 轻松实现：