Material for MkDocs 页脚Footer配置完全指南社交链接、版权声明与上一篇/下一篇导航【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material页脚是项目文档页面最容易被忽视、却又极具营销与导航价值的区域。Material for MkDocs 允许通过mkdocs.yml一行配置即可在页脚展示社交平台链接如 Mastodon、YouTube、自定义版权横幅与生成器声明并可开启上一篇/下一篇翻页导航。本文基于当前仓库的官方文档与模板源码完整讲解页脚的全部配置项、每个social链接属性的取值范围、按页面隐藏页脚的 Front matter 技巧以及如何通过覆盖 partial 实现完全自定义的版权区域。页脚由哪些部分组成在深入配置之前先明确页脚的结构。Material for MkDocs 的页脚由 src/templates/partials/footer.html 这一个模板渲染并被 src/templates/base.html 在页面底部引入。从模板结构看页脚可以分为两个层次页脚内部导航md-footer__inner仅在启用navigation.footer特性后渲染用于展示当前页面的上一篇Previous与下一篇Next链接页脚元信息md-footer-meta始终渲染内部依次包含版权声明 partial 与社交链接 partial前者对应 src/templates/partials/copyright.html后者对应 src/templates/partials/social.html。因此页脚的全部能力都可以通过mkdocs.yml中的主题特性、copyright顶级配置和extra命名空间完成无需编写任何模板代码只有需要深度定制时才涉及覆盖 partial。配置开启上一篇/下一篇导航页脚可以显示当前页面所属文档的前后翻页链接。要启用这一行为在mkdocs.yml中添加navigation.footer特性该特性自 Material for MkDocs 9.0.0 起可用theme: features: - navigation.footer从模板实现看src/templates/partials/footer.html 会先检查navigation.footer in features再判断page.previous_page与page.next_page是否存在只有前后页存在时才渲染导航区块。页脚的“上一篇/下一篇”文案取自语言翻译文件例如英文环境下对应 src/templates/partials/languages/en.html 中的footer.previous与footer.next键因此会随站点语言自动本地化。前后翻页的方向箭头默认使用material/arrow-left与material/arrow-right图标你也可以通过主题的theme.icon.previous与theme.icon.next配置项替换为任意已捆绑的图标。注意navigation.footer仅控制页脚内部的翻页区块与导航栏的navigation.tabs、navigation.sections等特性相互独立可自由组合。配置社交链接社交链接会作为页脚的一部分、紧邻版权声明渲染。在mkdocs.yml中添加extra.social列表即可extra: social: - icon: fontawesome/brands/mastodon # (1)! link: https://fosstodon.org/squidfunk输入几个关键词使用 图标搜索 找到最合适的图标点击其 shortcode 即可复制到剪贴板当前仓库的图标搜索功能可直接检索已捆绑的图标集。每个社交链接支持以下三个属性其结构定义在 docs/schema/extra.json 中icon与link为必填项social.icon必填此属性必须指向一个主题捆绑的合法图标路径否则构建将失败。icon的取值规则与主题内部.icons/目录的目录结构一一对应常用示例平台图标路径GitHubfontawesome/brands/githubGitLabfontawesome/brands/gitlabX / Twitterfontawesome/brands/x-twitterMastodonfontawesome/brands/mastodonDockerfontawesome/brands/dockerFacebookfontawesome/brands/facebookInstagramfontawesome/brands/instagramLinkedInfontawesome/brands/linkedinSlackfontawesome/brands/slackDiscordfontawesome/brands/discord其中Mastodon 图标有特殊行为查看 src/templates/partials/social.html 的渲染逻辑可以发现当social.icon中包含mastodon字样时链接会自动追加relme属性同时保留noopener这满足了 Mastodon 官方个人主页验证Profile Verification的要求让文档站点的 Mastodon 链接可以被社交网络识别为本人身份。social.link必填此属性必须设置为包含 URI scheme 的相对或绝对 URL。所有 URI scheme 均受支持包括mailto与bitcoin。常见用法示例 Mastodon yaml extra: social: - icon: fontawesome/brands/mastodon link: https://fosstodon.org/squidfunk 邮箱 yaml extra: social: - icon: fontawesome/solid/paper-plane link: mailto:email-address social.name可选该属性会被用作链接的title属性鼠标悬停提示设置一个可辨识的名称可以显著改善无障碍访问体验。若不设置模板会尝试从link中自动推导域名作为默认值——从 src/templates/partials/social.html 的实现看它会将link按//分割取第二部分、再按/分割取第一段即提取出主机名部分。例如https://fosstodon.org/squidfunk的默认标题就是fosstodon.orgextra: social: - icon: fontawesome/brands/mastodon link: https://fosstodon.org/squidfunk name: squidfunk on Fosstodon渲染时所有社交链接会通过target_blank在新标签页打开rel属性默认包含noopener。配置版权声明页脚中可以渲染一条自定义版权横幅显示在社交链接旁。版权声明通过mkdocs.yml顶级的copyright键定义自 0.1.0 起可用copyright: Copyright copy; 2016 - 2020 Martin Donath模板中src/templates/partials/copyright.htmlconfig.copyright会被包裹在md-copyright__highlight容器中高亮展示并支持 HTML 实体因此像copy;这样的版权符号可以放心使用。当前仓库自身的 mkdocs.yml 就是真实范例copyright: Copyright copy; 2016 - 2026 Martin Donath。配置生成器声明页脚默认显示一条Made with Material for MkDocs的生成器声明自 7.3.0 起可用默认值为true用于标识站点的生成方式。若想移除该声明可在mkdocs.yml中设置extra: generator: false其默认值与结构同样定义在 docs/schema/extra.json 的generator项中而模板侧通过{% if not config.extra.generator false %}判断是否渲染声明见 src/templates/partials/copyright.html因此只有显式设置为false才会隐藏未配置时默认为显示。移除生成器声明前请三思页脚中这行低调的Made with Material for MkDocs提示是该项目广受欢迎的原因之一——它告诉访问者站点是如何生成的帮助新用户发现并认识这个开源项目。你正在免费享受开源许可带来的全部收益而该项目背后是成千上万小时的无偿投入因此在移除前请权衡这一贡献。使用按页面隐藏上一篇/下一篇即使全局开启了navigation.footer你也可以在单个页面中隐藏页脚的翻页导航。只需在该 Markdown 文件的 Front matter 中添加hide属性并列出footer--- hide: - footer --- # Page title ...这一机制由 src/templates/partials/footer.html 实现模板读取page.meta.hide当其中包含footer时为md-footer__inner导航区块设置hidden属性从而仅隐藏页脚内部的上一篇/下一篇导航版权声明与社交链接仍正常显示。该隐藏机制同样适用于站点级配置适合在版权声明页、法律声明页等不需要前后翻页的页面上使用。自定义覆盖版权区域实现完全定制如果你需要比copyright键更复杂的版权呈现例如加入多行文本、品牌 Logo 或自定义 HTML 结构可以按 扩展主题 的方式在mkdocs.yml的theme.custom_dir指向的自定义目录中建立与主题同名同结构的目录层级按 覆盖 partial 的方式覆盖默认的copyright.htmlpartial即 src/templates/partials/copyright.html。覆盖后的 partial 默认仍需自行读取config.copyright来呈现mkdocs.yml中定义的版权内容但你可以完全改写渲染逻辑自由组合文本、图标与样式实现完全自定义的版权区域。类似地社交链接也可通过覆盖 src/templates/partials/social.html 来调整链接的呈现方式与属性。小结页脚配置的全部要点可归纳如下表功能配置位置默认值引入版本上一篇/下一篇导航theme.features中的navigation.footer关闭9.0.0社交链接extra.socialicon、link必填name可选无1.0.0版权声明顶级copyright无0.1.0生成器声明extra.generatortrue7.3.0单页隐藏翻页导航页面 Front matterhide: [footer]显示—以上配置全部通过mkdocs.yml声明式完成无需接触模板代码如需更深度的定制可基于 src/templates/partials/footer.html、src/templates/partials/copyright.html 与 src/templates/partials/social.html 三个模板结合 docs/schema/extra.json 与 docs/schema/theme.json 中的 JSON Schema 定义精准把握每个配置项的合法取值再通过覆盖 partial 实现任意形态的页脚。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考