diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index 24e1f84..70c0eaf 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -14,8 +14,25 @@ jobs: - name: Checkout uses: actions/checkout@v4 + # Jena 6 requires Java 21; the runner defaults to 17 + - name: Set up Java 21 + uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: '21' + - name: RDF syntax check uses: AtomGraph/RDF-syntax-check@v1.0.5 + with: + jena-version: 6.1.0 + + - name: Install Linux packages + run: sudo apt-get update && sudo apt-get install -y libxml2-utils + + # riot checks rdf:XMLLiteral well-formedness; canonical form is only + # enforced up to Jena 4.7.0, so it is checked separately + - name: XMLLiteral canonical form check + run: ./check-xmlliterals.sh - name: Check links run: ./check-links.sh diff --git a/.gitignore b/.gitignore index f998a83..51328d6 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ linkeddatahub/.DS_Store docs/docs.trix docs/files.xml docs/html +docs/timestamps.xml diff --git a/CLAUDE.md b/CLAUDE.md index f9793ef..4c324cd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,6 +34,35 @@ make validate # Validate documents make ttl-to-html # Convert Turtle files to HTML ``` +### Documentation media (screencast/) + +Screenshots and clips for the docs are produced by a scripted Playwright rig, never taken by hand. + +```bash +cd screencast +node docs/shoot.mjs --base … --cert-file … --cert-password-file … [--only reference] +make docs-publish # optimise docs/out/ into ../docs/, printing sha1 per published file +``` + +- `docs/manifest.mjs` is the shot list — one entry per `div.screenshot-placeholder` in the `.ttl` sources, bound to its file, line and caption verbatim. New slots go there, not in the runner. +- Each entry's `want` is asserted after `act` and before the capture, so a shot that never reached its state is reported missed rather than written. +- `blocked` slots stay as placeholders with their reason recorded. Do not fill one by hand. +- The shoot writes **masters** — 2880px lossless PNG, a `.webm` and an `.mp4` per clip — into `docs/out/`, plus an `index.json` of slot, caption, file and outcome. It never edits a `.ttl`. +- `make docs-publish` derives the web assets into `docs/`: stills to WebP at 2240px (twice the docs' content column), `.mp4`s copied since they already carry CRF 20 / `yuv420p` / faststart, `.webm`s dropped. + +**Optimise before hashing.** Uploads are content-addressed at `{base}uploads/{sha1}`, so a reference is only valid for the bytes that ship — never hash a master. + +References are document-relative, one `../` per path segment of the page, and live inside `rdf:XMLLiteral` bodies that must stay canonical (attributes alphabetical, explicit end tags, each start tag on one line): + +```xml +The document tree with a container expanded + +``` + +A clip is a `