Enable heading attributes

[ehuss]

I'm interested in enabling the new ENABLE_HEADING_ATTRIBUTES feature of pulldown-cmark. This allows you to specify custom id and classes of headers:

# text { #id .class1 .class2 } is interpreted as a level 1 heading with the content text, ID id, and classes class1 and class2. Note that attributes (ID and classes) should be space-separeted.

On occasion I have wanted this functionality to specify nicer links for # fragments (particularly for very long headers), or to avoid breaking links when renaming a header.

Using <a id="foo"> is a clunky workaround. The search system doesn't know about <a> tags, and the header highlighting also doesn't work.

I wanted to see if anyone following this repo has any objection to turning it on, or have any other feedback about it.

A drawback is that GitHub and other services do not support this syntax, so it looks kinda ugly (such as when you are reviewing a PR, or browsing the source):

text { #id .class1 .class2 }

I'm also uncertain if this will break existing plugins. I can't think of anything offhand that would particularly fall down, though.

[rimutaka]

@ehuss, I don't think your proposal would be a problem because the docs are written with a particular platform in mind. Kind of don't use it if it doesn't look nice where you publish it.

I have an alternative proposal along the same lines: adding a div wrapper similar to what Docusaurus does.
Example:

Some paragraph text, bla - bla ...

:::::alert-box
#### Danger zone
Some alert box text message ...

More alert text ....
:::::

converts into

<p>Some paragraph text, bla - bla ...</p>
<div class="alert-box">
  <h4>Danger zone</h4>
  <p>Some alert box text message ...</p>
  <p>More alert text ....</p>
</div>

The goal is to add a wrapper with a class name. It will allow for styling blocks of HTML, no just individual tags.
DIVs are quite versatile and can be styled in many ways, inline, block and wrap any of the HTML mdBook generates without breaking it.

Maybe other Rust MD to HTML converters do something like this already or if there is a better way of achieving the same.
The ::::: syntax is what I saw in Docusaurus. It can be any combo of characters.

We need something like this for our project and I am interested in implementing it if you think it can be merged.

[ISSOtm]

Customizing heading IDs is a common feature request, if only for permalink-like features. So I'd definitely be in favor of this.

[ehuss]

Closing as this was added a while ago in #2013.

[ISSOtm]

Thank you!