google/comprehensive-rust

Formalize patching of `book.js`

Open

#2924 opened on Sep 23, 2025

View on GitHub
 (4 comments) (0 reactions) (0 assignees)Rust (32,954 stars) (2,009 forks)batch import
buggood first issue

Description

Inspired by #2571 and other similar changes I made myself, we need to come up with a proper system for maintaining our customizations to theme/book.js. That is, we need to store our modifications as patches or something very similar. Right now, our customizations are direct edits to the file.

The problem is that mdbook is somewhat coupled to it's theme: when we update mdbook to a new version, we run the risk of messing up the rendering if we don't update our (partial!) copy of the default theme.

I'm imagining a system where we:

  1. Store the modifications as a set of patches.
  2. Check that theme/book.js is truly equal to the original book.js file plus the applied patches in a GitHub action.
  3. Some script which can update our mdbook version by updating the book.js file.

I'm probably missing some steps here! 😄

Cc @djmitche, @gribozavr.

Contributor guide

Tech stack
javascriptrust
Domain
toolingdeveloper experience
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
needs investigation
Prerequisites
GitJavaScriptmdbook basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
30
Research direction
This issue proposes formalizing a patching system for customizations to mdbook's theme/book.js. First, research existing patching tools and workflows (e.g., patch files, git submodules, or tools like quilt). Then, design a system to verify that book.js matches the original plus patches, likely via a GitHub Action. Consider how to automate updating book.js when mdbook is updated. Files involved: theme/book.js, potentially a new patches/ directory and CI configuration.