quarto-conventions

Quarto Conventions

Shared Quarto formatting and structure rules for all textbook chapter workflows.

---

Folder-Based Structure

Because IDE agents rewrite files from scratch on each edit, a single-file approach causes the entire chapter to be rewritten when editing any section. Instead, use a folder-based structure where:

• Each section is a separate file (can be edited independently)
• An index file includes all sections (renders as a single document)

File Structure

Statistics/
├── Bayesian Credible Intervals.qmd          ← Index file (includes all sections)
└── Bayesian Credible Intervals/             ← Folder (same name as index)
    ├── TEXTBOOK-PLAN.md                     ← Created by the research workflow
    ├── _01-introduction.qmd                 ← Section 1
    ├── _02-the-bayesian-framework.qmd       ← Section 2
    ├── _03-computing-credible-intervals.qmd ← Section 3
    ├── _04-examples.qmd                     ← Section 4
    ├── _98-math-background.qmd              ← Math Background appendix (if needed)
    ├── _99-closing.qmd                      ← Summary, questions, resources
    └── sources/                             ← Symlink or note pointing to AI-Learning-Gems/sources/

Key conventions:

• Index file: [Topic Name].qmd — contains YAML header and {{< include >}} statements
• Folder: [Topic Name]/ — same name as the index file (without .qmd)
• Section files: Prefixed with _ so Quarto doesn't render them standalone
• Numeric prefixes: _01-, _02-, etc. for ordering (starting at _01, not _00)
• Sources: Referenced from central AI-Learning-Gems/sources/ — see TEXTBOOK-PLAN.md for paths

---

Index File Template

The index file should contain ONLY the YAML header and include statements. Most settings (format, jupyter kernel, execute options) are inherited from the project's _quarto.yml file — the index file only needs the title and the D2 diagram filter.

CRITICAL: The filter path is RELATIVE from the .qmd file to the _extensions folder at the project root. Adjust the number of ../ based on folder depth:

• Files 1 level deep (e.g., Statistics/Topic.qmd): ../_extensions/...
• Files 2 levels deep (e.g., Statistics/Subfolder/Topic.qmd): ../../_extensions/...