Docs Build and Deploy

Purpose

Describe how the DSAMbayes documentation site is built, previewed, and deployed.

Documentation layers

DSAMbayes has two documentation systems:

1. pkgdown site (R package documentation)

Generated from roxygen comments in R/ source files and vignettes in vignettes/.

Build locally:

R_LIBS_USER="$PWD/.Rlib" \
  Rscript -e 'pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)'

CI deployment: .github/workflows/pkgdown.yaml builds and deploys to gh-pages on push to main or release events.

Output: generated site under docs/ (pkgdown output, not the Markdown docs).

2. Markdown documentation site (this site)

The docs/ directory contains hand-authored Markdown files organised into sections (Getting Started, Runner, Modelling, Plots, How-To, Appendices). These are configured via docs/docs-config.json.

Site generator: the configuration structure (docs-config.json with navigation, branding, and search settings) is designed for a static site generator. The specific generator and hosting are configured in the deployment environment.

Preview locally: open Markdown files directly, or use any Markdown preview tool. The inter-page links use root-relative paths (e.g. /getting-started/install-and-setup).

Deploy target: https://dsambayes.docs.wppma.space/ (as referenced in README.md).

Configuration

docs/docs-config.json defines:

  • metadata — site name, description, version.
  • branding — logo, favicon, primary colour.
  • navigation — navbar links and sidebar structure.
  • features — math rendering (enabled), search (local).

Adding a new page

  1. Create the Markdown file in the appropriate section directory (e.g. docs/modelling/new-page.md).
  2. Add a sidebar entry in docs/docs-config.json under the appropriate section.
  3. Add a row to the section’s index.md page table.
  4. Update docs/_plan/content-map.md if tracking authoring status.