Iconoclast¶

Iconoclast integrates Font Awesome Pro with Material for MkDocs. It makes using Font Awesome Pro icons in your site as easy as using Font Awesome Free icons already is.¹ And with support for Font Awesome Kits², using your own custom icons is just as simple.

Material for MkDocs already has a mechanism for adding custom icons. Why do I need Iconoclast?

You could download Font Awesome Pro, unzip it, and copy the SVG files into your project, but then you wouldn't be able to publish your project to GitHub without violating the Font Awesome Pro license. Iconoclast allows you to use Font Awesome Pro icons in your project without exposing them in your codebase.

Prerequisites¶

Font Awesome Pro (1)
Material for MkDocs (2)

Only Font Awesome 6 is supported by Iconoclast.
Not included as a dependency of Iconoclast and must be installed separately.

Installation and Setup¶

First, install Iconoclast:

pip Poetry PDM

pip install iconoclast

poetry add iconoclast

pdm add iconoclast

Then, grab your Font Awesome package manager token from your Font Awesome account page and add it to Iconoclast's plugin configuration. (1)

Font Awesome may require you to generate a token first.

token: Your Font Awesome package manager token.

If your token is bound to the FONTAWESOME_PKG_TOKEN or FONTAWESOME_NPM_AUTH_TOKEN environment variables, Iconoclast will detect it automatically and you can omit this option from the plugin configuration.

Otherwise, you can specify an environment variable with the !ENV tag:

mkdocs.yml

plugins:
    - iconoclast:
        token: !ENV SOME_ENVIRONMENT_VARIABLE

Finally, install Font Awesome Pro with the Iconoclast CLI:

iconoclast setup # (1)!

Tip

The Iconoclast CLI can also be invoked as icl.

Iconoclast and GitHub Actions

If you run iconoclast setup in a GitHub actions workflow, your Font Awesome package manager token could be exposed in workflow logs. To avoid this, store your token as a repository secret and mask it before running iconoclast setup:

steps:
  - name: Add mask
    run: echo "::add-ask::${{ secrets.FONTAWESOME_PKG_TOKEN }}"

Alternatively, you can run iconoclast setup with the --quiet/-q flag to suppress its output entirely.

Configuration¶

Iconoclast requires emoji

Before using Iconoclast, make sure your Material for MkDocs site has been configured to use emoji:

mkdocs.yml

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

The simplest possible configuration is just adding Iconoclast's plugin to mkdocs.yml:

mkdocs.yml

plugins:
    - iconoclast

You can now use Font Awesome Pro icons in Markdown files just as you would Font Awesome Free icons. For example, :fontawesome-duotone-icons: will now render as .

Deprecation warning

If you're using Material for MkDocs Insiders 4.33.0 or later, the built-in social plugin has undergone a rewrite that renders Iconocards obsolete. You can safely ignore the content of this section and use the built-in social plugin as usual.

As of Iconoclast 2.0.2, Iconocards will emit a deprecation warning on versions of Material for MkDocs where it is no longer needed.

Iconoclast's Iconocards plugin is required to use Iconoclast icons in social cards generated by Material for MkDocs' built-in social plugin.³

To use Iconocards, you must remove the built-in social plugin from mkdocs.yml. Don't worry — Iconocards is fully backwards-compatible with the built-in social plugin; you won't lose any functionality.

mkdocs.yml

plugins:
    - iconoclast
    - iconocards # (1)!

Iconocards must be declared after Iconoclast.

Iconocards supports all configuration options of the built-in social plugin.

CSS Support¶

If you want to use Font Awesome icons when overriding blocks or partials, Iconoclast can automatically add the necessary CSS to your site so that you can reference Font Awesome as you would in any other website (e.g,  would render as ).

css: Whether to add Font Awesome's CSS to your site.

Default: false

mkdocs.yml

plugins:
  - iconoclast:
      css: true

Using Kits¶

Have a Font Awesome Kit² with custom icons that you'd like to use in your project? Iconoclast has you covered — just add your kit name and Font Awesome API token to the plugin's configuration.

kit.name: The name of the Kit to use.

mkdocs.yml

plugins:
  - iconoclast:
      kit:
        name: My Kit

kit.token: Your Font Awesome API token. (1)

If your token is bound to the FONTAWESOME_API_TOKEN environment variable, Iconoclast will detect it automatically and you can omit this option from the plugin configuration.

Otherwise, you can specify a different environment variable it with the !ENV tag:

mkdocs.yml

plugins:
    - iconoclast:
        kit:
          name: My kit
          token: !ENV SOME_ENVIRONMENT_VARIABLE

This is distinct from your Font Awesome package manager token. You can find your API token on your Font Awesome account page (Font Awesome may require you to generate one first).

Once you've configured your Kit, you need to install it:

iconoclast install

You can then reference your custom icons in Markdown files with the syntax :fontawesome-kit-[icon-name]: (e.g. :fontawesome-kit-solid-rakugo-sensu:).

If you've enabled CSS Support, you can also reference your custom icons in HTML files with the syntax  (e.g. ).

Tip

You need to rerun iconoclast install every time you make a change to your Kit's name or custom icons.

Using CSS with Kits counts against your pageviews

Font Awesome allots you a certain number of Kit pageviews per month.⁴ If you use Iconoclast's CSS support with a Kit, Iconoclast will serve your CSS via Font Awesome's CDN rather than bundling it with your site, which means that every time someone visits your site, it will count against your pageviews.

Iconoclast¶

Prerequisites¶

Installation and Setup¶

Configuration¶

Social Cards¶

CSS Support¶

Using Kits¶