Icons rendered in some markdown pages but not others

[BamBalaam]

Introduction

Hi everyone.

I recently version bumped one of my company's documentation websites from mkdocs-material 4.0.1 to 9.1.1 (yeah, it's a big bump...).

We used to be able to render material icons in markdown pages (with some extra CSS sugar on top) with no issues.

Since the bump, some pages are not rendering the icons correctly. I have a small theory of why that is the case found at the end of my question, but I'm not sure if it is correct.

Thanks in advance for your help! 😄

Before the version bump

<i class="medium-material-icons">notifications</i> View the system notifications

<div class="dev-sample-code-widget">
    <a href="/developers/nfc/ndef-tag">
        <div class="dev-widget-image">
            <i class="bigger-material-icons">nfc</i>
        </div>
        <div class="dev-widget-title">
            NFC NDEF Classic tag
        </div>
    </a>
</div>

After the version bump

<i class="medium-material-icons">:material-bell:</i> View the system notifications

(replaced "notifications" by ":material-bell", everything is working fine)

<div class="dev-sample-code-widget">
    <a href="/developers/nfc/ndef-tag">
        <div class="dev-widget-image">
            <i class="bigger-material-icons">:material-nfc-variant:</i>
        </div>
        <div class="dev-widget-title">
            NFC NDEF Classic tag
        </div>
    </a>
</div>

(replaced "nfc" by ":material-nfc-variant:", the rendering is broken)

Theory

My leading theory is that the parser might be struggling to render icons nested in one or several div tags.

Rendering the same <i> tag outside of the nested div tags displays the icon correctly.

<i class="bigger-material-icons">:material-nfc-variant:</i>

However inside of a singular div tag, the rendering fails

<div>
    <i class="bigger-material-icons">:material-nfc-variant:</i>
</div>

[squidfunk]

You probably need to set the markdown property on all div elements, and use md_in_html to instruct the parser to look for Markdown constructs inside HTML. If you move :material-nfc-variant: outside of the div to the top level, does it render correctly? if so, that's a clear indication that you're missing md_in_html. Example:

<div markdown>
  <div markdown>
    :material-nfc-variant:
  </div>
</div>

And I'd be very interested to hear what you think of Material for MkDocs 9 when coming from version 4 😊 Almost 4 years of development happened since then.

[squidfunk]

You can't use icons inside code blocks, which appears to be what you're doing. Copy and paste this in your Markdown file:

This is a paragraph with an :material-nfc-variant: icon.

[BamBalaam]

Hi again,

No, it's not a code block. The parser rendered it that way. Here's the exact code written to get the output above:

## Sample codes related

<div markdown>
  <div markdown>
    :material-nfc-variant:
  </div>
</div>

[BamBalaam]

@squidfunk if this can help you in any way, I might have found an element of response.

The moment you set a markdown property in a HTML tag, the parser struggles to understand indentation in the html, which is why it is rendering as a code block, because markdown treats an indentation as a code block. Not sure if the issue is in mkdocs-material or md_in_html

Here is a list of examples. Notice how each time the first example has no indentation and the second has.

Code

# Sample codes

## Simple example, no indentation

<div markdown>
<i markdown class="bigger-material-icons">:material-nfc-variant:</i>
</div>

## Simple example, with indentation

<div markdown>
    <i markdown class="bigger-material-icons">:material-nfc-variant:</i>
</div>

## Complex example, no indentation

<div markdown class="dev-container-row">
<div markdown class="dev-sample-code-widget">
<div markdown class="dev-widget-image">
<i markdown class="bigger-material-icons">:material-nfc-variant:</i>
</div>
<div class="dev-widget-title">
NFC NDEF Classic tag
</div>
</div>
</div>

## Complex example, with indentation

<div markdown class="dev-container-row">
    <div markdown class="dev-sample-code-widget">
        <div markdown class="dev-widget-image">
            <i markdown class="bigger-material-icons">:material-nfc-variant:</i>
        </div>
        <div class="dev-widget-title">
            NFC NDEF Classic tag
        </div>
    </div>
</div>

Output

EDIT: Conclusion

It seems that it's ok as long as you keep your indentation level under at one space char.

[squidfunk]

Ah yeah, my bad. You must not indent the Markdown, and sometimes whitespace seems even necessary:

## Sample codes related

<div markdown>
  <div markdown>

:material-nfc-variant:

  </div>
</div>

I'm not entirely sure about the mechanics of the extension, maybe take this upstream to Python Markdown and consult their documentation or ask the maintainers what exactly needs to be done for Markdown to be parsed out correctly.

[BamBalaam]

I opened the question here because I identified a regression in the way the Markdown was parsed between version 4 and 9 of mkdocs-material, as the indented markdown with icons worked fine in version 4 (without the use of the md-in-html extension). Since it was a regression on the icons part (not a "core" MKDocs feature), I wondered if something changed in mkdocs-material in how to parse and resolve icons. But I understand that the issue might be in Python Markdown, as I imagine you version-bumped that library between versions of mkdocs-material.

I tested writing HTML with only one space char as indentation, and it works indeed. Thanks! 😄