transparency-certified · Xarthisius · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -0,0 +1,39 @@
+name: Jupyter Book Build Check
+
+on:
+  push:
+    branches-ignore: [main]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+
+      - name: Install Jupyter Book (via myst)
+        run: npm install -g jupyter-book
+
+      - name: Build and check for warnings or errors
+        run: |
+          jupyter-book build --site --check-links --strict 2>&1 | tee build.log
+          FAILED=0
+          if grep -qE '^⚠️' build.log; then
+            echo "::error::Jupyter Book build produced warnings. See log for details."
+            grep -E '^⚠️' build.log | while IFS= read -r line; do
+              echo "::warning::$line"
+            done
+            FAILED=1
+          fi
+          if grep -qE '^⛔️' build.log; then
+            echo "::error::Jupyter Book build produced errors. See log for details."
+            grep -E '^⛔️' build.log | while IFS= read -r line; do
+              echo "::error::$line"
+            done
+            FAILED=1
+          fi
+          exit $FAILED
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -1,26 +1,48 @@
-name: deploy-docs
+# This file was created automatically with `jupyter-book init --gh-pages` 🪄 💚
+# Ensure your GitHub Pages settings for this repository are set to deploy with **GitHub Actions**.
 
-# Only run this when the master branch changes
+name: Jupyter Book (via myst) GitHub Pages Deploy
 on:
   push:
-    branches:
-    - main
+    # Runs on pushes targeting the default branch
+    branches: [main]
+env:
+  # `BASE_URL` determines, relative to the root of the domain, the URL that your site is served from.
+  # E.g., if your site lives at `https://mydomain.org/myproject`, set `BASE_URL=/myproject`.
+  # If, instead, your site lives at the root of the domain, at `https://mydomain.org`, set `BASE_URL=''`.
+  BASE_URL: /${{ github.event.repository.name }}
 
-# Build the docs and publish to gh-pages
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
 jobs:
