# 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 [:octicons-link-external-16: SVGOMG Optimize](https://optimize.svgomg.net/)
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 [:octicons-arrow-right-16: Syntax #Custom Icons](syntax.md#custom-icons).

For the primary documentation on Custom Icons in Material for MkDocs, see [:simple-materialformkdocs: Customization - Additional icons](https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#additional-icons).