图标、表情符号¶

¥Icons, Emojis¶

Material for MkDocs 的一大亮点是，它几乎无需任何额外工作，即可在项目文档中使用超过 10,000 个图标和数千个表情符号。此外，您还可以在mkdocs.yml文件、文档和模板中添加和使用自定义图标。

¥One of the best features of Material for MkDocs is the possibility to use more than 10,000 icons and thousands of emojis in your project documentation with practically zero additional effort. Moreover, custom icons can be added and used in mkdocs.yml, documents and templates.

搜索¶

¥Search¶

提示：输入一些关键字来查找图标和表情符号，然后单击短代码将其复制到剪贴板。

¥ Tip: Enter some keywords to find icons and emojis and click on the shortcode to copy it to your clipboard.

配置¶

¥Configuration¶

此配置允许使用简单的短代码来使用图标和表情符号，这些短代码可以通过图标搜索找到。将以下几行添加到mkdocs.yml中：

¥This configuration enables the use of icons and emojis by using simple shortcodes which can be discovered through the icon search. Add the following lines to mkdocs.yml:

markdown_extensions:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

以下图标集与 Material for MkDocs 捆绑在一起：

¥The following icon sets are bundled with Material for MkDocs:

查看其他配置选项：

¥See additional configuration options:

用法¶

¥Usage¶

使用表情符号¶

¥Using emojis¶

通过将表情符号的短代码放在两个冒号之间，可以将表情符号集成到 Markdown 中。如果您使用Twemoji （推荐），您可以在Emojipedia上查找短代码：

¥Emojis can be integrated in Markdown by putting the shortcode of the emoji between two colons. If you're using Twemoji (recommended), you can look up the shortcodes at Emojipedia:

Emoji

:smile:

使用图标¶

¥Using icons¶

启用表情符号后，可以像表情符号一样使用图标，通过引用主题捆绑的任何图标的有效路径（位于.icons目录中），并将/替换为- ：

¥When Emoji is enabled, icons can be used similar to emojis, by referencing a valid path to any icon bundled with the theme, which are located in the .icons directory, and replacing / with -:

Icon

:fontawesome-regular-face-laugh-wink:

有颜色¶

¥with colors¶

启用“属性列表”后，可以通过在图标后添加特殊语法来添加自定义 CSS 类。虽然 HTML 允许使用内联样式，但始终建议添加额外的样式表，并将声明移至专用的 CSS 类中：

¥When Attribute Lists is enabled, custom CSS classes can be added to icons by suffixing the icon with a special syntax. While HTML allows to use inline styles, it's always recommended to add an additional style sheet and move declarations into dedicated CSS classes:

docs/stylesheets/extra.css mkdocs.yml

.youtube {
  color: #EE0F0F;
}

extra_css:
  - stylesheets/extra.css

应用自定义后，将 CSS 类添加到图标短代码：

¥After applying the customization, add the CSS class to the icon shortcode:

Icon with color

:fontawesome-brands-youtube:{ .youtube }

带有动画¶

¥with animations¶

与添加颜色类似，通过使用附加样式表、定义@keyframes规则并向图标添加专用 CSS 类，可以轻松地向图标添加动画：

¥Similar to adding colors, it's just as easy to add animations to icons by using an additional style sheet, defining a @keyframes rule and adding a dedicated CSS class to the icon:

docs/stylesheets/extra.css mkdocs.yml

@keyframes heart {
  0%, 40%, 80%, 100% {
    transform: scale(1);
  }
  20%, 60% {
    transform: scale(1.15);
  }
}
.heart {
  animation: heart 1000ms infinite;
}

extra_css:
  - stylesheets/extra.css

应用自定义后，将 CSS 类添加到图标短代码：

¥After applying the customization, add the CSS class to the icon shortcode:

Icon with animation

:octicons-heart-fill-24:{ .heart }

侧边栏中的图标、表情符号¶

¥Icons, emojis in sidebars ¶

借助内置排版插件，您可以在标题中使用图标和表情符号，这些图标和表情符号随后会显示在侧边栏中。该插件保留 Markdown 和 HTML 格式。

¥With the help of the built-in typeset plugin, you can use icons and emojis in headings, which will then be rendered in the sidebars. The plugin preserves Markdown and HTML formatting.

定制¶

¥Customization¶

在模板中使用图标¶

¥Using icons in templates¶

当您使用部分或块扩展主题时，您可以简单地使用 Jinja 的包含功能引用与主题捆绑在一起的任何图标，并将其与.twemoji CSS 类包装在一起：

¥When you're extending the theme with partials or blocks, you can simply reference any icon that's bundled with the theme with Jinja's include function and wrap it with the .twemoji CSS class:

<span class="twemoji">
  {% include ".icons/fontawesome/brands/youtube.svg" %} <!-- (1)! -->
</span>

输入几个关键字，使用我们的图标搜索找到完美的图标，然后单击短代码将其复制到剪贴板：

这正是 Material for MkDocs 在其模板中所做的。

¥Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard: