Speed up "reading" times with icon overrides present?

[J-animA]

Hello Everyone,

I recently updated one of my docs sites to mkdocs-material 7.2.5 (issue was also seen in 7.2.4) and MkDocs 1.2.2 and followed the instructions for extending the theme and adding custom icons (for use with the theme toggles) https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#additional-icons

Relevant lines in mkdocs.yml:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

theme:
  name: material
  custom_dir: overrides
  palette:
    - scheme: slate
      primary: deep purple
      accent: purple
      toggle:
        icon: custom/MOON
        name: Switch to dark mode
    - scheme: default
      primary: deep purple
      accent: purple
      toggle:
        icon: custom/SUN
        name: Switch to light mode

When these overrides are in place, it takes a very long time for the site to build (specifically with mkdocs serve but the same issue occurs with mkdocs build as well):

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
...
...
INFO     -  Documentation built in 121.92 seconds

With the overrides removed it takes a "normal" amount of time to build and serve:

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
...
...
INFO     -  Documentation built in 10.86 seconds
INFO     -  [12:53:10] Serving on http://127.0.0.1:8000/

considering there is a checklist item to disable overrides when reporting a bug/issue, I'm assuming this is expected in some fashion, but my question is: is there a way to determine why there is such a slowdown? For reference, there are a whole 2 .svg files in the custom directory. It's structure is as follows:

.
├─ overrides/
│  └─ .icons/
│     └─ custom/
│        └─ SUN.svg
|        └─ MOON.svg
└─ mkdocs.yml

I'd appreciate any info.

[squidfunk]

... considering there is a checklist item to disable overrides when reporting a bug/issue, I'm assuming this is expected in some fashion, but my question is: ...

Correct, we cannot control what users do with this project, and plugins or extension may cause significant slowdown, which is why, in general, we only offer support for issues that are not related to customization.

... is there a way to determine why there is such a slowdown?

Nope, you'd have to narrow it down by commenting out your customizations one-by-one. If you've isolated the cause, we can look into it, but it looks like it's more likely related to an upstream dependency of Material for MkDocs.

[squidfunk]

Okay, then I'm almost sure that it is either related to Python Markdown Extensions or MkDocs itself. I'd recommend posting on the discussion board of the former first, before taking it to MkDocs.

[facelessuser]

I'm not sure what could be done if the Material emoji extension is to blame. When the plugin is loaded for the first time, it should index all the icons. It should only do this when the plugin is loaded for the first time. I'm not sure if MkDocs is re-instantiating the plugins each time or what. If it is re-instantiating it multiple times, then that could be the problem. If it was shown that we were indexing more than once when the plugin was only instantiated once, then we could probably fix that, but outside of that, I'm not sure what the problem would be.

Also, I'm not sure what the "Reading" step is doing in MkDocs. Is it running the Markdown processor in this step?

[facelessuser]

I'll run some basic tests with the latest pymdown-extensions and the latest mkdocs-material-extensions. If I don't see the icon list compounding or indexing more than expected, I'm not sure the problem is on my side.

[facelessuser]

From what I can see, icons are indexed on every page, but only once on each page. The number of paths doesn't inflate on accident, and the number of icons and aliases aren't inflating on accident either. The question is whether indexing is getting run only on new instantiations or whether they are accidentally re-running on new calls to old instantiated instances.

DEBUG    -  Reading: about/changelog.md
---Paths to search---
['docs/theme/my_icons', '/usr/local/lib/python3.9/site-packages/material/.icons']
---indexed---
11252
1762
DEBUG    -  Reading: about/contributing.md
---Paths to search---
['docs/theme/my_icons', '/usr/local/lib/python3.9/site-packages/material/.icons']
---indexed---
11252
1762
DEBUG    -  Reading: about/license.md
---Paths to search---
['docs/theme/my_icons', '/usr/local/lib/python3.9/site-packages/material/.icons']
---indexed---
11252
1762

[facelessuser]

From what I can tell, emoji will only run the custom icon indexing when the new class is instantiated (see _set_index which is only run under __init__):

class EmojiPattern(InlineProcessor):
    """Return element of type `tag` with a text attribute of group(2) of an `InlineProcessor`."""

    def __init__(self, pattern, config, md):
        """Initialize."""

        InlineProcessor.__init__(self, pattern, md)

        title = config['title']
        alt = config['alt']
        self.options = config['options']
        self._set_index(config["emoji_index"])
        self.unicode_alt = alt in UNICODE_ALT
        self.encoded_alt = alt == UNICODE_ENTITY
        self.remove_var_sel = config['remove_variation_selector']
        self.title = title if title in VALID_TITLE else NO_TITLE
        self.generator = config['emoji_generator']

    def _set_index(self, index):
        """Set the index."""

        if len(inspect.getfullargspec(index).args):
            self.emoji_index = index(self.options, self.md)
        else:
            warnings.warn(MSG_INDEX_WARN, util.PymdownxDeprecationWarning)
            self.emoji_index = index()

So it seems like a new instance of Python Markdown is created for each file. If you are scanning a large custom folder of icons, I imagine you will increase the time even more.

Now, this is all based on the latest versions. If you are using an old version of mkdocs-material-extensions there was a bug where the index would inflate bigger and bigger, but this is fixed in the latest iteration.