Local build instructions

Prerequisites

  • Quarto 1.5 or later (quarto --version)
  • Python 3.10+ only if you want to run the accessibility script (standard library; no pip packages)

No R, Jupyter, database, or private jordanforge toolchain is required. Source pages are static Markdown.

Preview

From the repository root:

quarto preview

Quarto prints a local URL. The site uses relative links plus site-url: https://csil-history.jordanforge.ca for the published location. Canonical and sitemap URLs use that hostname at the subdomain root, with no /csil-history/ prefix.

Render

quarto render

HTML is written to _site/, which is gitignored. Open _site/index.html in a browser if you do not want the preview server.

Accessibility check

python3 scripts/check_a11y.py _site

The script exits non-zero when a baseline (Blocker/High) HTML problem is found. That failure is a merge blocker.

Continuous integration

.github/workflows/pages.yml runs on pull requests and on pushes to main:

  1. Install Quarto (quarto-dev/quarto-actions/setup@v2)
  2. quarto render
  3. python3 scripts/check_a11y.py _site
  4. On main only: upload the Pages artifact and deploy

Enabling GitHub Pages

A repository administrator should set Settings → Pages → Source to GitHub Actions. Until that is done, the workflow can build on pull requests but production deploy will not have a Pages environment.

Canonical public URL:

https://csil-history.jordanforge.ca

The earlier project URL, https://jordanforge-ca.github.io/csil-history/, redirects to the custom domain while that hostname is the Pages custom domain. The observed response is a 301. It points at http:// until the Pages certificate exists and HTTPS is enforced.

Adding content

Data table
Task Where
New source Copy sources/example-template-source-record.qmd
New timeline event Append to data/timeline.yml
New person stub Copy a file in people/
New bibliography entry references.bib
Hosted document Only after copyright policy

See CONTRIBUTING.md.