# Icons, Emojis

One of the best features of Zensical 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](<https://zensical.org/docs/setup/logo-and-icons/#additional-icons>) and used in your configuration, documents and templates.

## Configuration

This configuration enables the use of icons and emojis by using simple shortcodes. Add the following lines to your configuration:

```toml
[project.markdown_extensions]
attr_list = {}
pymdownx.emoji.emoji_generator = "zensical.extensions.emoji.to_svg"
pymdownx.emoji.emoji_index = "zensical.extensions.emoji.twemoji"
```

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

See additional configuration options:

- [Attribute Lists](<https://zensical.org/docs/compatibility/markdown/python-markdown/#attribute-lists>)
- [Emoji](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#emoji>)
- [Emoji with custom icons](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#custom_icons>)

## Included icon sets

The following icon sets are bundled with Zensical (links lead to search page for each):

- \- [Lucide](<https://lucide.dev/>)
- – [Material Design](<https://pictogrammers.com/library/mdi/>)
- – [FontAwesome](<https://fontawesome.com/search?m=free>)
- – [Octicons](<https://octicons.github.com/>)
- – [Simple Icons](<https://simpleicons.org/>)

Note that you are not limited to these icons as you can [add your own icons](<https://zensical.org/docs/setup/logo-and-icons/#additional-icons>).

## Usage

### Use emojis

Emojis can be integrated in Markdown by putting the shortcode of the emoji between two colons. If you're using [Twemoji](<https://github.com/jdecked/twemoji>) (recommended), you can look up the shortcodes at [Emojipedia](<https://emojipedia.org/twitter/>):

Emoji

```text
:smile:
```

😄

### Use icons

When [Emoji](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#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`](<https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons>) directory, and replacing `/` with `-`:

Icon

```text
:fontawesome-regular-face-laugh-wink:
```

#### with colors

When [Attribute Lists](<https://zensical.org/docs/compatibility/markdown/python-markdown/#attribute-lists>) is enabled, custom CSS classes can be added to icons. While HTML allows inline styles, it's always recommended to add an [additional style sheet](<https://zensical.org/docs/customization/#additional-css>) and move declarations into dedicated CSS classes:

```css
.youtube {
  color: #EE0F0F;
}
```

```toml
[project]
extra_css = [
  "stylesheets/extra.css",
]
```

```yaml
extra_css:
  - stylesheets/extra.css
```

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

Icon with color

```markdown
:fontawesome-brands-youtube:{ .youtube }
```

#### with animations

Similar to adding [colors](<#with-colors>), it's just as easy to add [animations](<https://developer.mozilla.org/en-US/docs/Web/CSS/animation>) to icons by using an [additional style sheet](<https://zensical.org/docs/customization/#additional-css>), defining a `@keyframes` rule and adding a dedicated CSS class to the icon:

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

```toml
[project]
extra_css = [
  "stylesheets/extra.css",
]
```

```yaml
extra_css:
  - stylesheets/extra.css
```

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

Icon with animation

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

## Customization

### Use icons in templates

When you're [extending the theme](<https://zensical.org/docs/customization/#extending-the-theme>) with partials or blocks, you can simply reference any [available icon](<#included-icon-sets>) with Jinja's [`include`](<https://jinja.palletsprojects.com/en/2.11.x/templates/#include>) function and wrap it with the `.twemoji` CSS class:

```html
<span class="twemoji">
  {% include ".icons/fontawesome/brands/youtube.svg" %}
</span>
```

This is exactly what Zensical does in its templates.