Add AI documentation skills
This commit is contained in:
@@ -0,0 +1,239 @@
|
||||
---
|
||||
icon: material/emoticon-happy-outline
|
||||
---
|
||||
|
||||
# Icons, Emojis
|
||||
|
||||
One of the best features of Material for MkDocs is the possibility to use [more
|
||||
than 10,000 icons][icon search] 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.
|
||||
|
||||
[icon search]: #search
|
||||
[custom icons can be added]: ../setup/changing-the-logo-and-icons.md#additional-icons
|
||||
|
||||
## Search
|
||||
|
||||
<div class="mdx-iconsearch" data-mdx-component="iconsearch">
|
||||
<input
|
||||
class="md-input md-input--stretch mdx-iconsearch__input"
|
||||
placeholder="Search the icon and emoji database"
|
||||
data-mdx-component="iconsearch-query"
|
||||
/>
|
||||
<div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result">
|
||||
<select
|
||||
class="mdx-iconsearch-result__select"
|
||||
data-mdx-component="iconsearch-select"
|
||||
>
|
||||
<option value="all" selected>All</option>
|
||||
<option value="icons">Icons</option>
|
||||
<option value="emojis">Emojis</option>
|
||||
</select>
|
||||
<div class="mdx-iconsearch-result__meta"></div>
|
||||
<ol class="mdx-iconsearch-result__list"></ol>
|
||||
</div>
|
||||
</div>
|
||||
<small>
|
||||
:octicons-light-bulb-16:
|
||||
**Tip:** Enter some keywords to find icons and emojis and click on the
|
||||
shortcode to copy it to your clipboard.
|
||||
</small>
|
||||
|
||||
## Configuration
|
||||
|
||||
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`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
```
|
||||
|
||||
The following icon sets are bundled with Material for MkDocs:
|
||||
|
||||
- :material-material-design: – [Material Design]
|
||||
- :fontawesome-brands-font-awesome: – [FontAwesome]
|
||||
- :octicons-mark-github-16: – [Octicons]
|
||||
- :simple-simpleicons: – [Simple Icons]
|
||||
|
||||
See additional configuration options:
|
||||
|
||||
- [Attribute Lists]
|
||||
- [Emoji]
|
||||
- [Emoji with custom icons]
|
||||
|
||||
[Material Design]: https://pictogrammers.com/library/mdi/
|
||||
[FontAwesome]: https://fontawesome.com/search?m=free
|
||||
[Octicons]: https://octicons.github.com/
|
||||
[Simple Icons]: https://simpleicons.org/
|
||||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
[Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
|
||||
[Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.emoji.options.custom_icons
|
||||
|
||||
## Usage
|
||||
|
||||
### Using emojis
|
||||
|
||||
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]:
|
||||
|
||||
``` title="Emoji"
|
||||
:smile:
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
:smile:
|
||||
|
||||
</div>
|
||||
[Twemoji]: https://github.com/jdecked/twemoji
|
||||
[Emojipedia]: https://emojipedia.org/twitter/
|
||||
|
||||
### Using 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`][custom icons] directory, and replacing `/` with `-`:
|
||||
|
||||
``` title="Icon"
|
||||
:fontawesome-regular-face-laugh-wink:
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
:fontawesome-regular-face-laugh-wink:
|
||||
|
||||
</div>
|
||||
|
||||
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
|
||||
|
||||
#### with colors
|
||||
|
||||
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:
|
||||
|
||||
<style>
|
||||
.youtube {
|
||||
color: #EE0F0F;
|
||||
}
|
||||
</style>
|
||||
|
||||
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
|
||||
|
||||
``` css
|
||||
.youtube {
|
||||
color: #EE0F0F;
|
||||
}
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
After applying the customization, add the CSS class to the icon shortcode:
|
||||
|
||||
``` markdown title="Icon with color"
|
||||
:fontawesome-brands-youtube:{ .youtube }
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
:fontawesome-brands-youtube:{ .youtube }
|
||||
|
||||
</div>
|
||||
|
||||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
[inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
|
||||
[additional style sheet]: ../customization.md#additional-css
|
||||
|
||||
#### with animations
|
||||
|
||||
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:
|
||||
|
||||
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
|
||||
|
||||
``` css
|
||||
@keyframes heart {
|
||||
0%, 40%, 80%, 100% {
|
||||
transform: scale(1);
|
||||
}
|
||||
20%, 60% {
|
||||
transform: scale(1.15);
|
||||
}
|
||||
}
|
||||
.heart {
|
||||
animation: heart 1000ms infinite;
|
||||
}
|
||||
```
|
||||
|
||||
=== ":octicons-file-code-16: `mkdocs.yml`"
|
||||
|
||||
``` yaml
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
After applying the customization, add the CSS class to the icon shortcode:
|
||||
|
||||
``` markdown title="Icon with animation"
|
||||
:octicons-heart-fill-24:{ .heart }
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
:octicons-heart-fill-24:{ .mdx-heart }
|
||||
|
||||
</div>
|
||||
|
||||
[colors]: #with-colors
|
||||
[animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
|
||||
|
||||
### Icons, emojis in sidebars :smile:
|
||||
|
||||
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.
|
||||
|
||||
[built-in typeset plugin]: ../plugins/typeset.md
|
||||
|
||||
## Customization
|
||||
|
||||
### Using icons in templates
|
||||
|
||||
When you're [extending the theme] with partials or blocks, you can simply
|
||||
reference any icon that's [bundled with the theme][icon search] with Jinja's
|
||||
[`include`][include] function and wrap it with the `.twemoji` CSS class:
|
||||
|
||||
``` html
|
||||
<span class="twemoji">
|
||||
{% include ".icons/fontawesome/brands/youtube.svg" %} <!-- (1)! -->
|
||||
</span>
|
||||
```
|
||||
|
||||
1. Enter a few keywords to find the perfect icon using our [icon search] and
|
||||
click on the shortcode to copy it to your clipboard:
|
||||
|
||||
<div class="mdx-iconsearch" data-mdx-component="iconsearch">
|
||||
<input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="brands youtube" />
|
||||
<div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
|
||||
<div class="mdx-iconsearch-result__meta"></div>
|
||||
<ol class="mdx-iconsearch-result__list"></ol>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
This is exactly what Material for MkDocs does in its templates.
|
||||
|
||||
[extending the theme]: ../customization.md#extending-the-theme
|
||||
[include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
|
||||
Reference in New Issue
Block a user