Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support (and ignore) commonmark header attribute lists in SUMMARY.md #2516

Open
chorman0773 opened this issue Jan 2, 2025 · 0 comments
Open
Labels
C-enhancement Category: Enhancement or feature request

Comments

@chorman0773
Copy link

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.

@chorman0773 chorman0773 added the C-enhancement Category: Enhancement or feature request label Jan 2, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-enhancement Category: Enhancement or feature request
Projects
None yet
Development

No branches or pull requests

1 participant