Make the built-in typeset plugin compatible with data-toc-label

[lampensau]

Description

I am using the markdown extension attr_list and data attribute data-toc-label to shorten long headings that make up a document's TOC (h2 - h6). Unfortunately, the data attribute doesn't seem to be compatible with the built-in typeset plugin. As soon as the plugin is active, the data attribute is removed but the TOC representation does not change.

Context

Sadly, I am unable to create a reproduction using insiders, as the current beta is recognized as newer. Unfortunately, as of now, the typeset plugin is only available using insiders > 4.27.0:

ERROR   -  Please upgrade to the latest version.

  When reporting issues, please first upgrade to the latest
  version of Material for MkDocs, as the problem might already
  be fixed in the latest version. This helps reduce duplicate
  efforts and saves us maintainers time.

  Please update from 9.1.21+insiders.4.38.0 to 9.2.0b2.

  pip install --upgrade --force-reinstall mkdocs-material

However, using this minimal mkdocs.yml in combination with the following heading will produce my findings. Disabling the typeset plugin will produce a shortened TOC heading.

site_name: My Docs

theme:
  name: material

plugins:
  - typeset

markdown_extensions:
  - attr_list

## Very long heading that spans across multiple TOC lines { data-toc-label="Short heading that fits the TOC" }

Related links

• Requesting a change
• Typeset plugin
• attr_list extension
• MKDocs Issue#2085: control the text in TOC
• Broken heading in official documentation

Use Cases

I have long document headings (h2 - h6) that make up a document's TOC which, if left as is, extend over multiple lines. This makes them harder to grasp when skimming over the TOC. I used to shorten such headings for the TOC and would like to continue to do so when using the built-in typeset plugin.

Visuals

No response

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for reporting. The problem with the info plugin is already tracked in #5773. In the meantime, please use the following configuration for the plugin for mitigation:

plugins:
  - info:
      archive_stop_on_violation: false

[lampensau]

Thanks for the pointer regarding the info plugin. However, the correct syntax for my situation would be (note the dash and indentation):

plugins:
  - info:
      archive_stop_on_violation: false
  - typeset

Please find the reproduction here: example.zip

[squidfunk]

Thanks for noting, updated my comment 😊

[squidfunk]

Okay, so 741005109 adds a hack (really rather a hack than an elegant implementation) that restores data-toc-label functionality when using the typeset plugin in . The problem is that the plugin can't observe the presence data-toc-label as it was already removed, so we must check the Markdown if the toc extension extracted the anchor title from the data-toc-label attribute. The limitation of using data-toc-label is that you can't use HTML inside of it, the toc extension doesn't support it at all. What we theoretically could do is to try to patch that in, but this would probably be pretty fragile, so we're currently not considering that. However, the reported issue is now resolved 😊

[squidfunk]

Released as part of insiders-4.38.1.