mkdocs-material 页面元数据完全指南使用 front matter 配置标题、描述、图标、状态与模板【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMaterial for MkDocs 内置了大量提升技术写作体验的特性而页面级元数据Metadata正是其中的基础能力通过在每个 Markdown 文件顶部的 YAML front matter 中声明title、description、icon、status、subtitle、template等属性即可精确控制页面的title、meta标签、导航侧边栏的展示效果以及整页模板的选择。读完本文你将掌握如何在当前项目中为每个页面配置这些元数据属性、如何借助内置 meta 插件为整个目录批量设置默认值以及如何在模板重写中利用page.meta对象实现搜索引擎索引策略等高级定制。元数据机制概述在 Material for MkDocs 中每个 Markdown 文件顶部的 YAML front matter 会被解析为页面的元数据对象即模板中的page.meta主题在构建时会将其中一部分属性映射到生成页面的 HTML 结构上。以 基础模板 为例head区域内的site_meta与htmltitle两个 Jinja block 会直接消费这些元数据{% if page.meta and page.meta.title %} title{{ page.meta.title }} - {{ config.site_name }}/title {% elif page.title and not page.is_homepage %} title{{ page.title | striptags }} - {{ config.site_name }}/title {% else %} title{{ config.site_name }}/title {% endif %}同理description属性会生成meta namedescription标签并在未显式定义时回退到mkdocs.yml中的site_description参见 src/templates/base.html。这意味着页面元数据是主题与文档内容之间最重要的契约理解它就能掌控站点 SEO、社交分享卡片和导航体验。设置页面title每个页面都有一个指定标题它会被用于导航侧边栏、社交卡片 以及其他位置。虽然 MkDocs 会通过四步流程自动推断页面标题你也可以用 front matter 中的title属性显式覆盖--- title: Lorem ipsum dolor sit amet # (1)! --- # Page title ...该行会将title写入生成页面的 HTML 文档head中的title标签。注意站点名称由site_name配置会以破折号的形式追加在页面标题之后最终渲染效果类似页面标题 - 站点名称。这一点在 src/templates/base.html 的htmltitleblock 中得到了印证当page.meta.title存在时优先使用它否则回退到页面自身的标题去除 HTML 标签后若两者皆无如首页则直接使用config.site_name。因此显式设置title的场景主要包括页面标题过长需要截断、包含特殊字符需要控制展示、或希望搜索引擎索引的标题与正文一级标题不同。设置页面descriptionMarkdown 文件可以在 front matter 中声明description它会被写入页面的meta标签同时也会被 社交卡片 功能消费。建议在mkdocs.yml中设置site_description作为兜底值以便作者未显式定义时仍有合理的站点级描述--- description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! --- # Page title ...该行会在当前页面的文档head中写入包含该描述的meta标签。从源码来看src/templates/base.html 的优先级逻辑是page.meta.description优先其次才是config.site_description。这对 SEO 尤为重要——每个页面拥有独立且贴合内容的描述能显著提升搜索引擎对页面的理解与摘要质量。设置页面icon实验性功能 · 自 9.2.0 版本起可用每个页面都可以分配一个图标它将作为导航侧边栏的一部分被渲染如果启用了 navigation tabs也会显示在导航标签页中。在 Markdown 文件顶部加入 front mattericon属性即可--- icon: material/emoticon-happy # (1)! --- # Page title ...输入几个关键词即可使用 图标搜索 找到合适的图标点击短代码即可复制到剪贴板。底层实现位于 src/templates/partials/nav-item.html渲染导航项时若nav_item.meta.icon存在主题会include对应的 SVG 文件{% if nav_item.meta and nav_item.meta.icon %} {% include .icons/ ~ nav_item.meta.icon ~ .svg %} {% endif %}因此icon的值必须与.icons目录下的图标路径精确对应例如material/emoticon-happy、fontawesome/solid/bug等。该功能默认未开启表情符号扩展时也可独立工作因为它直接引用主题自带的图标集合。设置页面status实验性功能 · 自 9.2.0 版本起可用状态标识status会被显示在导航侧边栏中用于快速标记新页面已废弃等语义。使用分两步首先在mkdocs.yml的extra.status中将状态标识符identifier与一段描述文本关联起来extra: status: identifier: description # (1)!标识符只能包含字母、数字、短横线-和下划线_。例如要为页面标记Recently added可以定义标识符newextra: status: new: Recently added然后在页面 front matter 中用status属性引用该标识符即可将页面标记为new--- status: new --- # Page title ...主题已经预置了以下两个状态标识符:material-alert-decagram: –new:material-trash-can: –deprecated这两个内置状态的图标定义可以在 src/templates/assets/stylesheets/main/components/_status.scss 中看到--md-status--new使用material/alert-decagram.svg警示星形图标--md-status--deprecated使用material/trash-can.svg垃圾桶图标。当前项目自身的 mkdocs.yml 也配置了这两个状态extra: status: new: Recently added deprecated: Deprecated自定义状态标识符你也可以定义自定义的页面状态但如果希望自定义状态使用默认图标以外的其他图标就需要在extra.css中额外配置例如定义--md-status--identifier对应的 mask-image主题官方提供了一个自定义页面状态示例可供参考。状态渲染的源码细节从 src/templates/partials/nav-item.html 可以看到render_status宏的完整逻辑当config.extra.status[type]存在时状态徽章会带上描述文本作为title属性悬停即显示 tooltip否则只渲染一个无说明的图标。同时src/templates/partials/nav-item.html 会读取nav_item.meta.status来为当前导航项渲染对应状态徽章。此外ellipsis 补丁 在启用了content.tooltips功能时会将.md-status元素挂载为内联 tooltip让状态描述以提示气泡的形式呈现。设置页面subtitle实验性功能 · 自 9.6.0 版本起可用每个页面都可以定义一个副标题subtitle它会以标题下方的次要文本形式渲染在导航侧边栏中。使用 front matter 的subtitle属性即可--- subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor --- # Page title ...在 src/templates/partials/nav-item.html 中副标题被渲染为small元素{% if nav_item.meta and nav_item.meta.subtitle %} br / small{{ nav_item.meta.subtitle }}/small {% endif %}副标题非常适合在大型文档站点中补充说明页面所属模块、适用版本或简短摘要让读者在展开导航的一瞬间就能判断该页面是否值得点入。设置页面template如果你正在使用主题扩展并在overrides目录中创建了新的页面模板就可以通过 front matter 的template属性为某个特定页面启用它--- template: custom.html --- # Page title ...为整个目录批量设置模板??? question 如何为一个文件夹下的所有页面设置模板借助内置的 [meta 插件](https://link.gitcode.com/i/7ae3d3e9326706d6ccf8e948cd9c8832)你可以为整个章节及其所有嵌套页面设置自定义模板在对应文件夹中创建一个 .meta.yml 文件内容如下 yaml template: custom.html 这正是 meta 插件的核心价值。从源码看src/plugins/meta/plugin.py 会在on_files阶段扫描docs目录下的.meta.yml文件名由meta_file配置项控制将其解析为 YAML 并记录到内部映射中随后在on_page_markdown事件优先级 50确保尽早执行阶段按目录层级由浅到深、以类型安全追加TYPESAFE_ADDITIVE策略合并所有相关 meta 文件最后再合并页面自身的 front matter确保页面级元数据始终优先于目录级默认值参见 src/plugins/meta/plugin.py。也就是说.meta.yml提供默认值页面 front matter 可覆盖甚至删除默认值两者互补。在模板中使用元数据为所有页面添加自定义 meta 标签如果你想为所有页面统一添加自定义meta标签可以扩展主题并重写extraheadblock。例如为搜索引擎添加robots索引策略{% extends base.html %} {% block extrahead %} meta namerobots contentnoindex, nofollow / {% endblock %}从 src/templates/base.html 可以看到extraheadblock 位于head的末尾、所有主题内置 meta 标签之后因此非常适合追加自定义标签且不会破坏主题默认行为。为单个页面设置不同 meta 标签如果你只想在单个页面上设置meta标签或希望不同页面使用不同的值可以在模板重写中使用page.meta对象。例如{% extends base.html %} {% block extrahead %} {% if page and page.meta and page.meta.robots %} meta namerobots content{{ page.meta.robots }} / {% else %} meta namerobots contentindex, follow / {% endif %} {% endblock %}此后robots就可以像title和description一样通过 front matter 直接赋值--- robots: noindex, nofollow ---注意在这个例子中模板定义了一个else分支因此在未提供robots元数据时页面会回退到默认值index, follow。这是默认值 按页覆盖模式的典型实践与 meta 插件的合并策略思路一致模板中的条件分支充当兜底front matter 中的具体值负责定制。元数据优先级总结综合以上内容Material for MkDocs 的页面元数据遵循清晰的优先级体系页面 front matter优先级最高直接作用于当前页面目录级.meta.yml默认值由 meta 插件合并次之页面 front matter 可以覆盖它站点级配置如site_description、site_name作为兜底仅在页面与目录均未定义时生效MkDocs 自动推断如标题的四步推断流程处于最底层。掌握这套优先级你就能在保证站点整体一致性的前提下为每个页面灵活定制标题、描述、图标、状态与模板从而获得更好的搜索引擎可见性、社交分享效果与导航体验。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mkdocs-material 页面元数据完全指南：使用 front matter 配置标题、描述、图标、状态与模板
mkdocs-material 页面元数据完全指南使用 front matter 配置标题、描述、图标、状态与模板【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-materialMaterial for MkDocs 内置了大量提升技术写作体验的特性而页面级元数据Metadata正是其中的基础能力通过在每个 Markdown 文件顶部的 YAML front matter 中声明title、description、icon、status、subtitle、template等属性即可精确控制页面的title、meta标签、导航侧边栏的展示效果以及整页模板的选择。读完本文你将掌握如何在当前项目中为每个页面配置这些元数据属性、如何借助内置 meta 插件为整个目录批量设置默认值以及如何在模板重写中利用page.meta对象实现搜索引擎索引策略等高级定制。元数据机制概述在 Material for MkDocs 中每个 Markdown 文件顶部的 YAML front matter 会被解析为页面的元数据对象即模板中的page.meta主题在构建时会将其中一部分属性映射到生成页面的 HTML 结构上。以 基础模板 为例head区域内的site_meta与htmltitle两个 Jinja block 会直接消费这些元数据{% if page.meta and page.meta.title %} title{{ page.meta.title }} - {{ config.site_name }}/title {% elif page.title and not page.is_homepage %} title{{ page.title | striptags }} - {{ config.site_name }}/title {% else %} title{{ config.site_name }}/title {% endif %}同理description属性会生成meta namedescription标签并在未显式定义时回退到mkdocs.yml中的site_description参见 src/templates/base.html。这意味着页面元数据是主题与文档内容之间最重要的契约理解它就能掌控站点 SEO、社交分享卡片和导航体验。设置页面title每个页面都有一个指定标题它会被用于导航侧边栏、社交卡片 以及其他位置。虽然 MkDocs 会通过四步流程自动推断页面标题你也可以用 front matter 中的title属性显式覆盖--- title: Lorem ipsum dolor sit amet # (1)! --- # Page title ...该行会将title写入生成页面的 HTML 文档head中的title标签。注意站点名称由site_name配置会以破折号的形式追加在页面标题之后最终渲染效果类似页面标题 - 站点名称。这一点在 src/templates/base.html 的htmltitleblock 中得到了印证当page.meta.title存在时优先使用它否则回退到页面自身的标题去除 HTML 标签后若两者皆无如首页则直接使用config.site_name。因此显式设置title的场景主要包括页面标题过长需要截断、包含特殊字符需要控制展示、或希望搜索引擎索引的标题与正文一级标题不同。设置页面descriptionMarkdown 文件可以在 front matter 中声明description它会被写入页面的meta标签同时也会被 社交卡片 功能消费。建议在mkdocs.yml中设置site_description作为兜底值以便作者未显式定义时仍有合理的站点级描述--- description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! --- # Page title ...该行会在当前页面的文档head中写入包含该描述的meta标签。从源码来看src/templates/base.html 的优先级逻辑是page.meta.description优先其次才是config.site_description。这对 SEO 尤为重要——每个页面拥有独立且贴合内容的描述能显著提升搜索引擎对页面的理解与摘要质量。设置页面icon实验性功能 · 自 9.2.0 版本起可用每个页面都可以分配一个图标它将作为导航侧边栏的一部分被渲染如果启用了 navigation tabs也会显示在导航标签页中。在 Markdown 文件顶部加入 front mattericon属性即可--- icon: material/emoticon-happy # (1)! --- # Page title ...输入几个关键词即可使用 图标搜索 找到合适的图标点击短代码即可复制到剪贴板。底层实现位于 src/templates/partials/nav-item.html渲染导航项时若nav_item.meta.icon存在主题会include对应的 SVG 文件{% if nav_item.meta and nav_item.meta.icon %} {% include .icons/ ~ nav_item.meta.icon ~ .svg %} {% endif %}因此icon的值必须与.icons目录下的图标路径精确对应例如material/emoticon-happy、fontawesome/solid/bug等。该功能默认未开启表情符号扩展时也可独立工作因为它直接引用主题自带的图标集合。设置页面status实验性功能 · 自 9.2.0 版本起可用状态标识status会被显示在导航侧边栏中用于快速标记新页面已废弃等语义。使用分两步首先在mkdocs.yml的extra.status中将状态标识符identifier与一段描述文本关联起来extra: status: identifier: description # (1)!标识符只能包含字母、数字、短横线-和下划线_。例如要为页面标记Recently added可以定义标识符newextra: status: new: Recently added然后在页面 front matter 中用status属性引用该标识符即可将页面标记为new--- status: new --- # Page title ...主题已经预置了以下两个状态标识符:material-alert-decagram: –new:material-trash-can: –deprecated这两个内置状态的图标定义可以在 src/templates/assets/stylesheets/main/components/_status.scss 中看到--md-status--new使用material/alert-decagram.svg警示星形图标--md-status--deprecated使用material/trash-can.svg垃圾桶图标。当前项目自身的 mkdocs.yml 也配置了这两个状态extra: status: new: Recently added deprecated: Deprecated自定义状态标识符你也可以定义自定义的页面状态但如果希望自定义状态使用默认图标以外的其他图标就需要在extra.css中额外配置例如定义--md-status--identifier对应的 mask-image主题官方提供了一个自定义页面状态示例可供参考。状态渲染的源码细节从 src/templates/partials/nav-item.html 可以看到render_status宏的完整逻辑当config.extra.status[type]存在时状态徽章会带上描述文本作为title属性悬停即显示 tooltip否则只渲染一个无说明的图标。同时src/templates/partials/nav-item.html 会读取nav_item.meta.status来为当前导航项渲染对应状态徽章。此外ellipsis 补丁 在启用了content.tooltips功能时会将.md-status元素挂载为内联 tooltip让状态描述以提示气泡的形式呈现。设置页面subtitle实验性功能 · 自 9.6.0 版本起可用每个页面都可以定义一个副标题subtitle它会以标题下方的次要文本形式渲染在导航侧边栏中。使用 front matter 的subtitle属性即可--- subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor --- # Page title ...在 src/templates/partials/nav-item.html 中副标题被渲染为small元素{% if nav_item.meta and nav_item.meta.subtitle %} br / small{{ nav_item.meta.subtitle }}/small {% endif %}副标题非常适合在大型文档站点中补充说明页面所属模块、适用版本或简短摘要让读者在展开导航的一瞬间就能判断该页面是否值得点入。设置页面template如果你正在使用主题扩展并在overrides目录中创建了新的页面模板就可以通过 front matter 的template属性为某个特定页面启用它--- template: custom.html --- # Page title ...为整个目录批量设置模板??? question 如何为一个文件夹下的所有页面设置模板借助内置的 [meta 插件](https://link.gitcode.com/i/7ae3d3e9326706d6ccf8e948cd9c8832)你可以为整个章节及其所有嵌套页面设置自定义模板在对应文件夹中创建一个 .meta.yml 文件内容如下 yaml template: custom.html 这正是 meta 插件的核心价值。从源码看src/plugins/meta/plugin.py 会在on_files阶段扫描docs目录下的.meta.yml文件名由meta_file配置项控制将其解析为 YAML 并记录到内部映射中随后在on_page_markdown事件优先级 50确保尽早执行阶段按目录层级由浅到深、以类型安全追加TYPESAFE_ADDITIVE策略合并所有相关 meta 文件最后再合并页面自身的 front matter确保页面级元数据始终优先于目录级默认值参见 src/plugins/meta/plugin.py。也就是说.meta.yml提供默认值页面 front matter 可覆盖甚至删除默认值两者互补。在模板中使用元数据为所有页面添加自定义 meta 标签如果你想为所有页面统一添加自定义meta标签可以扩展主题并重写extraheadblock。例如为搜索引擎添加robots索引策略{% extends base.html %} {% block extrahead %} meta namerobots contentnoindex, nofollow / {% endblock %}从 src/templates/base.html 可以看到extraheadblock 位于head的末尾、所有主题内置 meta 标签之后因此非常适合追加自定义标签且不会破坏主题默认行为。为单个页面设置不同 meta 标签如果你只想在单个页面上设置meta标签或希望不同页面使用不同的值可以在模板重写中使用page.meta对象。例如{% extends base.html %} {% block extrahead %} {% if page and page.meta and page.meta.robots %} meta namerobots content{{ page.meta.robots }} / {% else %} meta namerobots contentindex, follow / {% endif %} {% endblock %}此后robots就可以像title和description一样通过 front matter 直接赋值--- robots: noindex, nofollow ---注意在这个例子中模板定义了一个else分支因此在未提供robots元数据时页面会回退到默认值index, follow。这是默认值 按页覆盖模式的典型实践与 meta 插件的合并策略思路一致模板中的条件分支充当兜底front matter 中的具体值负责定制。元数据优先级总结综合以上内容Material for MkDocs 的页面元数据遵循清晰的优先级体系页面 front matter优先级最高直接作用于当前页面目录级.meta.yml默认值由 meta 插件合并次之页面 front matter 可以覆盖它站点级配置如site_description、site_name作为兜底仅在页面与目录均未定义时生效MkDocs 自动推断如标题的四步推断流程处于最底层。掌握这套优先级你就能在保证站点整体一致性的前提下为每个页面灵活定制标题、描述、图标、状态与模板从而获得更好的搜索引擎可见性、社交分享效果与导航体验。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考