Can't figure out how to use custom icons

[jorge-campo]

Firstly, thank you very much for this project, @squidfunk! We're evaluating Material for MkDocs for our new documentation site.

My problem is that I can't figure out how to use custom icons in my markdown files. I've reviewed the documentation, the discussions here, and checked other projects using custom icons and still, I don't understand how to do it.

1. In the Icons + Emojis reference section is discussed "Using icons in templates." Do I need to add this <span></span> to my custom CSS? I'm not sure what "Using icons in templates" means; I only want to include custom icons in some markdown files that are not part of the template.
2. I've followed the steps in the Changing the logo and icons section, but I'm not sure about the custom_icons: path in the Bootstrap example. Is the overrides path absolute or relative? And if relative, relative to what?
3. If my icons are under overrides/.icons/status and I have an icon called wallet.svg, how do I type the icon in the markdown file? After checking Adding a custom icon set, not all displaying #2283, I suppose I must write :status-wallet: but this doesn't work for me.

We love the product and the documentation! 💙 But I'm not a web developer, and I believe the documentation can be more useful by adding some examples.

Thank you!

(I attached here a summary of my mkdocs.yml with the relevant information.)

mkdocs.txt

[jorge-campo]

OK, I found it.

Do you know when you spent hours trying to make something work, and in the exact moment you ask for help you find the answer? 😅

The custom icons work for me now. Here is what I have done, just in case someone else finds the same issue:

1. You don't need to add the <span></span> in your custom CSS if you only need to write the icons in your markdown files.
2. The custom_icons path is relative to the path to your mkdocs.yml configuration file.
3. If your icons are under (for example) overrides/.icons/status and you want to render the wallet.svg icon you have on that folder, you type :status-wallet: anywhere on your markdown file.

[cedric-at-list]

Hello, I'm not sure if my question belongs in this issue, but I can't figure out how to reference Icons.
I have copied this grid example and The Icons display correctly in my project.

Now if I want to use this material icon for example, I've tried:

• mdiHandCoin
• mdi-hand-coin

And another question, why are you linking to a third party website for the material icons?
Is it an older version of material design? There are different Icons than on the official library from google.

Nothing works, it always just displays as text.
I have also tried this with fontawesome and icons from the official google library.

There is no way to figure out which string I need to use for an icon.

Also, on both above-mentioned websites for google material icons, I could not find "material-clock-fast", which you use in your grid example.
And on fontawesome, I could not find the "fontawesome-brands-markdown" icon from your example.

[kamilkrzyskow]

Hello @cedric-at-list,
have you read the question and answer above and visited all of the links, because it doesn't seem so. Otherwise I'm confused what isn't clear from those resources. 🤔

The :fontawesome-brands-html5: is mapped to a path fontawesome/brands/html5 which is looked up in the material/templates/.icons directory. material is the true "library/package/namespace" name of the installed mkdocs-material Python package:

• https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons

So with the icon above it finds:

• https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/templates/.icons/fontawesome/brands/html5.svg

The - between the words aren't exactly replaced with / as some icons do have their own dashes inside their names.

Like the :material-hand-coin: is mapped to .icons/material/hand-coin.svg:

• https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/templates/.icons/material/hand-coin.svg

---

The icons inside .icons/material are downloaded from the open source variant @mdi/svg, just like all of the others:

• https://www.npmjs.com/package/@mdi/svg
  I'm not sure if there is some sort of code that renames the mdi space, but I guess it's not required. The builder only copies the files to the appropriate .icons/material subdirectory.

mkdocs-material/package.json

Lines 51 to 53 in 0c54a88

	"@fortawesome/fontawesome-free": "^6.5.2",
	"@mdi/svg": "^7.4.47",
	"@primer/octicons": "^19.9.0",

mkdocs-material/package.json

Line 89 in 0c54a88

"simple-icons": "^12.1.0",

---

So to find the available icons go to https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#icons-emojis
If you want to add other icons packs use overrides as said in the answer above.

[cedric-at-list]

Hello @kamilkrzyskow, thanks for the speedy reply. I got it to work now.

There were some misunderstandings from my side. I didn't know that mkdocs-material has a copy of all the icons that can be used, I thought they are retrieved from other websites. And more importantly, I did not see the search bar for icons at the top of the page 🤦‍♂️ .

[robtaylor]

I completely missed the search bar too! One issue is that its gray. Maybe something a bit more explicit? "Here you can search of all icons included with material and their names"? The tip text is actually helpful but my visual center completely parsed it out...