bd5dd6f088
Configures explicit `render` paths for both volumes to ensure complete and correct builds, particularly for selective rendering workflows. Replaces the static cross-reference fix script with a dynamic version. This new script automatically discovers and resolves internal links from QMD sources, improving maintainability and ensuring links remain functional during partial book builds. Adds a new script to check and auto-fix bibliography completeness, facilitating self-contained volumes. Removes redundant empty Python code blocks from chapter QMDs and refines frontmatter content for consistency.
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.