Local build instructions
Prerequisites
- Quarto (external site) 1.5 or later (
quarto --version) - Python 3.10+ to run the source-access and accessibility scripts (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 previewQuarto 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 renderHTML is written to _site/, which is gitignored. Open _site/index.html in a browser if you do not want the preview server.
Source access check
full-text-public and external-link-only must name a usable public copy. From the repository root, before or instead of waiting for a full render:
python3 scripts/check_source_access.pyQuarto also runs that script as pre-render. A failure names the source file and the field (external_url, archived_url, or document_path). Tests for the same rules:
python3 scripts/test_check_source_access.pyAccessibility check
python3 scripts/check_a11y.py _siteThe 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 (external site) runs on pull requests and on pushes to main:
- Install Quarto (
quarto-dev/quarto-actions/setup@v2) python3 scripts/check_source_access.pyandpython3 scripts/test_check_source_access.pyquarto render(which runs the source-access check again before rendering)python3 scripts/check_a11y.py _site- On
mainonly: 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
| 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 |