How openhandbookcommons/ohc-001-digital-literacy works
What the file tree implies about architecture
Key structural components in the tree:
• Quarto project configuration
• _quarto.yml (the root “build manifest”: project settings, book structure, output format options, etc.)
• index.qmd (book entry point; often defines metadata and landing content)
• Content sources
• front-matter/*.qmd (license, disclaimers, printing, contribute, preface)
• chapters/partN/*.qmd (main book content split by parts)
• Assets
• cover/ (cover inputs; exact files not shown but directory exists)
• fonts/ (contains OFL.txt; implies custom fonts may be bundled/used in PDF generation)
• Custom build helper(s)
• scripts/add_cover.py (Python script; likely post-processes PDFs to add/merge a cover or generate cover pages)
• Build outputs
• _book/ is mentioned in README as output directory (not committed)
• Dependencies / toolchain
• Quarto (which internally uses Pandoc)
• LaTeX distribution (TinyTeX recommended)
• Python packages: pyyaml, pypdf, reportlab (strongly suggests PDF manipulation + YAML parsing + PDF generation)
• Distribution / release practice
• Rendered PDF is not version-controlled; uploaded as a binary asset with each release (so there’s a “release artifact” step outside the repo tree)
The README defines the “system workflow”:
Authoring Inputs (Source)
• index.qmd
• front-matter/*.qmd
• chapters/**.qmd
• (Optional: treat each “part” directory as a subcomponent)
Project Configuration
• _quarto.yml (book structure, format settings, metadata)
Asset Inputs
• cover/ (cover images or templates)
• fonts/ (font files / license; show as “Fonts (OFL-licensed)”)
Build Orchestrator
• Quarto CLI (quarto render)
• Internals worth explicitly showing (even if Quarto abstracts them):
• Pandoc (document conversion)
• LaTeX Engine (PDF compilation; TinyTeX distribution)
Custom Post-Processing
• scripts/add_cover.py
• Python libs: pypdf / reportlab (PDF creation/manipulation), pyyaml (likely reads config)
Build Artifacts
• _book/ directory
• “Book PDF” (the final distributable)
Distribution
• “GitHub Release (binary asset upload)” (based on README note)
This decomposition is the “as many components as possible” version for clarity and accuracy.
• .qmd + _quarto.yml + assets → Quarto Render
• Quarto Render → (via Pandoc) → LaTeX → PDF output
• PDF output → _book/ (artifact directory)
• _book/<book>.pdf → scripts/add_cover.py (if used after render) → “Final PDF with cover”
• Final PDF → “GitHub Release asset”
Architectural patterns / principles
• Content-as-code: book content versioned as .qmd sources
• Declarative build configuration: _quarto.yml defines structure and output settings
• Toolchain pipeline: Quarto → Pandoc → LaTeX → PDF
• Artifact separation: _book/ output not committed; release attaches binary output
• Extensible build: custom Python script(s) for post-processing (cover/PDF manipulation)
• Quarto CLI
• Pandoc (as an internal step)
• LaTeX / TinyTeX
• Python + pyyaml, pypdf, reportlab
• GitHub Releases (distribution endpoint)
Left column: Inputs
• index.qmd
• front-matter/*.qmd
• chapters/part*/**.qmd
• cover/
• fonts/
• _quarto.yml
Middle column: Build Pipeline
• nested/annotated steps:
• Pandoc (conversion)
• LaTeX/TinyTeX (PDF compile)
Right column: Outputs
• _book/ (output directory)
• “Rendered PDF (release artifact; not committed)”
Bottom or far-right: Distribution
• “GitHub Release (binary asset upload)”
Side branch
• scripts/add_cover.py (Python) connected between _book/ PDF and “Final PDF”
• Dependencies: pypdf, reportlab, pyyaml