Custom section (header) ID

[lo48576]

It would be useful if the section IDs can be specified manually (such as # About foo {#foo}, supported by many processors including zola).

For example, it would be useful when:

• Some of section names are very long, but wants IDs to be short enough.
• Attempt to prevent future link breakage, which can be caused by sections renaming or mdbook algorithm change.
• Providing multiple sites with different languages, but wants URIs (especially paths and fragments) to be coherent English.

Users can already control paths by setting filename, then it is natural if users can also control fragment part of URIs (/user/specified/path.html#THIS-PART).

Is this feature simply not implemented or considered yet, or are there some reasons to object to this feature?

Maybe related: #880

[ehuss]

I think such a change would be best made as an extension in pulldown-cmark, the markdown processor mdbook uses. Perhaps ask over there if it would be considered?

I usually just add a tags like <a id="example-fragment"></a> just before the header, but is certainly not ideal.

[lo48576]

pulldown-cmark v0.9.0 now has Options::ENABLE_HEADING_ATTRIBUTES extension, which enables users to write custom ID and classes such as # Examples {#examples-foo .example}.

[ImUrX]

@ehuss This is easy to work on, should I make this a default option or configurable?

Also I should document it on the mdbook, right?

[ehuss]

Thanks for taking a look!

I think it should be fine to have it always be on. I think the risk of it causing issues is low.

Just make sure to test that things like the search index work correctly.

And yea, the documentation would be listed as an extension at https://github.com/rust-lang/mdBook/blob/master/guide/src/format/markdown.md.