Support (and ignore) commonmark header attribute lists in SUMMARY.md
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 22.2k
- Forks
- 1.9k
- PR merge metrics
- PR metrics pending
Description
Problem
mdbook supports CommonMark header attribute lists, and handles them (particularily the #id) attributes appropriately. However it does not handle them in one particular place - SUMMARY.md.
This means that they show up in the table of contents sidebar when they are used (for example, to adjust an identifier computed for parts by 3rd party renderers).
Proposed Solution
The {attributes} block in a h1 header in SUMMARY.md should be parsed by mdbook's html renderer and discarded. This allows other backends to make use of this block while not being visually intrusive in the default renderer.
As an alternative, though one that would likely require an API breaking change, the attributes could be provided separately to the string. This would make it easier for both backends that make use of it (not requiring the backend to explicitly parse it) and ignore it (being able to discard it silently without effort. The pulldown_cmark crate provides this information, so this would likely just require enabling that feature in it.
Notes
In https://github.com/chorman0773/mdbook-fiction-tools, the "ID" of each part is used to compute the output file for the epub output (as well as others using the same system in that repository) when the user of the tool requests that output be split by part (where multiple different works may be amalgamated into a single repository and rendered to html using the same mdbook book, but rendered to downloadable formats elsewise). It also uses it to determine keys in the file-ids config table, which allows users to set explicit identifiers per-part.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Trace how h1 headers in SUMMARY.md reach the HTML renderer, then inspect the pulldown_cmark attribute support mentioned in the issue. Done means attribute lists are omitted from the rendered sidebar while remaining available to other backends; add or update coverage for SUMMARY.md parsing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, rust
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100