MkDocs Material 更换 Logo 与图标从内置图标库到自定义 SVG 的完整配置指南【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material本篇指南以 Material for MkDocs 的「更换 Logo 与图标」为主题讲解如何在mkdocs.yml中一键切换头部与侧边栏 Logo、Favicon 以及站点各处导航箭头、搜索、返回顶部等的图标并深入剖析如何在主题中注册自定义 SVG 图标集如 Bootstrap 图标使其既能用于配置项也能在 Markdown 中以 shortcode 形式引用。读完本文你将掌握 Logo/Favicon 的两种配置方式、全部可定制图标清单及其底层渲染机制并能在实际项目中自由混用内置图标与自绘图标。引言超过 8000 个开箱即用的图标安装 Material for MkDocs 后主题会随包分发一套内置图标库bundled icons包含超过 8,000 个可用于主题定制和 Markdown 书写的图标。这套图标按来源组织在主题的material/templates/.icons目录下从目录结构看至少包含以下几大来源material/templates/.icons/ ├─ fontawesome/ # Font Awesome 系列 ├─ material/ # Material Design 系列 ├─ octicons/ # GitHub Octicons 系列 ├─ simple/ # Simple Icons 系列 ├─ logo.svg # 主题自带 Logo └─ logo-monochrome.svg # 主题单色 Logo图标以 SVG 文件形式存在渲染时会被内联到 HTML 中见下文「源码深挖」小节。如果内置图标不够用还可以以极小的成本注册自己的图标集见「自定义图标」章节。配置 LogoLogo 会同时出现在头部header与侧边栏sidebar的左上角且默认指向文档首页。它有两种配置方式使用用户提供的图片文件或使用主题内置图标。方式一使用图片文件任何放在docs文件夹中的图片都可以作为 Logo支持*.png、*.svg等任意常见格式。在mkdocs.yml中指定theme: logo: assets/logo.png注意路径相对于docs文件夹若你的图片位于docs/assets/logo.png则配置值为assets/logo.png。从模板实现看当配置了theme.logo时主题会直接以img标签渲染该图片见 src/templates/partials/logo.html。方式二使用内置图标不配置图片文件而是指定一个图标 shortcodetheme: icon: logo: material/library # (1)!默认值为material/library见 src/templates/mkdocs_theme.yml。可以输入几个关键词用官方的 图标搜索 找到合适的图标点击其 shortcode 复制到剪贴板。渲染时主题会内联该 SVG 图标当theme.logo未配置时模板取config.theme.icon.logo or material/library并通过include .icons/ ~ icon ~ .svg将对应 SVG 文件嵌入页面见 src/templates/partials/logo.html。修改 Logo 的跳转链接默认情况下头部与侧边栏的 Logo 链接到文档首页即site_url指定的地址。如需改为其他目标可通过extra.homepage覆盖extra: homepage: https://example.com设置后点击 Logo 会跳转到该地址而非site_url。配置 FaviconFavicon 是浏览器标签页与书签中显示的小图标同样可以换成用户提供的图片但必须位于docs文件夹内与 Logo 的图片路径规则一致。在mkdocs.yml中配置theme: favicon: images/favicon.png该值的默认路径为assets/images/favicon.png见 src/templates/mkdocs_theme.yml对应本仓库中 material/templates/assets/images/favicon.png。最终主题会将其渲染为link relicon ...标签插入页面头部见 src/templates/base.html。更换站点图标Site icons从版本 9.2.0 起站点上几乎所有可见图标如导航图标都可以单独更换。以页脚footer中的前后翻页箭头为例theme: icon: previous: fontawesome/solid/angle-left next: fontawesome/solid/angle-right主题为每个可定制图标都提供了默认值未配置时自动回退。下表列出全部可定制图标及其用途Icon 名称用途logo头部与侧边栏 Logo参见 Logo 一节menu打开抽屉式导航drawer的菜单按钮alternate切换语言的按钮search搜索图标share分享搜索结果close重置搜索、关闭公告条top返回顶部Back-to-top按钮edit编辑当前页面的入口图标view查看页面源码的入口图标repo仓库图标Git 仓库链接admonition提示框图标参见 Admonition iconstag标签图标与标识符参见 Tag icons and identifiersprevious页脚上一页图标同时用于移动端隐藏搜索next页脚下一页图标各图标的默认值与渲染位置都可以在模板源码中找到依据例如菜单按钮默认material/menu见 src/templates/partials/header.html搜索图标默认material/magnify见 src/templates/partials/search.html翻页箭头默认material/arrow-left与material/arrow-right见 src/templates/partials/footer.html返回顶部默认material/arrow-up见 src/templates/partials/top.html编辑/查看源码默认material/file-edit-outline与material/file-eye-outline见 src/templates/partials/actions.html仓库图标默认fontawesome/brands/git-alt见 src/templates/partials/source.html语言切换默认material/translate见 src/templates/partials/alternate.html。本仓库自带的 mkdocs.yml 就是一个综合示例它同时配置了favicon: assets/favicon.png与icon.logo: logo并在颜色切换、社交链接等位置大量使用了material/*与fontawesome/brands/*图标。自定义图标注册并使用自己的 SVG 图标集当内置图标无法满足需求时可以注册任意 SVG 图标集。操作分为两步放置图标文件与在mkdocs.yml中声明。第一步准备图标目录结构首先需要 扩展主题在用作custom_dir的覆盖目录下新建一个名为.icons的文件夹再把你的*.svg图标放入它的子文件夹中。以经典的 Bootstrap 图标集 为例下载解压后放入项目最终目录结构如下. ├─ overrides/ │ └─ .icons/ │ └─ bootstrap/ │ └─ *.svg └─ mkdocs.yml提示图标会按**/*.svg递归扫描见下文源码分析因此.icons下的子目录结构完全由你决定只要保证每个 SVG 文件名不重复即可。第二步在mkdocs.yml中声明自定义图标目录markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg options: custom_icons: - overrides/.icons注意这里引用的material.extensions.emoji.twemoji与material.extensions.emoji.to_svg正是主题提供的关键扩展点实现位于 src/extensions/emoji.py并同时存在于打包后的 material/extensions/emoji.py。两种使用语法注册完成后图标可在配置项与Markdown 正文两处使用但语法略有不同在配置中使用取 SVG 文件在.icons目录内的路径去掉扩展名。例如对于.icons/bootstrap/envelope-paper.svgtheme: icon: logo: bootstrap/envelope-paper在 Markdown 中使用同样以.icons为起点取路径但把所有/替换为-并在首尾各加一个冒号。例如上面的图标写作:bootstrap-envelope-paper:从此你可以在任何 Markdown 文件中使用:bootstrap-envelope-paper:这样的 shortcode也可以在mkdocs.yml中任何接受图标的地方Logo、导航、提示框、标签等使用bootstrap/envelope-paper这种带斜杠的路径形式。更详细的图标用法请参阅 图标与表情符号参考。源码深挖自定义图标是如何被索引的为什么配置里用/、Markdown 里用-答案在图标索引的构建逻辑中。twemoji索引函数src/extensions/emoji.py读取custom_icons选项随后_load_twemoji_index会以主题根目录下的templates/.icons为基准把主题自带图标目录与所有custom_icons路径合并遍历对每个目录递归执行**/*.svg的 glob 扫描将文件路径中目录分隔符统一替换为-并去掉.svg扩展名生成形如bootstrap-envelope-paper的 shortcode 名见 src/extensions/emoji.py。这就是 Markdown 中「斜杠换连字符」语法的来源而配置项中使用斜杠路径则是因为主题模板直接按config.theme.icon.name的值拼接.icons/前缀并include对应 SVG 文件如 src/templates/partials/logo.html路径即文件路径本身。此外模板中还预留了两种进阶玩法可一并参考导航项图标在页面 meta 中指定icon字段后导航项与标签页会渲染对应图标见 src/templates/partials/nav-item.html 与 src/templates/partials/tabs-item.html在模板中使用图标扩展主题时可用 Jinja 的include直接内联任意内置图标例如span classtwemoji {% include .icons/fontawesome/brands/youtube.svg %} /span这正是主题模板自身的做法参见 图标与表情符号参考。实操要点小结Logo 二选一theme.logo指定docs内的图片文件theme.icon.logo指定内置或自定义图标两者互斥后者的默认值为material/library。Favicon 必须在docs内theme.favicon的默认路径为assets/images/favicon.png。图标路径规则配置项中用「目录/文件名」无扩展名Markdown 中用「目录-文件名」并加冒号包围。自定义图标三步走建.icons目录放 SVG →custom_icons声明路径 → 在配置或 Markdown 中引用。默认值可查所有内置图标的默认值都定义在 src/templates/mkdocs_theme.yml 及各 partial 模板中未配置时自动回退因此可以放心地只覆盖少数图标。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MkDocs Material 更换 Logo 与图标：从内置图标库到自定义 SVG 的完整配置指南
MkDocs Material 更换 Logo 与图标从内置图标库到自定义 SVG 的完整配置指南【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material本篇指南以 Material for MkDocs 的「更换 Logo 与图标」为主题讲解如何在mkdocs.yml中一键切换头部与侧边栏 Logo、Favicon 以及站点各处导航箭头、搜索、返回顶部等的图标并深入剖析如何在主题中注册自定义 SVG 图标集如 Bootstrap 图标使其既能用于配置项也能在 Markdown 中以 shortcode 形式引用。读完本文你将掌握 Logo/Favicon 的两种配置方式、全部可定制图标清单及其底层渲染机制并能在实际项目中自由混用内置图标与自绘图标。引言超过 8000 个开箱即用的图标安装 Material for MkDocs 后主题会随包分发一套内置图标库bundled icons包含超过 8,000 个可用于主题定制和 Markdown 书写的图标。这套图标按来源组织在主题的material/templates/.icons目录下从目录结构看至少包含以下几大来源material/templates/.icons/ ├─ fontawesome/ # Font Awesome 系列 ├─ material/ # Material Design 系列 ├─ octicons/ # GitHub Octicons 系列 ├─ simple/ # Simple Icons 系列 ├─ logo.svg # 主题自带 Logo └─ logo-monochrome.svg # 主题单色 Logo图标以 SVG 文件形式存在渲染时会被内联到 HTML 中见下文「源码深挖」小节。如果内置图标不够用还可以以极小的成本注册自己的图标集见「自定义图标」章节。配置 LogoLogo 会同时出现在头部header与侧边栏sidebar的左上角且默认指向文档首页。它有两种配置方式使用用户提供的图片文件或使用主题内置图标。方式一使用图片文件任何放在docs文件夹中的图片都可以作为 Logo支持*.png、*.svg等任意常见格式。在mkdocs.yml中指定theme: logo: assets/logo.png注意路径相对于docs文件夹若你的图片位于docs/assets/logo.png则配置值为assets/logo.png。从模板实现看当配置了theme.logo时主题会直接以img标签渲染该图片见 src/templates/partials/logo.html。方式二使用内置图标不配置图片文件而是指定一个图标 shortcodetheme: icon: logo: material/library # (1)!默认值为material/library见 src/templates/mkdocs_theme.yml。可以输入几个关键词用官方的 图标搜索 找到合适的图标点击其 shortcode 复制到剪贴板。渲染时主题会内联该 SVG 图标当theme.logo未配置时模板取config.theme.icon.logo or material/library并通过include .icons/ ~ icon ~ .svg将对应 SVG 文件嵌入页面见 src/templates/partials/logo.html。修改 Logo 的跳转链接默认情况下头部与侧边栏的 Logo 链接到文档首页即site_url指定的地址。如需改为其他目标可通过extra.homepage覆盖extra: homepage: https://example.com设置后点击 Logo 会跳转到该地址而非site_url。配置 FaviconFavicon 是浏览器标签页与书签中显示的小图标同样可以换成用户提供的图片但必须位于docs文件夹内与 Logo 的图片路径规则一致。在mkdocs.yml中配置theme: favicon: images/favicon.png该值的默认路径为assets/images/favicon.png见 src/templates/mkdocs_theme.yml对应本仓库中 material/templates/assets/images/favicon.png。最终主题会将其渲染为link relicon ...标签插入页面头部见 src/templates/base.html。更换站点图标Site icons从版本 9.2.0 起站点上几乎所有可见图标如导航图标都可以单独更换。以页脚footer中的前后翻页箭头为例theme: icon: previous: fontawesome/solid/angle-left next: fontawesome/solid/angle-right主题为每个可定制图标都提供了默认值未配置时自动回退。下表列出全部可定制图标及其用途Icon 名称用途logo头部与侧边栏 Logo参见 Logo 一节menu打开抽屉式导航drawer的菜单按钮alternate切换语言的按钮search搜索图标share分享搜索结果close重置搜索、关闭公告条top返回顶部Back-to-top按钮edit编辑当前页面的入口图标view查看页面源码的入口图标repo仓库图标Git 仓库链接admonition提示框图标参见 Admonition iconstag标签图标与标识符参见 Tag icons and identifiersprevious页脚上一页图标同时用于移动端隐藏搜索next页脚下一页图标各图标的默认值与渲染位置都可以在模板源码中找到依据例如菜单按钮默认material/menu见 src/templates/partials/header.html搜索图标默认material/magnify见 src/templates/partials/search.html翻页箭头默认material/arrow-left与material/arrow-right见 src/templates/partials/footer.html返回顶部默认material/arrow-up见 src/templates/partials/top.html编辑/查看源码默认material/file-edit-outline与material/file-eye-outline见 src/templates/partials/actions.html仓库图标默认fontawesome/brands/git-alt见 src/templates/partials/source.html语言切换默认material/translate见 src/templates/partials/alternate.html。本仓库自带的 mkdocs.yml 就是一个综合示例它同时配置了favicon: assets/favicon.png与icon.logo: logo并在颜色切换、社交链接等位置大量使用了material/*与fontawesome/brands/*图标。自定义图标注册并使用自己的 SVG 图标集当内置图标无法满足需求时可以注册任意 SVG 图标集。操作分为两步放置图标文件与在mkdocs.yml中声明。第一步准备图标目录结构首先需要 扩展主题在用作custom_dir的覆盖目录下新建一个名为.icons的文件夹再把你的*.svg图标放入它的子文件夹中。以经典的 Bootstrap 图标集 为例下载解压后放入项目最终目录结构如下. ├─ overrides/ │ └─ .icons/ │ └─ bootstrap/ │ └─ *.svg └─ mkdocs.yml提示图标会按**/*.svg递归扫描见下文源码分析因此.icons下的子目录结构完全由你决定只要保证每个 SVG 文件名不重复即可。第二步在mkdocs.yml中声明自定义图标目录markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg options: custom_icons: - overrides/.icons注意这里引用的material.extensions.emoji.twemoji与material.extensions.emoji.to_svg正是主题提供的关键扩展点实现位于 src/extensions/emoji.py并同时存在于打包后的 material/extensions/emoji.py。两种使用语法注册完成后图标可在配置项与Markdown 正文两处使用但语法略有不同在配置中使用取 SVG 文件在.icons目录内的路径去掉扩展名。例如对于.icons/bootstrap/envelope-paper.svgtheme: icon: logo: bootstrap/envelope-paper在 Markdown 中使用同样以.icons为起点取路径但把所有/替换为-并在首尾各加一个冒号。例如上面的图标写作:bootstrap-envelope-paper:从此你可以在任何 Markdown 文件中使用:bootstrap-envelope-paper:这样的 shortcode也可以在mkdocs.yml中任何接受图标的地方Logo、导航、提示框、标签等使用bootstrap/envelope-paper这种带斜杠的路径形式。更详细的图标用法请参阅 图标与表情符号参考。源码深挖自定义图标是如何被索引的为什么配置里用/、Markdown 里用-答案在图标索引的构建逻辑中。twemoji索引函数src/extensions/emoji.py读取custom_icons选项随后_load_twemoji_index会以主题根目录下的templates/.icons为基准把主题自带图标目录与所有custom_icons路径合并遍历对每个目录递归执行**/*.svg的 glob 扫描将文件路径中目录分隔符统一替换为-并去掉.svg扩展名生成形如bootstrap-envelope-paper的 shortcode 名见 src/extensions/emoji.py。这就是 Markdown 中「斜杠换连字符」语法的来源而配置项中使用斜杠路径则是因为主题模板直接按config.theme.icon.name的值拼接.icons/前缀并include对应 SVG 文件如 src/templates/partials/logo.html路径即文件路径本身。此外模板中还预留了两种进阶玩法可一并参考导航项图标在页面 meta 中指定icon字段后导航项与标签页会渲染对应图标见 src/templates/partials/nav-item.html 与 src/templates/partials/tabs-item.html在模板中使用图标扩展主题时可用 Jinja 的include直接内联任意内置图标例如span classtwemoji {% include .icons/fontawesome/brands/youtube.svg %} /span这正是主题模板自身的做法参见 图标与表情符号参考。实操要点小结Logo 二选一theme.logo指定docs内的图片文件theme.icon.logo指定内置或自定义图标两者互斥后者的默认值为material/library。Favicon 必须在docs内theme.favicon的默认路径为assets/images/favicon.png。图标路径规则配置项中用「目录/文件名」无扩展名Markdown 中用「目录-文件名」并加冒号包围。自定义图标三步走建.icons目录放 SVG →custom_icons声明路径 → 在配置或 Markdown 中引用。默认值可查所有内置图标的默认值都定义在 src/templates/mkdocs_theme.yml 及各 partial 模板中未配置时自动回退因此可以放心地只覆盖少数图标。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