-  deploy-book:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
-    - name: Build the jupyter-book
-      uses: addnab/docker-run-action@v3
-      with: 
-          image: craigwillis/jupyter-book:latest
-          options: -v ${{ github.workspace }}:/src
-          run: jupyter-book build --all .
-    # Push the book's HTML to github-pages
-    - name: GitHub Pages action
-      uses: peaceiris/actions-gh-pages@v3.6.1
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./_build/html
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+      - name: Install Jupyter Book (via myst)
+        run: npm install -g jupyter-book
+      - name: Build HTML Assets
+        run: jupyter-book build --html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/_config.yml b/_config.yml
diff --git a/_toc.yml b/_toc.yml
diff --git a/docs/barriers.md b/docs/barriers.md
@@ -28,7 +28,7 @@ within a specific system.
 Research in the social sciences often relies on access to {term}`sensitive <Sensitive data>` 
 or {term}`proprietary <Proprietary data>` data that cannot be redistributed
 and, in many cases, is only accessible to authorized users on [access-controlled
-resources](barriers-large-specialized-compute). This includes data collected by
+resources](#barriers-large-specialized-compute). This includes data collected by
 researchers and stored on secure infrastructure at their institutions;
 confidential private-sector, school district, or government administrative data;
 as well as data from national statistical agencies. The results of research may

diff --git a/docs/case-profiles.md b/docs/case-profiles.md
@@ -1,8 +1,8 @@
 # Case Studies
 
-* [Statistical Research Data Centers](caseprofile-rdc)
-* [BPLIM](caseprofile-bplim)
-* [IPUMS](caseprofile-ipums)
+* [Statistical Research Data Centers](#caseprofile-rdc)
+* [BPLIM](#caseprofile-bplim)
+* [IPUMS](#caseprofile-ipums)
 * Research Cluster
 * Twitter 
 * Peer-review journal verification processes
diff --git a/docs/case-profiles/bplim.md b/docs/case-profiles/bplim.md
@@ -5,7 +5,7 @@ The [Banco de Portugal Microdata Research
 Laboratory](https://bplim.bportugal.pt/content/access-0) (BPLIM) provides access
 to datasets about the Portuguese economy. The following summary is based on the
 BPLIM [Guide for
-Researchers](https://msites-dee-bplim-prd.azurewebsites.net/sites/default/files/guide_for_researchers_v202210.pdf) and [Guimarães (2023)](https://doi.org/10.1162/99608f92.54a00239).
+Researchers](https://bplim.github.io/Manuals/Guides/01_Guide_for_Researchers/) and [Guimarães (2023)](https://doi.org/10.1162/99608f92.54a00239).
 
 ## Data access
 
@@ -47,7 +47,7 @@ More recently, they have been pushing researches to work with  Singularity conta
 
 **The app could be augmented to generate a TRO. The app itself would be described as part of the TRS.**
 
-> The initial TRO in the current usage is not useful to the researcher, since it only tells the BPLIM staff that the code runs cleanly. The confidential TRO generated by the app (TRS) on the confidential data needs vetting, similar to the [FSRDC case](caseprofile-rdc). 
+> The initial TRO in the current usage is not useful to the researcher, since it only tells the BPLIM staff that the code runs cleanly. The confidential TRO generated by the app (TRS) on the confidential data needs vetting, similar to the [FSRDC case](#caseprofile-rdc). 
 
 ## Archiving
 

diff --git a/docs/case-profiles/rdc.md b/docs/case-profiles/rdc.md
@@ -1,7 +1,7 @@
 (caseprofile-rdc)=
 # Federal Research Data Centers
 
-Jump to [TRACE in the FSRDC](caseprofile-trace-in-the-rdc).
+Jump to [TRACE in the FSRDC](#caseprofile-trace-in-the-rdc).
 
 [Federal Statistical Research Data
 Centers](https://www.census.gov/about/adrm/fsrdc.html) (FSRDC) provide secure
@@ -64,7 +64,7 @@ not preserved or de-accessioned, a record of the when and why should be kept.
 
 ### TRACE System description
 
-A TRACE System description should be published. The content should conform to the [TRACE System](element-trace-system), and could be made human-readable as a  webpage that has
+A TRACE System description should be published. The content should conform to the [TRACE System](#element-trace-system), and could be made human-readable as a  webpage that has
 structured, machine-readable content. It is expected
 that a TRACE System description does not reveal sensitive information. It should
 include principles of disclosure review. In principle, a duly

diff --git a/docs/case-profiles/twitter.md b/docs/case-profiles/twitter.md
@@ -4,7 +4,7 @@
 Twitter provides access to data for [Academic
 Research](https://developer.twitter.com/en/products/twitter-api/academic-research).
 The Twitter [Developer Agreement and
-Policy](https://developer.twitter.com/en/developer-terms/agreement-and-policy)
+Policy](https://web.archive.org/web/20220307191453/https://developer.twitter.com/en/developer-terms/agreement-and-policy)
 includes the following content redistribution policy:
 
 > If you provide Twitter Content to third parties, including downloadable
@@ -55,4 +55,4 @@ whether a "re-hydrated" dataset matches the original.
 
 ### Examples
 
-See [Twitter](example-twitter) examples.
+See [Twitter](#example-twitter) examples.
diff --git a/docs/dev/signing.md b/docs/dev/signing.md
@@ -7,8 +7,8 @@ non-repudiability (the signer cannot deny that they signed it). The signature
 mechanism determines how TROs are verified and TRACE is concerned with verifying
 the signature at the time of TRO creation even if the signing key/certificate
 has expired or been revoked/invalidated.  We have considered initially using
-[GPG](signing-gpg) with possible future support for [X.509
-certificates](signing-x509). 
+[GPG](#signing-gpg) with possible future support for [X.509
+certificates](#signing-x509). 
 
 A key difference between these two approaches is the underlying trust model.
 In public key infrastructure (PKI), trust models define how the authenticity of

diff --git a/docs/documentation-infrastructure.md b/docs/documentation-infrastructure.md
@@ -16,6 +16,7 @@ For the specification content itself, see [TRACE Specifications](specifications.
 
 ---
 
+(repositories)=
 ## Repositories
 
 Four repositories under the [transparency-certified](https://github.com/transparency-certified) GitHub organization contribute to the public documentation:
@@ -31,6 +32,7 @@ GitHub serves all of these independently under the same domain via its CDN. The
 
 ---
 
+(how-the-pieces-connect)=
 ## How the Pieces Connect
 
 ### Public URL structure
@@ -52,6 +54,7 @@ transparency-certified.github.io/
     └── trov/prerelease/               Generated by Widoco from trov submodule
 ```
 
+(source-file-layout)=
 ### Source file layout
 
 To edit content, work with the source files on the `main` branch of each repository. The build pipelines (described below) generate and deploy the public site automatically.
@@ -94,6 +97,7 @@ The `trace-specification` and `trace-vocabularies` repos each deploy to an orpha
 
 ---
 
+(the-project-website)=
 ## The Project Website
 
 The **[transparency-certified.github.io](https://github.com/transparency-certified/transparency-certified.github.io)** repository is a standard [Jekyll](https://jekyllrb.com/) site. GitHub Pages builds it automatically from the `main` branch using its built-in Jekyll support — no GitHub Action or Docker image is needed.
@@ -102,6 +106,7 @@ The site provides a landing page with project description and team information,
 
 ---
 
+(the-specification-site)=
 ## The Specification Site
 
 The **[trace-specification](https://github.com/transparency-certified/trace-specification)** repository contains the specification documents as Markdown files in `docs/`. The build and deploy process works as follows:
@@ -150,6 +155,7 @@ Each page on the built site offers Markdown and PDF downloads via the toolbar. T
 
 ---
 
+(the-vocabulary-reference)=
 ## The Vocabulary Reference
 
 The **[trace-vocabularies](https://github.com/transparency-certified/trace-vocabularies)** repository is a build hub that aggregates vocabulary source repos as git submodules. It runs Widoco to generate HTML documentation and serialization files, then deploys everything to GitHub Pages.
@@ -182,6 +188,7 @@ The action uses `peaceiris/actions-gh-pages@v4` to push the built output to an o
 
 A [vocabulary index page](https://transparency-certified.github.io/trace-vocabularies/) (`index.html` in the repo root) is copied into the build output during each deploy. It lists all published vocabularies and versions, and serves as the default landing page for unversioned requests via w3id.org.
 
+(updating-after-vocabulary-changes)=
 ### Updating After Vocabulary Changes
 
 Pushing changes to a vocabulary repo (e.g. trov) does not automatically rebuild the site. The trace-vocabularies repo uses git submodules. Each submodule records a specific commit from the vocabulary repo. To pick up new vocabulary content, you advance the submodule pointer and push to trace-vocabularies, which triggers the build workflow.
@@ -190,6 +197,7 @@ The submodule pointer is a deliberate decision, not an automatic sync. This mean
 
 For the specific git commands to advance submodule pointers, pin to a tagged release, or check submodule status, see the [trace-vocabularies README](https://github.com/transparency-certified/trace-vocabularies#updating-vocabulary-documentation).
 
+(testing-the-w3id-org-redirect-rules)=
 ### w3id.org Namespace Resolution
 
 TROV namespace URIs (e.g. `https://w3id.org/trace/trov/0.1#ArtifactComposition`) resolve via redirect rules in a `.htaccess` file registered at [w3id.org](https://w3id.org/). The rules perform content negotiation: RDF tools requesting Turtle get `trov.ttl`, JSON-LD processors get `trov.jsonld`, and browsers get the HTML documentation page. The redirect targets are the GitHub Pages URLs served by trace-vocabularies.
@@ -202,6 +210,7 @@ The w3id.org `.htaccess` rules redirect namespace URI requests to files on GitHu
 
 ---
 
+(adding-a-page-to-the-specification)=
 ## Adding a Page to the Specification
 
 To add a new document to the specification site: