rust-lang / rust-lang/mdBook

Add collapse all / expand all button for sidebar chapters

Open
#3,050 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
22.2k
Forks
1.9k
PR merge metrics
PR metrics pending

Description

Problem

When a book has many nested chapters with folding enabled, there is no way to collapse or expand all chapters at once. Users must click each chapter's fold toggle individually. VSCode's file explorer has a convenient "Collapse All" button for this exact use case, and mdBook would benefit from the same.

Proposed Solution

Add a button in the menu bar that toggles all chapter folds at once, similar to VSCode's collapse-all button.

  • Placement: In the menu bar's left-buttons area, to the left of the sidebar toggle (hamburger icon)
  • Icons: Use font-awesome-as-a-crate (already a dependency) — square-minus for collapse all, square-plus for expand all, using the regular (outline) style
  • Scope: Only affects top-level foldable chapter items (ol.chapter > li.chapter-item with a child ol.section), not the "On This Page" heading nav groups
  • Visibility: Only shown when [output.html.fold.enable] is true; auto-hidden when JS is disabled (inherits html:not(.js) .left-buttons button { display: none })
  • Behavior: If any foldable chapter is expanded → collapse all; if all are collapsed → expand all. Icon syncs when individual chapter toggles are clicked. The existing 0.5s CSS chevron rotation transition applies automatically.

Files to modify:

File Change
crates/mdbook-html/front-end/templates/index.hbs Add <button> in left-buttons div + <template> elements for FA icons
crates/mdbook-html/front-end/templates/toc.js.hbs Add click handler + icon state sync in connectedCallback() via DOMContentLoaded

No changes needed in toc.rs or chrome.css — the button is entirely client-side and inherits existing .icon-button and menu bar styles.

Notes

The infrastructure for this is mostly in place — folding already works via the expanded class on li.chapter-item elements, and CSS handles visibility and chevron animation. The main work is adding the button UI and a small JS handler to toggle all items at once.

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 by reading the existing folding behavior in crates/mdbook-html/front-end/templates/toc.js.hbs and the left-buttons markup in crates/mdbook-html/front-end/templates/index.hbs. Test with a book containing nested foldable chapters: the new control should appear when folding is enabled, toggle all top-level chapter folds, and keep its icon synchronized with individual toggles.

Written by the indexing model from the issue text.

Assessment

Tech stack
handlebars, javascript
Domain
frontend
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.