Skip to content

Custom Icons

Material for MkDocs supports custom icons (for example, for our product logos). Here are some notes and steps on adding these files to this site.

0. Start with an svg

You will need the icon in a square .svg file format, with a transparent background. I haven't experimented too much with size, but files up to 1000 x 1000 seem to work fine so far.

1. Minify the svg

So that the image will work with MkDocs' color switching and CSS, we need to remove any embedded colors and cruft from the SVG file.

  1. Open SVGOMG Optimize
  2. In the left menu, choose Open SVG and upload your SVG file
  3. In the Global Settings menu, turn on all the options except for Show original. Leave the sliders at their default settings.
  4. In the Features menu, turn on all the options except for Remove xmlns.
  5. Use the blue download button to download your newly optimized SVG.

2. Add the optimized svg to this repo

In the about repo, add the optimized svg file you just downloaded to the overrides\.icons\<category> folder. The category will depend on what kind of icon you're adding. (StarCat product icons go in logos, etc.)

3. Use your new icon

If you're using the new icon in a Markdown page, you can use the syntax <category>-<name>. So, if the category is logos and the icon is docshub.svg, your icon syntax would be icons-docshub.

Reference

For a list of the major custom icons and their syntax, see Syntax #Custom Icons.

For the primary documentation on Custom Icons in Material for MkDocs, see Customization - Additional icons.