rust-lang / rust-lang/mdBook

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

Open
#2,516 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.