b7d74ce949
Refactors the sidebar auto-collapse script to improve active link detection, scrolling, and part divider placement. It addresses issues with incorrect link highlighting and ensures the active page is always visible after collapse events. Replaces the glossary fix script with a more general cross-reference fixer that correctly calculates relative paths.
Post-Render Scripts
This directory contains scripts that run after Quarto builds to fix various issues.
fix_cross_references.py
Problem It Solves
When using selective rendering to speed up builds (only building index + introduction instead of all 20+ chapters), Quarto cannot resolve cross-references to chapters that weren't built. This results in broken references appearing as ?@sec-chapter-name in the HTML output.
This particularly affects:
- Glossary: Contains 800+ cross-references to all chapters (hence the original script name)
- Introduction: References many other chapters for context
- Any chapter that references other chapters
How It Works
- Runs automatically as a post-render hook after Quarto finishes building
- Scans ALL HTML files in the
_build/html/directory - Finds unresolved references that appear as
<strong>?@sec-xxx</strong> - Converts them to proper links:
<strong><a href="../path/to/chapter.html#sec-xxx">Chapter Title</a></strong>
Configuration
The script is configured as a post-render hook in the Quarto configuration files:
# In config/_quarto-html.yml
project:
post-render:
- scripts/clean_svgs.py
- scripts/fix_cross_references.py # Fixes cross-references
Maintenance
When adding new chapters to the book:
- Add the chapter's section ID to
CHAPTER_MAPPINGdictionary - Add the chapter's display title to
CHAPTER_TITLESdictionary - Ensure the section ID matches what's in the
.qmdfile (e.g.,{#sec-new-chapter})
Example:
CHAPTER_MAPPING = {
# ... existing chapters ...
"sec-new-chapter": "../core/new_chapter/new_chapter.html#sec-new-chapter",
}
CHAPTER_TITLES = {
# ... existing chapters ...
"sec-new-chapter": "New Chapter Title",
}
Manual Testing
# Test on all HTML files
python3 scripts/fix_cross_references.py
# Test on specific file
python3 scripts/fix_cross_references.py _build/html/contents/backmatter/glossary/glossary.html
Output
The script provides clear output showing what it fixed:
🔗 [Cross-Reference Fix] Scanning 3 HTML files...
✅ Fixed 850 cross-references in 2 files:
📄 contents/backmatter/glossary/glossary.html: 810 refs
📄 contents/core/introduction/introduction.html: 40 refs
clean_svgs.py
Cleans up SVG files generated during the build process.
Why These Scripts Exist
These post-render scripts enable fast iterative development by allowing selective chapter builds while maintaining a fully functional website with working cross-references. Without them, developers would need to build all 20+ chapters every time (taking minutes) just to test changes to a single chapter.