Looking for more information about data-toc-label and <small>

[rmscode]

While browsing the docs, I noticed that some headings and their TOC entries were formatted in a way that I liked. I checked the raw markdown and discovered this: ### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }.

Can someone point me in the right direction to find the appropriate documentation for data-toc-label, <small>, and other similar things?

[mocdaniel]

<small> is just HTML, which can be written inside of .md files and gets rendered by mkdocs as-is.

The {{ #with-pip data-toc-label="with pip" }} part is an attribute list which allows you to add HTML attributes and CSS classes to almost every Markdown inline- and block-level element with a special syntax (quoted from the docs).

In the specific case you mention in your question, the part #with-pip assigns id="with-pip" to the <h3> HTML element rendered by mkdocs.

The data-toc-label="with-pip" most probably overwrites the TOC entry for this subheading, so that recommended won't get rendered in the TOC. Instead, with-pip is used for the anchor within the page's URL slug, and with pip as entry in the TOC.

[kamilkrzyskow]

Hi @rmscode,
the toc markdown extension allows to override the label for a given TOC entry if it contains special HTML data.

There are cases where you want to add special information for the headings in the content, but want to keep the table of contents "clean".
https://python-markdown.github.io/extensions/toc/#custom-labels

The { ... } syntax is from the attr_list markdown extension, which allows to assign additional HTML attributes to the previous element generated from the markdown
https://python-markdown.github.io/extensions/attr_list/

EDIT: Ah Daniel was faster this time 😎 🤘

[rmscode]

@mocdaniel @kamilkrzyskow Thank you both!