Add admonitions to TOC?

[guillevg]

I am creating a math textbook, and I use admonitions for problems. I'd like these admonitions to be automatically added to the TOC (as h6, for example). Maybe I could add a class to the admonition and make the TOC extension recognize that class. I'd appreciate any pointer as to where to start (I understand I should use the Extension API).

[waylan]

I'm not sure I understand what you mean. Could you provide an example (including both the input and expected output)?

[guillevg]

Thank you, sure.

From this Markdown

# Header 1

## Header 2

### Header 3

!!! question "Problem 1"
    Find all solutions to $x^2+1=3$

I get this HTML output

<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  <label class="md-nav__title" for="__toc">
    <span class="md-nav__icon md-icon"></span>
    Table of contents
  </label>
  <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
    <li class="md-nav__item">
      <a href="#header-2" class="md-nav__link">
    Header 2
      </a>
      <nav class="md-nav" aria-label="Header 2">
    <ul class="md-nav__list">
      <li class="md-nav__item">
        <a href="#header-3" class="md-nav__link">
          Header 3
        </a>
      </li>
    </ul>
      </nav>
    </li>
  </ul>
</nav>

But I would like to get this instead

<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  <label class="md-nav__title" for="__toc">
    <span class="md-nav__icon md-icon"></span>
    Table of contents
  </label>
  <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
    <li class="md-nav__item">
      <a href="#header-2" class="md-nav__link">
    Header 2
      </a>
      <nav class="md-nav" aria-label="Header 2">
    <ul class="md-nav__list">
      <li class="md-nav__item">
        <a href="#header-3" class="md-nav__link">
          Header 3
        </a>
        <nav class="md-nav" aria-label="Header 3">
          <ul class="md-nav__list">
        <li class="md-nav__item">
          <a href="#problem-1" class="md-nav__link">
            ❓ Problem 1
          </a>
        </li>
          </ul>
        </nav>
      </li>
    </ul>
      </nav>
    </li>
  </ul>
</nav>

which is the code I get from this Markdown

# Header 1

## Header 2

### Header 3

###### Problem 1

That is, I would like the admonition to show up in the TOC as if it were an h6 heading, using the admonition title as the text (being able to add an emoji in front would be nice, too).

[waylan]

Thank you. However, that is not something we will be implementing. TOC items only ever come from headings. An admonition title is not a heading. Specifically, it is not a h1-6 element and therefore would never be a TOC item. If we allow one non-heading item, then someone else will want another and then we have a mess.

That said, you may be able to use something other than an admonition which does use a heading as the title. Then TOC would include it. Maybe something could be done with Pymdownx Blocks. Specifically, with the html plugin you could craft some custom HTML which looks like an admonition but uses a heading as the title element. For that matter, you could even build your own custom plugin which outputs different HTML for admonitions.

[guillevg]

Thank you. However, that is not something we will be implementing. TOC items only ever come from headings. An admonition title is not a heading. Specifically, it is not a h1-6 element and therefore would never be a TOC item. If we allow one non-heading item, then someone else will want another and then we have a mess.

Of course, I can see this is a very specific concern, I wasn't expecting it to be implemented :)

That said, you may be able to use something other than an admonition which does use a heading as the title. Then TOC would include it. Maybe something could be done with Pymdownx Blocks. Specifically, with the html plugin you could craft some custom HTML which looks like an admonition but uses a heading as the title element. For that matter, you could even build your own custom plugin which outputs different HTML for admonitions.

I'll take a look at these options. Thank you for the ideas.