Problems in main TOC while embedding markdown files

[pajaro1966]

When I embed a markdown file in another markdown file, the TOC of the main file gets interrupted if the embedded file contains a first level heading (#), but not if it contains only second or further level headings (##, ###, etc.).

This is a screen shot of the main TOC in my MkDocs. It stops at the letter delta (Δ):

This is the content of the first embedded markdown file (it does not interrupt the TOC):

This is the content of the second embedded markdown file, the one interrupting the TOC:

The main markdown file contains many other first level headings that don't appear in the TOC (exactly after the point where the second embedded file is inserted):

The solution seems easy: to write my embedded .md files with no first level heading, but this is a bad practice and I should reformat all my files. Is this a bug or am I making some mistake?

Sorry if this issue has been already addressed. I couldn't find any reference.

Thanks in advance for your help.

Antonio

[alexvoss]

AFAIK, this is a general problem with Markdown. If you write the embedded files just for embedding then you can avoid a level 1 heading but if they also need to have their own existence then their level 1 headings get included in a document that already has one.
Nothing to do with Material for MkDocs really.

How are you including the files? If you are using the Python Markdown Extensions and their snippets function, then you could try specifying the starting line for the included file.

[pajaro1966]

But a new problem has arisen. The TOC of the embedding markdown file includes also the TOC of the embedded file (see the red box), which is undesirable:

[alexvoss]

If there are headings in the included file then those would appear in the TOC, yes. Not sure why you would not expect them to? Just to be clear, you do want the headings in the document but do not want them to appear in the TOC? Could you use this tip to use HTML headings instead of Markdown?

If that does not do what you want then I think the only way left would be to process the included file. You could write your own hook to do this.

[pajaro1966]

Thank you very much for all your detailed and fast replies. I do really appreciate. I'm new to Material and perhaps my questions are obvious and are explained in the documentation. I'm just overwhelmed by the documentation.
I don't want the general TOC to include the tocs of the embedded files, because I'm writing a dictionary and with so many entries the TOC would become useless.
Thanks again for your time.

[alexvoss]

I wish I could tell you that you simply missed something in the documentation but that is not the case. The whole Markdown/MkDocs/Material ecosystem has grown over time and its documentation is fragmented. The Material for MkDocs documentation does not cover many things that are really defined by MkDocs. Nor does it cover the specific Markdown dialect used, Python Markdown. So, you will find that you need to ready across these different bits of documentation and, all too often, between the lines.

We are actively working on documentation that will remedy some of these problems. This is part of our work to [transform Material[(https://squidfunk.github.io/mkdocs-material/blog/2024/08/19/how-were-transforming-material-for-mkdocs/) into an even more amazing tool for producing great docs. I do hope this will help with questions like the one you came across. Until we are ready, please feel free to ask questions.

[pajaro1966]

Material is extremely good as it is. It's a great step forward from Mkdocs. I do really appreciate your work on it and your replies to my questions. Thanks again to all of you working on it.