尧图网站建设 
Material for MkDocs 导航配置完全指南从即时加载到面包屑的 14 项功能详解【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material一份清晰、简洁的导航结构是优秀项目文档的重要基石。Material for MkDocs本仓库即其完整源码实现围绕theme.features提供了十多项导航相关的配置选项涵盖导航选项卡、导航分组、即时加载等核心能力。读完本文你将掌握每项导航功能的 YAML 配置方法、适用场景、兼容性约束以及它们背后在仓库源码中的实际实现原理可以直接在自己的文档项目中组合出理想的信息架构。补充说明除下文介绍的theme.features导航配置外Material for MkDocs 还支持在页脚中配置额外导航tags 插件与blog 插件也会自动构建各自独立的导航层级。Instant loading让文档站拥有 SPA 般的无刷新体验即时加载是 Material for MkDocs 的标志性功能之一。启用后所有内部链接的点击事件都会被拦截页面内容通过 XHR 异步获取并原地注入无需整页刷新。在mkdocs.yml中加入theme: features: - navigation.instant开启后目标页面会被解析、注入且所有事件处理器与组件会自动重新绑定即Material for MkDocs 开始表现得像一个单页应用SPA。最直接的收益是搜索索引在页面切换后得以保留这对于大型文档站点尤为有用——用户不必每次跳转都重新等待搜索初始化。!!! info 必须设置site_url使用即时导航时必须同时配置 [site_url](https://www.mkdocs.org/user-guide/configuration/#site_url)因为即时导航依赖构建时生成的 sitemap.xml 来判定链接是否属于本站内部页面若省略该配置sitemap.xml 为空即时导航将无法工作。示例 yaml site_url: https://example.com 即时加载的底层实现从源码层面看即时加载由 src/templates/assets/javascripts/integrations/instant/index.ts 中的setupInstantNavigation驱动核心流程包含四个阶段导航拦截在document.body上通过事件冒泡统一监听click由handle()函数过滤事件——跳过非链接元素、带有target属性或按下meta/ctrl键新窗口打开的链接以及不在 sitemap 中的 URL例如跨版本、跨语言的链接。确认是站内链接后才调用ev.preventDefault()阻止浏览器默认跳转获取与解析对location$流使用switchMap请求 HTML——快速连续点击时自动取消上一个未完成的请求避免慢网络下加载无用页面请求失败则回退为常规整页跳转setLocation(url, true)。随后resolve()会把新文档中所有相对href/src解析为绝对地址防止 popstate 场景下相对基准错乱内容注入inject()将新文档中data-md-component标记的 announce、container、header-topic、outdated、logo、skip 等组件整体替换并同步head中的 meta 标签当启用navigation.tabs.sticky时还会额外替换 tabs 组件最后重放作者在 Markdown 中嵌入的script滚动恢复导航期间将history.scrollRestoration置为manual通过viewport$流去抖 100ms跟踪视口偏移量并写入history.replaceState从而在前进/后退时精确恢复滚动位置。Instant prefetch悬停即预取即时预取是一个实验性功能9.7.0 引入当用户把鼠标悬停到某个链接上时浏览器便提前开始获取该页面从而大幅降低感知加载时间在慢速网络下尤其明显。启用方式theme: features: - navigation.instant - navigation.instant.prefetch在源码中该功能监听document.body上的mousemove与focusin事件聚焦也能触发预取经 25ms 去抖、URL 去重后通过向head动态追加link relprefetch指示浏览器预取并使用exhaustMap保证加载不会过度挤占缓存见 src/templates/assets/javascripts/integrations/instant/index.ts。Progress indicator慢网络下的加载进度条进度指示器同样为实验性功能9.4.3 引入。开启后页面顶部会出现一条进度条直到页面加载完成才隐藏theme: features: - navigation.instant - navigation.instant.progress进度条只在页面加载超过 400ms 后才显示——这意味着快速连接下用户永远看不到它以保证即时体验不被进度条动画干扰。Instant previews不离开当前页的文档预览即时预览9.7.0实验性允许用户在不跳转的情况下预览本站其他文档页面的内容帮助用户保持上下文。你可以为任意头部链接header link添加data-preview属性来启用预览 markdown [Attribute Lists](#){>markdown_extensions: - material.extensions.preview: configurations: - targets: include: - changelog/index.md - customization.md - insiders/changelog/* - setup/extensions/*上面这段配置正是本仓库文档站点自身的用法为 changelog、customization 指南、Insiders 章节以及全部受支持的 Markdown 扩展页面开启了即时预览。完整的配置骨架如下sources与targets均可省略markdown_extensions: - material.extensions.preview: configurations: - sources: # (1)! include: - ... exclude: - ... targets: # (2)! include: - ... exclude: - ...sources指定在哪些页面上启用即时预览。省略时所有页面都会启用。支持用通配模式进行包含与排除排除在包含之上求值——若某页面同时命中包含与排除模式最终会被排除。此外configurations下可定义多个配置项从而精确控制即时预览的生效范围。targets指定指向哪些页面的链接启用即时预览这是推荐的启用方式。扩展的源码实现该扩展位于 src/extensions/preview.pyPreviewExtension注册了一个名为preview、优先级为 0 的 treeprocessorPreviewProcessor。它的工作方式很巧妙——依赖 MkDocs 在渲染前注册的relpathtreeprocessor 获取当前处理文件路径然后用sources过滤配置过滤当前页面不命中则跳过整页处理遍历文档中所有a元素跳过脚注引用footnote-ref与外部链接含 scheme 或 netloc 的 URL对剩余内部链接用targets过滤配置逐一匹配目标文件命中则给元素设置data-preview属性。其中的包含/排除过滤由 src/utilities/filter/init.py 的FileFilter实现基于fnmatch通配匹配文件的src_uri同样遵循先查 include、再查 excludeexclude 优先的求值顺序。全局启用即时预览如果想不加任何 data 属性、为所有头部链接启用预览可以全局开启theme: features: - navigation.instant.preview!!! info 必须设置site_url与即时加载一样即时预览同样依赖构建产物 sitemap.xml因此必须设置 [site_url](https://www.mkdocs.org/user-guide/configuration/#site_url)否则 sitemap.xml 为空、功能无法生效 yaml site_url: https://example.com Anchor tracking地址栏同步当前锚点启用锚点跟踪后浏览器地址栏中的 URL 会随目录TOC高亮的活动锚点自动更新theme: features: - navigation.tracking这对于需要复制当前阅读位置链接、或进行状态分享的场景非常实用。Navigation tabs导航选项卡启用选项卡后8.0.0 之前版本即 1.1.0 引入对于宽度超过 1220px的视口顶层章节会渲染在页头下方的一层菜单tab中移动端则保持原有形态。theme: features: - navigation.tabs!!! note 版本行为差异6.2.0 前后6.2.0 之前nav 中所有直接指向 *.md 文件的顶层页面会被归入第一个选项卡且以第一页标题命名导致无法把顶层页面或外部链接作为独立选项卡项见 issue #1884、#2072。从 6.2.0 起导航选项卡包含**所有**顶层页面与章节。Sticky navigation tabs吸顶选项卡启用吸顶后导航选项卡会锁定在页头下方滚动页面时始终可见theme: features: - navigation.tabs - navigation.tabs.sticky从模板源码 src/templates/partials/header.html 可以看到启用navigation.tabs.sticky时页头会附加md-header--shadow md-header--lifted类并把 tabs 局部模板直接包含进 header而在 src/templates/partials/nav.html 中启用navigation.tabs会给主导航附加md-nav--lifted类实现选项卡悬浮于侧边栏之上的布局。Navigation sections侧边栏导航分组启用分组后对于宽度超过 1220px的视口顶层章节会在侧边栏中渲染为分组组标题不可点击展开仅作分隔移动端保持原状。theme: features: - navigation.sectionsnavigation.tabs与navigation.sections可以同时开启此时第二级导航项会渲染为分组。这一组合行为在 src/templates/partials/nav-item.html 中有明确体现——两个功能同时启用时level 2且父级处于激活态的嵌套项会获得md-nav__item--section类。Navigation expansion默认展开全部子章节启用后左侧边栏会默认展开所有可折叠的子章节用户无需手动逐个展开theme: features: - navigation.expand实现上该功能通过给未激活的嵌套项 toggle 复选框设置md-toggle--indeterminate类使浏览器以半选中状态渲染复选框从而在首屏即展开全部层级见 src/templates/partials/nav-item.html。Navigation path页面标题上方的面包屑导航路径9.7.0实验性启用后会在每个页面的标题上方渲染面包屑导航对在小屏设备上浏览文档的用户尤其有助于定位theme: features: - navigation.path面包屑的渲染逻辑位于 src/templates/partials/path.html当页面祖先层级含首页总深度大于 1 时才渲染nav classmd-path依次输出首页与逆序的祖先项。Navigation pruning裁剪导航构建体积直降 33%导航裁剪9.2.0实验性启用后只有当前可见的导航项才会被包含在渲染出的 HTML 中构建站点体积可减少 33% 甚至更多theme: features: - navigation.prune # (1)!该功能与navigation.expand不兼容因为展开功能依赖完整的导航结构。这项功能对拥有 100 乃至 1000 页面的文档站点价值巨大——导航在 HTML 中占比可观。裁剪后所有可展开的章节会被替换为指向该章节第一个页面或章节索引页的链接。其实现可参见 src/templates/partials/nav-item.html非分组is_section且非激活nav_item.active的嵌套项被标记为md-nav__item--pruned并由render_pruned宏递归下降到第一个无子项的页面后输出为普通链接。Section index pages章节索引页启用章节索引页后文档可以直接挂载到章节上——非常适合为每个章节提供概述页theme: features: - navigation.indexes # (1)!该功能与toc.integrate不兼容因为章节没有足够空间容纳目录。要将页面挂载到章节只需在对应文件夹中新建名为index.md的文档并将其放在导航章节的开头nav: - Section: - section/index.md # (1)! - Page 1: section/page-1.md ... - Page n: section/page-n.mdMkDocs 同样会把名为README.md的文件视为索引页。从模板实现看src/templates/partials/nav-item.html启用该功能后渲染器会在章节的子项中查找is_index项并将其渲染为章节的链接 折叠开关组合容器。目录Table of contents的两项增强Anchor following目录自动跟随滚动启用锚点跟随8.5.0实验性后侧边栏会自动滚动使当前活动锚点始终可见theme: features: - toc.follow阅读长文时目录会像聚光灯一样持续高亮当前阅读位置。Navigation integration目录并入左侧导航启用目录整合6.2.0后目录始终作为左侧导航侧边栏的一部分渲染与页面导航同处一侧theme: features: - toc.integrate # (1)!该功能与navigation.indexes不兼容原因同上——章节空间不足以容纳目录。开启后主导航容器会附加md-nav--integrated类见 src/templates/partials/nav.html目录即随左侧导航一并渲染。有关目录本身的配置可参考目录扩展说明。Back-to-top button返回顶部按钮启用后当用户向下滚动、随后开始向上滚动时页面中央、页头正下方会出现一个返回顶部按钮theme: features: - navigation.top按钮模板见 src/templates/partials/top.html其图标可通过theme.icon.top自定义默认material/arrow-up。使用篇用 front matter 隐藏侧边栏与面包屑隐藏导航/目录侧边栏通过 Markdown 文件顶部的hide属性可针对单个文档隐藏导航和/或目录侧边栏--- hide: - navigation - toc --- # Page title ...隐藏面包屑面包屑默认显示在标题上方若想对特定页面隐藏同样使用hide属性--- hide: - path --- # Page title ...对应实现中src/templates/partials/path.html 会检查page.meta.hide中是否包含path命中即为nav设置hidden属性。定制篇键盘快捷键与内容区宽度键盘快捷键Material for MkDocs 内置多组键盘快捷键支持纯键盘浏览文档分为两种模式search 模式搜索框聚焦时生效arrow-down、arrow-up选择下一个 / 上一个搜索结果esc、tab关闭搜索对话框enter打开选中的结果global 模式搜索未聚焦、且没有其他可接收键盘输入的焦点元素时生效f、s、slash打开搜索对话框p、comma前往上一页n、period前往下一页如需自定义快捷键可通过附加 JavaScript 订阅keyboard$可观察对象并附加自定义事件监听器 docs/javascripts/shortcuts.js js keyboard$.subscribe(function(key) { if (key.mode global key.type x) { /* 在这里添加自定义键盘处理逻辑 */ key.claim() // (1)! } }) 1. 调用 key.claim() 会对底层事件执行 preventDefault()从而阻止按键事件继续传播、触发其他监听器。 mkdocs.yml yaml extra_javascript: - javascripts/shortcuts.js 内容区宽度默认情况下内容区宽度被限制为每行 80–100 个字符视字符宽度而定。这一默认值有利于阅读但如果你希望整体加宽内容区、甚至让它铺满整个可用空间可以通过附加样式表实现 docs/stylesheets/extra.css css .md-grid { max-width: 1440px; /* (1)! */ } 1. 若希望内容区始终铺满可用屏幕空间可重置 max-width css .md-grid { max-width: initial; } mkdocs.yml yaml extra_css: - stylesheets/extra.css 小结导航功能的组合策略从上面的配置项可以看出Material for MkDocs 的导航体系围绕theme.features提供了从加载体验instant、prefetch、progress、preview到信息架构tabs、sections、expand、path、prune、indexes再到阅读辅助tracking、toc.follow、toc.integrate、top的完整能力矩阵。组合时需特别注意两对互斥关系navigation.prune与navigation.expand、navigation.indexes与toc.integrate。小型站点推荐navigation.tabs navigation.indexes兼顾美观与概述页大型站点100 页面则建议navigation.prune navigation.instant在体积与体验上双赢。所有导航渲染逻辑均可从 src/templates/partials/nav-item.html 与 src/templates/partials/nav.html 的模板源码中一探究竟。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Material for MkDocs 导航配置完全指南：从即时加载到面包屑的 14 项功能详解
Material for MkDocs 导航配置完全指南从即时加载到面包屑的 14 项功能详解【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material一份清晰、简洁的导航结构是优秀项目文档的重要基石。Material for MkDocs本仓库即其完整源码实现围绕theme.features提供了十多项导航相关的配置选项涵盖导航选项卡、导航分组、即时加载等核心能力。读完本文你将掌握每项导航功能的 YAML 配置方法、适用场景、兼容性约束以及它们背后在仓库源码中的实际实现原理可以直接在自己的文档项目中组合出理想的信息架构。补充说明除下文介绍的theme.features导航配置外Material for MkDocs 还支持在页脚中配置额外导航tags 插件与blog 插件也会自动构建各自独立的导航层级。Instant loading让文档站拥有 SPA 般的无刷新体验即时加载是 Material for MkDocs 的标志性功能之一。启用后所有内部链接的点击事件都会被拦截页面内容通过 XHR 异步获取并原地注入无需整页刷新。在mkdocs.yml中加入theme: features: - navigation.instant开启后目标页面会被解析、注入且所有事件处理器与组件会自动重新绑定即Material for MkDocs 开始表现得像一个单页应用SPA。最直接的收益是搜索索引在页面切换后得以保留这对于大型文档站点尤为有用——用户不必每次跳转都重新等待搜索初始化。!!! info 必须设置site_url使用即时导航时必须同时配置 [site_url](https://www.mkdocs.org/user-guide/configuration/#site_url)因为即时导航依赖构建时生成的 sitemap.xml 来判定链接是否属于本站内部页面若省略该配置sitemap.xml 为空即时导航将无法工作。示例 yaml site_url: https://example.com 即时加载的底层实现从源码层面看即时加载由 src/templates/assets/javascripts/integrations/instant/index.ts 中的setupInstantNavigation驱动核心流程包含四个阶段导航拦截在document.body上通过事件冒泡统一监听click由handle()函数过滤事件——跳过非链接元素、带有target属性或按下meta/ctrl键新窗口打开的链接以及不在 sitemap 中的 URL例如跨版本、跨语言的链接。确认是站内链接后才调用ev.preventDefault()阻止浏览器默认跳转获取与解析对location$流使用switchMap请求 HTML——快速连续点击时自动取消上一个未完成的请求避免慢网络下加载无用页面请求失败则回退为常规整页跳转setLocation(url, true)。随后resolve()会把新文档中所有相对href/src解析为绝对地址防止 popstate 场景下相对基准错乱内容注入inject()将新文档中data-md-component标记的 announce、container、header-topic、outdated、logo、skip 等组件整体替换并同步head中的 meta 标签当启用navigation.tabs.sticky时还会额外替换 tabs 组件最后重放作者在 Markdown 中嵌入的script滚动恢复导航期间将history.scrollRestoration置为manual通过viewport$流去抖 100ms跟踪视口偏移量并写入history.replaceState从而在前进/后退时精确恢复滚动位置。Instant prefetch悬停即预取即时预取是一个实验性功能9.7.0 引入当用户把鼠标悬停到某个链接上时浏览器便提前开始获取该页面从而大幅降低感知加载时间在慢速网络下尤其明显。启用方式theme: features: - navigation.instant - navigation.instant.prefetch在源码中该功能监听document.body上的mousemove与focusin事件聚焦也能触发预取经 25ms 去抖、URL 去重后通过向head动态追加link relprefetch指示浏览器预取并使用exhaustMap保证加载不会过度挤占缓存见 src/templates/assets/javascripts/integrations/instant/index.ts。Progress indicator慢网络下的加载进度条进度指示器同样为实验性功能9.4.3 引入。开启后页面顶部会出现一条进度条直到页面加载完成才隐藏theme: features: - navigation.instant - navigation.instant.progress进度条只在页面加载超过 400ms 后才显示——这意味着快速连接下用户永远看不到它以保证即时体验不被进度条动画干扰。Instant previews不离开当前页的文档预览即时预览9.7.0实验性允许用户在不跳转的情况下预览本站其他文档页面的内容帮助用户保持上下文。你可以为任意头部链接header link添加data-preview属性来启用预览 markdown [Attribute Lists](#){>markdown_extensions: - material.extensions.preview: configurations: - targets: include: - changelog/index.md - customization.md - insiders/changelog/* - setup/extensions/*上面这段配置正是本仓库文档站点自身的用法为 changelog、customization 指南、Insiders 章节以及全部受支持的 Markdown 扩展页面开启了即时预览。完整的配置骨架如下sources与targets均可省略markdown_extensions: - material.extensions.preview: configurations: - sources: # (1)! include: - ... exclude: - ... targets: # (2)! include: - ... exclude: - ...sources指定在哪些页面上启用即时预览。省略时所有页面都会启用。支持用通配模式进行包含与排除排除在包含之上求值——若某页面同时命中包含与排除模式最终会被排除。此外configurations下可定义多个配置项从而精确控制即时预览的生效范围。targets指定指向哪些页面的链接启用即时预览这是推荐的启用方式。扩展的源码实现该扩展位于 src/extensions/preview.pyPreviewExtension注册了一个名为preview、优先级为 0 的 treeprocessorPreviewProcessor。它的工作方式很巧妙——依赖 MkDocs 在渲染前注册的relpathtreeprocessor 获取当前处理文件路径然后用sources过滤配置过滤当前页面不命中则跳过整页处理遍历文档中所有a元素跳过脚注引用footnote-ref与外部链接含 scheme 或 netloc 的 URL对剩余内部链接用targets过滤配置逐一匹配目标文件命中则给元素设置data-preview属性。其中的包含/排除过滤由 src/utilities/filter/init.py 的FileFilter实现基于fnmatch通配匹配文件的src_uri同样遵循先查 include、再查 excludeexclude 优先的求值顺序。全局启用即时预览如果想不加任何 data 属性、为所有头部链接启用预览可以全局开启theme: features: - navigation.instant.preview!!! info 必须设置site_url与即时加载一样即时预览同样依赖构建产物 sitemap.xml因此必须设置 [site_url](https://www.mkdocs.org/user-guide/configuration/#site_url)否则 sitemap.xml 为空、功能无法生效 yaml site_url: https://example.com Anchor tracking地址栏同步当前锚点启用锚点跟踪后浏览器地址栏中的 URL 会随目录TOC高亮的活动锚点自动更新theme: features: - navigation.tracking这对于需要复制当前阅读位置链接、或进行状态分享的场景非常实用。Navigation tabs导航选项卡启用选项卡后8.0.0 之前版本即 1.1.0 引入对于宽度超过 1220px的视口顶层章节会渲染在页头下方的一层菜单tab中移动端则保持原有形态。theme: features: - navigation.tabs!!! note 版本行为差异6.2.0 前后6.2.0 之前nav 中所有直接指向 *.md 文件的顶层页面会被归入第一个选项卡且以第一页标题命名导致无法把顶层页面或外部链接作为独立选项卡项见 issue #1884、#2072。从 6.2.0 起导航选项卡包含**所有**顶层页面与章节。Sticky navigation tabs吸顶选项卡启用吸顶后导航选项卡会锁定在页头下方滚动页面时始终可见theme: features: - navigation.tabs - navigation.tabs.sticky从模板源码 src/templates/partials/header.html 可以看到启用navigation.tabs.sticky时页头会附加md-header--shadow md-header--lifted类并把 tabs 局部模板直接包含进 header而在 src/templates/partials/nav.html 中启用navigation.tabs会给主导航附加md-nav--lifted类实现选项卡悬浮于侧边栏之上的布局。Navigation sections侧边栏导航分组启用分组后对于宽度超过 1220px的视口顶层章节会在侧边栏中渲染为分组组标题不可点击展开仅作分隔移动端保持原状。theme: features: - navigation.sectionsnavigation.tabs与navigation.sections可以同时开启此时第二级导航项会渲染为分组。这一组合行为在 src/templates/partials/nav-item.html 中有明确体现——两个功能同时启用时level 2且父级处于激活态的嵌套项会获得md-nav__item--section类。Navigation expansion默认展开全部子章节启用后左侧边栏会默认展开所有可折叠的子章节用户无需手动逐个展开theme: features: - navigation.expand实现上该功能通过给未激活的嵌套项 toggle 复选框设置md-toggle--indeterminate类使浏览器以半选中状态渲染复选框从而在首屏即展开全部层级见 src/templates/partials/nav-item.html。Navigation path页面标题上方的面包屑导航路径9.7.0实验性启用后会在每个页面的标题上方渲染面包屑导航对在小屏设备上浏览文档的用户尤其有助于定位theme: features: - navigation.path面包屑的渲染逻辑位于 src/templates/partials/path.html当页面祖先层级含首页总深度大于 1 时才渲染nav classmd-path依次输出首页与逆序的祖先项。Navigation pruning裁剪导航构建体积直降 33%导航裁剪9.2.0实验性启用后只有当前可见的导航项才会被包含在渲染出的 HTML 中构建站点体积可减少 33% 甚至更多theme: features: - navigation.prune # (1)!该功能与navigation.expand不兼容因为展开功能依赖完整的导航结构。这项功能对拥有 100 乃至 1000 页面的文档站点价值巨大——导航在 HTML 中占比可观。裁剪后所有可展开的章节会被替换为指向该章节第一个页面或章节索引页的链接。其实现可参见 src/templates/partials/nav-item.html非分组is_section且非激活nav_item.active的嵌套项被标记为md-nav__item--pruned并由render_pruned宏递归下降到第一个无子项的页面后输出为普通链接。Section index pages章节索引页启用章节索引页后文档可以直接挂载到章节上——非常适合为每个章节提供概述页theme: features: - navigation.indexes # (1)!该功能与toc.integrate不兼容因为章节没有足够空间容纳目录。要将页面挂载到章节只需在对应文件夹中新建名为index.md的文档并将其放在导航章节的开头nav: - Section: - section/index.md # (1)! - Page 1: section/page-1.md ... - Page n: section/page-n.mdMkDocs 同样会把名为README.md的文件视为索引页。从模板实现看src/templates/partials/nav-item.html启用该功能后渲染器会在章节的子项中查找is_index项并将其渲染为章节的链接 折叠开关组合容器。目录Table of contents的两项增强Anchor following目录自动跟随滚动启用锚点跟随8.5.0实验性后侧边栏会自动滚动使当前活动锚点始终可见theme: features: - toc.follow阅读长文时目录会像聚光灯一样持续高亮当前阅读位置。Navigation integration目录并入左侧导航启用目录整合6.2.0后目录始终作为左侧导航侧边栏的一部分渲染与页面导航同处一侧theme: features: - toc.integrate # (1)!该功能与navigation.indexes不兼容原因同上——章节空间不足以容纳目录。开启后主导航容器会附加md-nav--integrated类见 src/templates/partials/nav.html目录即随左侧导航一并渲染。有关目录本身的配置可参考目录扩展说明。Back-to-top button返回顶部按钮启用后当用户向下滚动、随后开始向上滚动时页面中央、页头正下方会出现一个返回顶部按钮theme: features: - navigation.top按钮模板见 src/templates/partials/top.html其图标可通过theme.icon.top自定义默认material/arrow-up。使用篇用 front matter 隐藏侧边栏与面包屑隐藏导航/目录侧边栏通过 Markdown 文件顶部的hide属性可针对单个文档隐藏导航和/或目录侧边栏--- hide: - navigation - toc --- # Page title ...隐藏面包屑面包屑默认显示在标题上方若想对特定页面隐藏同样使用hide属性--- hide: - path --- # Page title ...对应实现中src/templates/partials/path.html 会检查page.meta.hide中是否包含path命中即为nav设置hidden属性。定制篇键盘快捷键与内容区宽度键盘快捷键Material for MkDocs 内置多组键盘快捷键支持纯键盘浏览文档分为两种模式search 模式搜索框聚焦时生效arrow-down、arrow-up选择下一个 / 上一个搜索结果esc、tab关闭搜索对话框enter打开选中的结果global 模式搜索未聚焦、且没有其他可接收键盘输入的焦点元素时生效f、s、slash打开搜索对话框p、comma前往上一页n、period前往下一页如需自定义快捷键可通过附加 JavaScript 订阅keyboard$可观察对象并附加自定义事件监听器 docs/javascripts/shortcuts.js js keyboard$.subscribe(function(key) { if (key.mode global key.type x) { /* 在这里添加自定义键盘处理逻辑 */ key.claim() // (1)! } }) 1. 调用 key.claim() 会对底层事件执行 preventDefault()从而阻止按键事件继续传播、触发其他监听器。 mkdocs.yml yaml extra_javascript: - javascripts/shortcuts.js 内容区宽度默认情况下内容区宽度被限制为每行 80–100 个字符视字符宽度而定。这一默认值有利于阅读但如果你希望整体加宽内容区、甚至让它铺满整个可用空间可以通过附加样式表实现 docs/stylesheets/extra.css css .md-grid { max-width: 1440px; /* (1)! */ } 1. 若希望内容区始终铺满可用屏幕空间可重置 max-width css .md-grid { max-width: initial; } mkdocs.yml yaml extra_css: - stylesheets/extra.css 小结导航功能的组合策略从上面的配置项可以看出Material for MkDocs 的导航体系围绕theme.features提供了从加载体验instant、prefetch、progress、preview到信息架构tabs、sections、expand、path、prune、indexes再到阅读辅助tracking、toc.follow、toc.integrate、top的完整能力矩阵。组合时需特别注意两对互斥关系navigation.prune与navigation.expand、navigation.indexes与toc.integrate。小型站点推荐navigation.tabs navigation.indexes兼顾美观与概述页大型站点100 页面则建议navigation.prune navigation.instant在体积与体验上双赢。所有导航渲染逻辑均可从 src/templates/partials/nav-item.html 与 src/templates/partials/nav.html 的模板源码中一探究竟。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考