feat(book): full title→heading chain in injectBookSectionDefaults

[mmcky]

Summary

Closes #25. Wires the full title → heading_1 → heading_2 → heading_3 chain per section: tag in injectBookSectionDefaults so the chapter-prefix machinery in enumerate.ts composes without authors needing project-level or per-page frontmatter workarounds.

The problem (from #25)

In a project using just numbering.book: true and section: tags:

project:
  numbering:
    book: true
  toc:
    - file: index
    - title: Front matter
      section: frontmatter
      children: [{ file: preface }]
    - title: Chapters
      section: chapters
      children: [{ file: ch_intro }, { file: ch_fps }]

…the enumerate.ts auto-prefix machinery never fires on chapter pages. The page-title H1 (which pandoc-generated chapter files produce as # Introduction) doesn't increment a counter unless numbering.title.enabled: true, so this.enumerator (the chapter prefix) is undefined and figures / sections / theorems render flat: Figure 1 instead of Figure 1.1, Section 1 instead of 1.1, etc.

The existing workaround required setting title.enabled and heading_2.enabled at project level — but that then leaked into frontmatter/backmatter pages, numbering ## Acknowledgements on the preface as "1". Per-page frontmatter to disable it was the only way out, and isn't viable for book-dp1 where chapter files are pandoc-generated and forbidden to hand-edit.

The fix

In injectBookSectionDefaults (a ~30-line function), wire the matching chain per section:

section: tag	New defaults
chapters / appendices	title.enabled ??= true, heading_2.enabled ??= true, heading_3.enabled ??= true (alongside existing heading_1 wiring)
frontmatter / backmatter	title.enabled ??= false, heading_2.enabled ??= false, heading_3.enabled ??= false (matching existing heading_1 disable)

Also changes the legacy hard h1.enabled = false on frontmatter/backmatter to ??= false for symmetry. The hard assignment had made it impossible for an author to override (e.g. opting a Preface page back into the chapter sequence). With ??= the layered precedence is uniform: page frontmatter > project config > section default > hardcoded fallback.

Tests added

10 new tests in bookSection.spec.ts:

• chapters / appendices seed the full chain enabled
• frontmatter / backmatter seed the full chain disabled
• page override wins on chapters (e.g. author disables heading_2)
• page override wins on frontmatter (e.g. "Chapter 0: Preface" — previously impossible)
• project-level numbering still wins over section default

All 19 bookSection.spec.ts tests pass; full myst-cli suite 293/293 green.

Precedence preserved

This change only adds defaults, never overrides. The mystmd inheritance model (overrides cascade down the document tree) is fully honored:

1. Page frontmatter (highest)
2. Project myst.yml
3. Section defaults — this layer
4. Hardcoded mystmd defaults (lowest)

All assignments use ??= so any higher layer's setting flows through untouched.

Test plan

• bookSection.spec.ts (19 tests) pass
• myst-cli full suite (293 tests) pass
• Deploy to book-dp1 and confirm chapter pages render 1.1, 1.1.1, Figure 1.1, etc. with just numbering.book: true in myst.yml
• Confirm preface / backmatter pages stay unnumbered in the same project

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates injectBookSectionDefaults in myst-cli to seed book-mode numbering defaults per TOC section: tag so that chapter-prefix enumeration composes correctly when a page’s first H1 is absorbed as the page title (e.g., pandoc chapter conversions).

Changes:

• Extend section-default injection to cover numbering.title, numbering.heading_2, and numbering.heading_3 (in addition to existing heading_1) for chapters/appendices, and seed disabled defaults for frontmatter/backmatter.
• Add unit tests covering the new defaults and override behavior.
• Add a changeset documenting the patch release.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
packages/myst-cli/src/process/mdast.ts	Extends injectBookSectionDefaults to seed title + heading_2/3 defaults by book section.
packages/myst-cli/src/process/bookSection.spec.ts	Adds tests validating the new seeding/override behavior.
.changeset/book-section-defaults.md	Declares a myst-cli patch release and describes the behavior change.

Comments suppressed due to low confidence (1)

packages/myst-cli/src/process/bookSection.spec.ts:200

• This test (and its comment) uses heading_1.start: 0 to illustrate a “Chapter 0: Preface”, but the frontmatter validator enforces start >= 1 for numbering items (myst-frontmatter validateNumberingItem, min: 1). In the real pipeline a page-level start: 0 will be rejected/ignored, so this example doesn’t reflect a supported override unless validation rules are changed.

  test('page override wins on a frontmatter page: enabling title is preserved', () => {
    // The other direction: an author has a `Preface` they want numbered
    // as part of the chapter sequence ("Chapter 0: Preface"). They write
    // `numbering.heading_1: { enabled: true, start: 0, label: "Chapter %s" }`.
    // The section default uses ??=, so the page wins and the preface
    // gets numbered despite being tagged `section: frontmatter`.
    //
    // This is the symmetry fix: the legacy `h1.enabled = false` (hard
    // assignment) made this impossible.
    const fm: PageFrontmatter = {
      numbering: {
        book: { enabled: true },
        heading_1: { enabled: true, start: 0, label: 'Chapter %s' },
        title: { enabled: true },
      },

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.