TOC does not list all h1 & children elements

[cukal]

Description

TOC only lists first h1 parent's children.

Expected behavior

TOC displays all h1 and children elements.

Actual behavior

TOC only displays the first h1 parent's children

Steps to reproduce the bug

Create a md page with:

# Title
## Subtitle
# Title
## Subtitle

Visit the page and the TOC will show:

Table of contents
subtitle

It should show:

Table of contents
Title
  subtitle
Title
  Subtitle

The problem seems to come from toc.html where toc_ gets populated with the first parent children elements hence it will not show the first h1 element itself but only children elements of the first h1 parent.

    {% if toc_ | first is defined and "\x3ch1 id=" in page.content %}
    {% set toc_ = (toc_ | first).children %}
    {% endif %}

When creating a partial overwrite and removing the if/endif the TOC shows all h1 & children from the md.

Package versions

• Python: Python 3.6.5
• MkDocs: version 0.17.5
• Material: Version: 2.9.2

Project configuration

Not relevant

System information

Not relevant

[squidfunk]

The TOC is not intended to list h1 elements. In HTML5 only one h1 is valid per page or article tag and the whole content is enclosed in an article tag, so adding multiple h1 is not considered valid. Only 2nd+ level items are listed. This is intended behavior. Also see #654.

Valid structures for Markdown documents used with Material are:

# Headline
## Subheadline
### Subsubheadline

or (omitting h1):

## Headline
### Subheadline

[cukal]

Thanks for you reply, I didn't know that but it does makes sense to allow only a single h1. It however upsets pandoc docx to md output because those md's can include multiple h1 elements depending on converted docx & the titles used etc. Adhering to spec this way is confusing and could maybe be catched more elegantly in toc.html with a warning message about the parsed md file containing multiple h1 elements, ignoring them makes it look broken.

[squidfunk]

Yes, you're correct, a warning would be awesome. However, the Jinja runtime is very, very limited and it's not possible for a template to emit a warning.

[squidfunk]

Closing as answered

[Andre601]

I have some doubts on how this works, considering that using default MkDocs theme displays all h1 and h2 headers in the Toc, so at least MkDocs sees it as valid?

[squidfunk]

This is a deliberate design decision. Material only supports a single h1 and it will start rendering TOC elements from the h2, as there's indentation happening with increasing levels. If we would render the h1, all elements beneath that would need to be indented. For this reason, h1 aren't rendered and the theme grabs everything from the first h2 to whatever the first sub-h1-level is.