47 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.
47.1 Local preview
quarto preview --profile opalxThe 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.
47.2 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.
47.3 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.