rust-lang / rust-lang/mdBook

Sidebar heading nav issues

Open
#2,848 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-HTML A-Style A-UI C-bug
Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

The sidebar heading navigation (added in #2822) currently seems to have a few oddities:

  1. Header items can be hard to differentiate from chapter items. In this case the user does not know where the headers end and chapters begin:
    Image
  2. Chapters and headers have different spacing. In theory I like that but it's not enough of a difference to help with the UX. If that is adjusted, it'd probably be preferable to have less spacing between chapters than between headers.
  3. There is an invisible <li><ol class="section"></ol></li> between each heading:
    Edit: Presumably resolved. Removed my example image.
  4. All formatting of a header is kept - including images, videos, buttons, etc. This is not necessarily an issue but can look a bit odd in some cases:
    Image
  5. The indicator dot can go off-screen. It would be nice if it would auto-scroll the sidebar to keep the dot on screen.
Steps

No response

Possible Solution(s)

No response

Notes

Tested on Windows 11 in the Zen Browser (based on Firefox 142.0.1).
Overall I really like this feature and it will likely replace mdBook-pagetoc for us.

Version
mdbook v0.5.0-alpha.1

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

Start from the sidebar heading navigation introduced in #2822 and reproduce the reported behavior in mdBook v0.5.0-alpha.1 using the screenshots and listed cases. Inspect the navigation markup and styling, then verify clearer header/chapter separation, appropriate header formatting, and indicator-dot scrolling without regressions.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, html, rust
Domain
frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.