50  Documentation Workflow

Every substantive page declares title, description, audience, status, and last-reviewed. Mark incomplete work visibly as planned; do not fill a gap by copying an unverified historical OPAL chapter.

50.1 Local preview

quarto preview --profile opalx

The opalx profile targets the production OPALX-project/opalx-manual and OPALX-project/opalx-documents repositories. For a one-off private fork, copy _quarto.yml.local.example to _quarto.yml.local and set its documents-base-url. The local file is ignored by Git.

50.2 PDF publication (paused)

The build workflow currently publishes HTML only. BUILD_PDF is "false" in .github/workflows/build.yml, so PDF dependencies, rendering and validation are skipped. _quarto.yml sets book.downloads: [] to hide the unavailable book download. External report PDFs remain available through their existing links.

To restore PDF publication, set BUILD_PDF to "true" and restore book.downloads: [pdf]. Keep the conversion tools installed before the render step. Explicit local PDF builds remain available with the prerequisites below.

The PDF build needs a TeX distribution, headless Chrome for Mermaid diagrams, and rsvg-convert for SVG figures. Install the conversion and inspection tools before rendering; HTML rendering does not exercise SVG-to-PDF conversion.

On Ubuntu, as used by the build workflow:

sudo apt-get update
sudo apt-get install --yes librsvg2-bin poppler-utils

On macOS with Homebrew, the corresponding packages are librsvg and poppler. With TeX installed, prepare the diagram renderer and build the book explicitly:

quarto install chrome-headless-shell --no-prompt
rsvg-convert --version
quarto render --profile opalx --to pdf --no-clean
ruby scripts/validate_rendered_pdf.rb

50.3 Linking binary documents

Place OPALX presentations, reports, examples, and datasets in the category-first opalx-documents tree. Link them only through project metadata:

[OPALX overview](https://github.com/OPALX-project/opalx-documents/blob/main/presentations/2026/features/2026-04-06-opalx-overview.pdf)

Project metadata supplies documents-base-url, so page content does not embed repository locations directly.

Report summaries live in the nested resources/reports/ Quarto project. Add a detail page beneath its year directory and link it from resources/presentations-reports.qmd; do not add individual reports to the numbered book chapters. The nested archive is rendered after the main HTML site and shares the selected deployment profile.

50.4 Asset policy

PDFs, Office documents, archives, and media are rejected from the manual. Raster figures must remain at or below 500 KiB. Source SVG, TikZ, Mermaid, small plots, and reproducible text scripts may remain with the page they support. Generated Quarto output is never committed. The separately hosted Doxygen API reference is linked rather than copied into this manual.