Having the TOC also include HTML headings <h>

[MetalKnight56]

Basically i've been having issues with the TOC as when creating headings that use HTML instead of the usual markdown annotations like in

## Heading

What i use

<h3 id="weapon-file"">Weapon File</h3>

They're excluded from the table of contents

I've seen a few simmilar discussions on the same topic, but i haven't been able to reproduce the contrary expected result, like in:
#313

[squidfunk]

This is a limitation of Python Markdown, which MkDocs uses (our upstream dependency) to render Markdown. You can see that this is not related to Material for MkDocs by using another theme – same result. I think this is a deliberate design decision. In any case, please take this upstream.

[MetalKnight56]

Will do thanks.

[facelessuser]

I think there is an important misunderstanding being made. Yes, this is a limitation in Python Markdown, but you can force raw HTML headers to be included in the TOC by using md_in_html.

Normally, HTML is taken out and handled differently. But if you use md_in_html and attach the markdown attribute, it will be handled more like normal Markdown.

import markdown
import pymdownx

print(f'Pymdown Extensions Version: {pymdownx.__version__}')
print(f'Markdown Version: {markdown.__version__}')
print('-----')

MD = """
[TOC]

## Test 1

<h2 markdown>Test 2</h2>
"""

extensions = ["toc", "md_in_html"]
extension_configs = {}

print(markdown.markdown(MD, extensions=extensions, extension_configs=extension_configs))

<div class="toc">
<ul>
<li><a href="#test-1">Test 1</a></li>
<li><a href="#test-2">Test 2</a></li>
</ul>
</div>
<h2 id="test-1">Test 1</h2>
<h2 id="test-2">Test 2</h2>

Are there cases where this may not always work? Maybe, but generally, at root level, this should work.

[facelessuser]

but for that i'd need to completely override the TOC and to manually specify the anchor links onto it.

I'm not sure where you are getting this from. Just include md_in_html and use raw HTML when you want to. That's it. Maybe you are confused because my example showed me adding [TOC]? You don't have to do this, I just wanted to illustrate it worked.

My question was, by doing this override, to include the anchors, wouldn't that completely bust the other markdown headers (the ones that use #) and force me to have to manually write down each anchor so it's included in the TOC?

Again, I think your assumptions are not quite right here. Try it and see what happens 🙂.

[facelessuser]

@MetalKnight56

and it still doesn`t show up in the toc as you may see in the image below:

It shows up for me

If you want someone to look at this further, please provide a minimal, reproducible example.

[MetalKnight56]

If you want someone to look at this further, please provide a minimal, reproducible example.

Try to have it wrapped inside of these

<div style="display: flex; align-items: flex-start;">
<div style="flex: 1; margin-right: 20px; max-width:75%;">

<h3 markdown id="weapon-file">
<blockquote>Here's a simple example of a sword config:</blockquote>
Test Test Test

</div> <div style="flex: 1; max-width:25%;">

Test 2
<br>
Test 3
</div></div>

It should not work, that's the exact thing i have on my side

[facelessuser]

Try to have it wrapped inside of these

Well, you are not using md_in_html correctly.

Let me explain how this works. Python Markdown does not process block HTML unless it has a markdown attribute.

So you want to process an <h3> inside a <div>? You need to ensure the parent elements also allow markdown processing.

<div markdown style="display: flex; align-items: flex-start;">
<div markdown style="flex: 1; margin-right: 20px; max-width:75%;">

<h3 markdown id="weapon-file">
<blockquote>Here's a simple example of a sword config:</blockquote>
Test Test Test

</div> <div style="flex: 1; max-width:25%;">

Test 2
<br>
Test 3
</div></div>

[facelessuser]

Also, read the documentation for the extension: https://python-markdown.github.io/extensions/md_in_html/.

Keep in mind that it is good to be strict when you are expecting the plugin to process your content. It epects the opening tag on a line by itself and the closing on a line by itself.