Skip to content

Icons & Emojis

DocsForge includes 8,000+ Material Design icons and 3,000+ Twemoji emojis out of the box. No external downloads needed.

Icons

Syntax

Use :material-icon-name: syntax anywhere in your Markdown:

:material-heart: I love DocsForge!

I love DocsForge!

Finding icons

Browse the full Material Design Icons library. Common categories:

CategoryExamples
Navigation :material-home: :material-arrow-right: :material-menu:
Actions :material-download: :material-upload: :material-refresh:
Content :material-file-document: :material-image: :material-code-braces:
Status :material-check-circle: :material-alert-circle: :material-information:
Hardware :material-memory: :material-harddisk: :material-server:
Social :material-github: :material-twitter: :material-web:

Icon search

Use the Material Icons search to find the exact name. Replace spaces with hyphens: arrow-right → :material-arrow-right:

Using icons

In text

Click the :material-settings: settings icon to configure.

Click the :material-settings: settings icon to configure.

[Get started :material-arrow-right:](getting-started.md)

[Download :material-download:](https://example.com)

Get started

Download

In admonitions

Icons appear automatically in admonition titles based on the type:

!!! tip "Tip with icon"
    This admonition has an automatic icon.

Tip with icon

This admonition has an automatic icon.

In headers

## :material-rocket: Getting Started

Getting Started

In tables

| Feature | Status |
|---------|--------|
| :material-check: Working | :material-check-circle: Complete |
| :material-wrench: In progress | :material-alert: Attention needed |
FeatureStatus
Working Complete
In progress Attention needed

Icon sizing

Apply CSS classes for sizing (requires custom CSS):

:material-heart:{ .twemoji .lg } Large heart
:material-heart:{ .twemoji .2x } Double size
:material-heart:{ .twemoji .3x } Triple size

Custom icon colors

:material-heart:{ .red } Red heart
:material-heart:{ .blue } Blue heart

(Requires defining .red and .blue CSS classes.)

Emojis

Standard shortcodes

Use standard emoji shortcodes:

:smile: :thumbsup: :rocket: :fire: :star: :warning: :heart: :tada:

😄 👍 🚀 🔥 ⭐ ⚠ ❤ 🎉

Common emojis for documentation

EmojiShortcodeUse case
🚀:rocket:New feature, launch
⚠:warning:Warning, caution
⭐:star:Favorite, recommended
🔥:fire:Hot topic, trending
💡:bulb:Idea, tip
🐛:bug:Bug, issue
✅:white_check_mark:Completed
❌:x:Failed, removed
📝:memo:Documentation
⚙:gear:Configuration

Font Awesome icons

Font Awesome brand icons are also available:

:fontawesome-brands-github: GitHub
:fontawesome-brands-python: Python
:fontawesome-brands-docker: Docker
:fontawesome-brands-linux: Linux
:fontawesome-brands-windows: Windows
:fontawesome-brands-apple: Apple
:fontawesome-brands-js: JavaScript
:fontawesome-brands-react: React
:fontawesome-brands-vuejs: Vue
:fontawesome-brands-html5: HTML5
:fontawesome-brands-css3: CSS3

GitHub
Python
Docker
Linux
Windows
Apple
JavaScript
React
Vue
HTML5
CSS3

Font Awesome regular and solid

Brand icons (fontawesome-brands-*) are always available. Regular and solid variants may require additional configuration.

Custom icons

Adding custom icons

Place SVG icons in docs/assets/icons/ and reference them:

extra:
  icon:
    logo: assets/icons/my-logo.svg
    repo: assets/icons/custom-repo.svg

Using custom icons in Markdown

:custom-icon-name:

Requires registering the icon in your docsforge.yml:

extra:
  icon:
    admonition:
      note: custom-icon-name

Configuration

Icon support is enabled by default. The configuration is:

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

Don't change this

DocsForge vendors all emoji and icon assets. Changing the generator or index may break offline support.

Best practices

  • Use icons sparingly — too many make text hard to read
  • Prefer Material icons over emojis for professional documentation
  • Use emojis for informal content, release notes, or social cards
  • Always include the text label alongside icons for accessibility
  • Test how icons render in both light and dark themes
  • Avoid icons in table headers — use text instead

Next steps