Adding custom icons in custom theme extending Material for MkDocs

[joapuiib]

I am having trouble adding custom icons with Markdown inside a custom theme that extends this theme. I'm able to use a custom icon placed in the custom theme .icons folder in the configuration, but not in Markdown.

I've looked at #5199, and I seem to have a similar problem, but the structure of the project and the goal is not the same.

---

File structure

Available at: https://github.com/joapuiib/mkdocs-custom-theme

.
├── custom_theme
│   ├── .icons
│   │   └── devicons
│   │       └── java-plain.svg
│   ├── __init__.py
│   └── mkdocs_theme.yml
├── docs
│    └── index.md
├── mkdocs.yml
└── pyproject.toml

mkdocs.yml:

site_name: My Docs

theme:
  name: custom-theme
  icon:
    logo: devicons/java-plain # This works

---

Plugin installation

I've installed my plugin via pip:

~/mkdocs-custom-theme $ pip install .

---

Result:

---

What I've tried

I have tried to configure the plugin in pymdownx.emojiin mkdocs.yml with a custom_dir, and it works (while mkdocs serve) on the same project as I have created the custom theme.

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:          
          - custom_theme/.icons

Note that I have referenced the icons by folder, not hte theme name (custom_theme/.icons instead of custom-theme).

However, this configuration fails when deploying (https://github.com/joapuiib/mkdocs-custom-theme/actions/runs/9964680935/job/27533499144)

Also, I have tried installing the package locally and using it in another project. I can use the custom icons in the configuration, but not as an emoji.

Thanks in advance!

[kamilkrzyskow]

Hi @joapuiib,
if an icon :some-icon: is not in the index it won't be loaded in the generator function. I guess you have to provide your own emoji, index/generator provider for pymdownx.emoji. You can simply load the material index/generator and add your own stuff on top later:

mkdocs-material/material/extensions/emoji.py

Lines 71 to 98 in 6b13c56

	# Load twemoji index and add icons
	@functools.lru_cache(maxsize = None)
	def _load_twemoji_index(paths):
	index = {
	"name": "twemoji",
	"emoji": twemoji_db.emoji,
	"aliases": twemoji_db.aliases
	}
	# Compute path to theme root and traverse all icon directories
	root = os.path.dirname(getfile(material))
	root = os.path.join(root, "templates", ".icons")
	for path in [*paths, root]:
	base = os.path.normpath(path)
	# Index icons provided by the theme and via custom icons
	glob = os.path.join(base, "**", "*.svg")
	glob = iglob(os.path.normpath(glob), recursive = True)
	for file in glob:
	icon = file[len(base) + 1:-4].replace(os.path.sep, "-")
	# Add icon to index
	name = f":{icon}:"
	if not any(name in index[key] for key in ["emoji", "aliases"]):
	index["emoji"][name] = { "name": name, "path": file }
	# Return index
	return index

---

The paths in:

custom_icons:          
  - custom_theme/.icons

are relative to the current working directory, they're not going to be resolved against the extended theme.
So it works in your Python package directory, but doesn't when an external project uses the theme.

[kamilkrzyskow]

If you want the users to be able to still use the default !!python/name:material.extensions.emoji.twemoji syntax in mkdocs.yml, there is also the option to do a hacky monkey-patch of those function during the load of your theme. If I remember correctly, the theme is imported before the config is resolved.

[joapuiib]

Thanks! I see what is happening.

So, what would you recommend for shipping a bunch of custom icons in an extended theme? Should I write an extension that loads the icons in the extended theme into the already defined index in the original extension?

---

Edit: Yes, I would like the users to use the original icons as well.

[kamilkrzyskow]

I'm talking about the syntax, I don't know where your users will get their knowledge from, about how to set up the project/mkdocs.yml.

If you accept the case where the users of the theme have to use !!python/name:custom_theme.extensions.emoji.twemoji, and you'll properly inform them about the change, add your own extension, and provide your replacement functions that will first execute the material.extensions functions and later load your own icons accordingly.

The suggestion with the monkey-patch hack was only meant as another approach to extending the original icons, with your own icons, while preserving the syntax of !!python/name:material.extensions.emoji.twemoji to perhaps decrease the confusion for users. Though, it's more hacky from a development standpoint.

[joapuiib]

I'd rather go with the first approach. I will probably be the only one to use the custom theme (I'll properly inform and document it anyway), but I also think it's the easiest and cleaner way to go.

Thanks for taking your time to helping me. I'll try to give it a try, but I'm not familiar with MkDocs and how extensions are managed (even less extending another extension). Any help is greatly appreciated!

[kamilkrzyskow]

Sure, no problem.
As for the extension creation, nothing is "managed" by MkDocs in this context.

The material Python package includes an extensions sub-package, which includes an emoji module.
In a plain Python interpreter you can do import material.extensions.emoji, and this is basically the same thing as the extended syntax of the mkdocs.yml file !!python/name:material.extensions.emoji.twemoji. which also includes the function name, and this imports the function from the module and attaches it to the config dict of pymdownx.emoji.

So the behavior is purely python import logic + a wrapper (!!python/name:). As for how to load your icons into the index, everything you need should be in the material emoji module file you're replacing.

[joapuiib]

It was easier than I thought.

I have solved it by adding my own emoji extension and configuring it in mkdocs.yml

---

custom_theme/extensions/emoji.py

import os

from inspect import getfile
from markdown import Markdown
from material.extensions.emoji import _load_twemoji_index
import custom_theme

# Create twemoji index
def twemoji(options: object, md: Markdown):
    paths = options.get("custom_icons", [])[:]

    root = os.path.dirname(getfile(custom_theme))
    root = os.path.join(root, ".icons")

    paths.append(root)
    return _load_twemoji_index(tuple(paths))

In mydocs.yml:

markdown_extensions:
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:custom_theme.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Note that I have used the name of the python package custom_theme, not the name of the theme custom-theme.

I have had to add a MANIFEST.in in order to include all .svg files:

recursive-include custom_theme *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff *.html *.py
recursive-exclude * __pycache__
recursive-exclude * *.py[co]

---

Result:

---

Thanks @kamilkrzyskow for your help.

[kamilkrzyskow]

Great work 💪 , even simpler than what I had in mind 🧠