[PR #1548] [MERGED] fix(book): break entirely-bold paragraphs that Pandoc promotes to <h4> #8256

New Issue

GiteaMirror · 2026-04-27T17:36:46-05:00

GiteaMirror commented

2026-04-27 17:36:46 -05:00

📋 Pull Request Information

Original PR: https://github.com/harvard-edge/cs249r_book/pull/1548
Author: @profvjreddi
Created: 4/26/2026
Status: ✅ Merged
Merged: 4/26/2026
Merged by: @profvjreddi

Base: dev ← Head: fix/issue-1503-data-eng-layout

📝 Commits (1)

38ed69b fix(book): break entirely-bold paragraphs that Pandoc promotes to

📊 Changes

13 files changed (+99 additions, -152 deletions)

View changed files

📝 book/quarto/contents/vol1/benchmarking/benchmarking.qmd (+8 -16)
📝 book/quarto/contents/vol1/data_engineering/data_engineering.qmd (+4 -4)
📝 book/quarto/contents/vol1/model_serving/model_serving.qmd (+5 -10)
📝 book/quarto/contents/vol1/nn_architectures/nn_architectures.qmd (+5 -10)
📝 book/quarto/contents/vol1/nn_computation/nn_computation.qmd (+46 -50)
📝 book/quarto/contents/vol1/training/training.qmd (+3 -6)
📝 book/quarto/contents/vol2/backmatter/appendix_reliability.qmd (+2 -4)
📝 book/quarto/contents/vol2/collective_communication/collective_communication.qmd (+4 -8)
📝 book/quarto/contents/vol2/compute_infrastructure/compute_infrastructure.qmd (+4 -8)
📝 book/quarto/contents/vol2/inference/inference.qmd (+3 -6)
📝 book/quarto/contents/vol2/network_fabrics/network_fabrics.qmd (+3 -6)
📝 book/quarto/contents/vol2/security_privacy/security_privacy.qmd (+5 -10)
📝 book/quarto/contents/vol2/sustainable_ai/sustainable_ai.qmd (+7 -14)

📄 Description

Closes #1503.

Summary

User report (#1503): in the rendered Vol1 Data Engineering chapter, body text after the "Optimizing the KWS Design Space" worked-example callout escaped the article column and rendered at full viewport width, overlapping the right-side TOC.

Root cause

Pandoc/Quarto promotes paragraphs whose entire content is a single bold span (e.g. **Step 1: Apply constraints to eliminate options.**) into <h4> headings with auto-generated anchor IDs. With Quarto's section-divs enabled, each promotion creates a <section class="level4">. Inside a foldbox callout near a chapter boundary, the resulting cascade of </section> closes overshoots and prematurely emits </main>. Every paragraph after the callout then renders outside <main> — outside the article column — outside the layout.

The pattern that triggers promotion is specifically: a paragraph whose entire text is wrapped in **...**. Mixed-content bold (**Scenario**: You are building...) is unaffected.

Fix

Move the colon outside the bold span: **Step 1**: Apply constraints to eliminate options. — the paragraph now has mixed Strong + Str content, so Pandoc treats it as prose, not as a heading. Same visual rendering. Matches the canonical **Scenario**: form already used in the same callouts.

Scope

Swept all 52 entirely-bold "Step N:" paragraph triggers across 12 chapters:

Vol1: benchmarking, data_engineering, model_serving, nn_architectures, nn_computation, training
Vol2: appendix_reliability, collective_communication, compute_infrastructure, inference, network_fabrics, security_privacy, sustainable_ai

Even where the cascade didn't catastrophically break the layout, removing the spurious <h4> sections cleans up the rendered chapter TOC (each step was leaking in as a fake sub-subsection).

Test plan

Pattern eliminated: grep -rn -E '^\*\*Step [0-9]+: [^*]+\*\*\$' book/quarto/contents/vol{1,2} returns 0
Pre-commit hooks all green (table prettifier ran on nn_computation.qmd post-edit; staged + recommitted)
Spot-check rendered HTML for vol1/data_engineering after merge: layout should restore, no <section id="step-N-..."> artifacts in the KWS callout

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/harvard-edge/cs249r_book/pull/1548 **Author:** [@profvjreddi](https://github.com/profvjreddi) **Created:** 4/26/2026 **Status:** ✅ Merged **Merged:** 4/26/2026 **Merged by:** [@profvjreddi](https://github.com/profvjreddi) **Base:** `dev` ← **Head:** `fix/issue-1503-data-eng-layout` --- ### 📝 Commits (1) - [`38ed69b`](https://github.com/harvard-edge/cs249r_book/commit/38ed69b631ba372c353020348915ada11d92bb9e) fix(book): break entirely-bold paragraphs that Pandoc promotes to <h4> ### 📊 Changes **13 files changed** (+99 additions, -152 deletions) <details> <summary>View changed files</summary> 📝 `book/quarto/contents/vol1/benchmarking/benchmarking.qmd` (+8 -16) 📝 `book/quarto/contents/vol1/data_engineering/data_engineering.qmd` (+4 -4) 📝 `book/quarto/contents/vol1/model_serving/model_serving.qmd` (+5 -10) 📝 `book/quarto/contents/vol1/nn_architectures/nn_architectures.qmd` (+5 -10) 📝 `book/quarto/contents/vol1/nn_computation/nn_computation.qmd` (+46 -50) 📝 `book/quarto/contents/vol1/training/training.qmd` (+3 -6) 📝 `book/quarto/contents/vol2/backmatter/appendix_reliability.qmd` (+2 -4) 📝 `book/quarto/contents/vol2/collective_communication/collective_communication.qmd` (+4 -8) 📝 `book/quarto/contents/vol2/compute_infrastructure/compute_infrastructure.qmd` (+4 -8) 📝 `book/quarto/contents/vol2/inference/inference.qmd` (+3 -6) 📝 `book/quarto/contents/vol2/network_fabrics/network_fabrics.qmd` (+3 -6) 📝 `book/quarto/contents/vol2/security_privacy/security_privacy.qmd` (+5 -10) 📝 `book/quarto/contents/vol2/sustainable_ai/sustainable_ai.qmd` (+7 -14) </details> ### 📄 Description Closes #1503. ## Summary User report (#1503): in the rendered Vol1 Data Engineering chapter, body text after the "Optimizing the KWS Design Space" worked-example callout escaped the article column and rendered at full viewport width, overlapping the right-side TOC. ## Root cause Pandoc/Quarto promotes paragraphs whose **entire content** is a single bold span (e.g. `**Step 1: Apply constraints to eliminate options.**`) into `<h4>` headings with auto-generated anchor IDs. With Quarto's `section-divs` enabled, each promotion creates a `<section class="level4">`. Inside a foldbox callout near a chapter boundary, the resulting cascade of `</section>` closes overshoots and prematurely emits `</main>`. Every paragraph after the callout then renders outside `<main>` — outside the article column — outside the layout. The pattern that triggers promotion is specifically: a paragraph whose *entire* text is wrapped in `**...**`. Mixed-content bold (`**Scenario**: You are building...`) is unaffected. ## Fix Move the colon outside the bold span: `**Step 1**: Apply constraints to eliminate options.` — the paragraph now has mixed `Strong + Str` content, so Pandoc treats it as prose, not as a heading. Same visual rendering. Matches the canonical `**Scenario**:` form already used in the same callouts. ## Scope Swept all 52 entirely-bold "Step N:" paragraph triggers across 12 chapters: - **Vol1**: benchmarking, data_engineering, model_serving, nn_architectures, nn_computation, training - **Vol2**: appendix_reliability, collective_communication, compute_infrastructure, inference, network_fabrics, security_privacy, sustainable_ai Even where the cascade didn't catastrophically break the layout, removing the spurious `<h4>` sections cleans up the rendered chapter TOC (each step was leaking in as a fake sub-subsection). ## Test plan - [x] Pattern eliminated: `grep -rn -E '^\*\*Step [0-9]+: [^*]+\*\*\$' book/quarto/contents/vol{1,2}` returns 0 - [x] Pre-commit hooks all green (table prettifier ran on `nn_computation.qmd` post-edit; staged + recommitted) - [ ] Spot-check rendered HTML for `vol1/data_engineering` after merge: layout should restore, no `<section id="step-N-...">` artifacts in the KWS callout --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-04-27 17:36:46 -05:00

GiteaMirror closed this issue

2026-04-27 17:36:50 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/cs249r_book#8256