Icons & Emojis

DocsForge includes 16,500+ icons across five families — Material Design, Lucide, Font Awesome, Octicons, and Simple Icons — plus 4,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:

Category	Examples
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-cog: settings icon to configure.

Click the settings icon to configure.

In buttons and links

[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 |

Feature	Status
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

Emoji	Shortcode	Use 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

Lucide icons

DocsForge also bundles the complete Lucide icon set (2,000+ stroke-based icons). Use them with the :lucide-name: prefix:

:lucide-rocket: Launch
:lucide-github: GitHub
:lucide-cloud: Cloud
:lucide-terminal: Terminal

Launch :lucide-github: GitHub Cloud Terminal

Browse the Lucide gallery to find the exact name — replace spaces with hyphens: arrow-right → :lucide-arrow-right:.

Stroke-based icons

Lucide icons are drawn with strokes. DocsForge renders them as outlines
(unlike filled Material icons), which pairs well with clean UI text.

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:

theme:
  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:

theme:
  icon:
    admonition:
      note: custom-icon-name

Configuration

Icon support is enabled by default. The configuration is:

markdown_extensions:
  - pymdownx.emoji:
      emoji_generator: !!python/name:docsforge.emoji.to_svg
      emoji_index: !!python/name:docsforge.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