MkDocs Material Extensions

注意：该项目现已弃用，因为MkDocs for Material现在直接实现了此逻辑。用户应迁移到使用mkdocs-material的material.extensions.emoji.twemoji和material.extensions.emoji.to_svg，以替代此库提供的相应materialx.emoji.twemoji和materialx.emoji.to_svg函数。

为MkDocs for Material提供的Markdown扩展资源

安装

通常，只需安装MkDocs Material即可自动安装mkdocs-material-extensions。但如果您需要手动安装，可以使用pip。

pip install mkdocs-material-extensions

但请确保您已安装MkDocs Material，因为没有它将无法工作。

pip install mkdocs-material

内联SVG图标

MkDocs Material 提供了来自 Material、FontAwesome 和 Octicons 的众多图标，但它通过将 SVG 图标内联到源代码中来这样做。目前没有简单的方法来访问这些图标并将它们随意插入到 Markdown 内容中。用户必须自己包含图标字体，并用 HTML 实现。

此模块允许您使用 PyMdown 扩展的 表情符号 扩展，通过简单的 :emoji-syntax: 来启用 MkDocs Material SVG 资产的轻松插入。这是通过创建我们自己的 表情符号索引 和 表情符号生成器 来实现的。自定义索引提供了 Emoji 扩展 Twemoji 索引的修改版本。

除了自定义索引外，您还必须指定相关的自定义生成器。这将找到适当的图标，并将其作为内联 SVG 插入到您的 Markdown 内容中。

示例

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

然后，使用 Material 的 .icons 文件夹的结构，您可以指定图标

We can use Material Icons :material-airplane:.

We can also use Fontawesome Icons :fontawesome-solid-ambulance:.

That's not all, we can also use Octicons :octicons-octoface:.

使用本地自定义图标

在 MkDocs 中，您可以本地覆盖主题资产，甚至可以向主题添加资产。不幸的是，Markdown 解析过程并不知道 MkDocs 环境。幸运的是，如果您正在使用 PyMdown 扩展 7.1，则可以在构建表情符号索引时传入自定义图标路径，并包含您的自定义 SVG 资产。如果将 theme/my_icons 文件夹路径提供给索引构建器，则 my_project/my_icons 下的所有图标，即使是在子文件夹中，也会成为索引的一部分。

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - theme/my_icons

如果给出一个位于 my_project/my_icons/animals/bird.svg 的图标，则该图标可以使用表情符号语法作为 :animals-bird: 使用。请注意，提供的基文件夹不会对图标名称做出贡献。文件夹用 - 分隔。文件夹名称和图标名称应与表情符号语法兼容，因此应避免特殊字符 -- - 和 _ 是可以接受的。

您可以提供任意多的路径，并且它们将按照指定的顺序进行评估。Material 主题的自身图标将在所有自定义路径之后进行评估。这允许用户根据需要覆盖 Material 的图标。

如果图标名称已在索引中，则不会添加该图标。建议始终将图标放在子文件夹中，以帮助对命名空间进行命名，以避免名称冲突。在上面的示例中，bird 在 animals 中，这创建了名称 :animals-bird:，并有助于创建一个更独特且不太可能与现有表情符号和 Material 图标产生重复名称的名称。