From b167e4e3c4fb67c6d3f981ba7fe5b90f582d3158 Mon Sep 17 00:00:00 2001 From: Derek Scruggs Date: Mon, 8 Jun 2026 19:32:25 -0500 Subject: [PATCH 1/5] Add opt-in Hypothesis inline review comments. Wire the Hypothesis embed into the base layout for inline, text-anchored review comments, as a ready-made alternative to pasting page snippets into Slack. It is off by default so production ships no third-party script. A review build enables it with HYPOTHESIS_COMMENTS=1, and HYPOTHESIS_GROUP scopes the client to a Hypothesis private group so only logged-in DB group members see and post comments. Config lives in site.js; the layout only emits the script (and the group config) when enabled. Document the env vars and the private-group / access-gated review pattern in the README. Co-Authored-By: Claude Opus 4.8 --- README.md | 21 +++++++++++++++++++++ src/_data/site.js | 9 +++++++++ src/_includes/layouts/base.njk | 13 +++++++++++++ 3 files changed, 43 insertions(+) diff --git a/README.md b/README.md index 6b0890e..851a884 100644 --- a/README.md +++ b/README.md @@ -51,8 +51,29 @@ To add a page to discovery: just create it. To exclude one, set The home page, sitemap, and `llms.txt` pick it up automatically. +## Inline review comments (Hypothesis) + +The site can load [Hypothesis](https://web.hypothes.is) for inline, +text-anchored review comments. It is **off by default** so production ships no +third-party script. Enable it only on a review build: + +```bash +HYPOTHESIS_COMMENTS=1 HYPOTHESIS_GROUP= npm run build +``` + +- `HYPOTHESIS_COMMENTS=1` injects the Hypothesis embed. +- `HYPOTHESIS_GROUP` scopes the client to a Hypothesis **private group** so only + logged-in group members see and post comments; the public sees nothing. Omit + it to use public Hypothesis annotations (not recommended for review). + +Reviewers join the private group, log in to Hypothesis, highlight text, and +comment. To also hide the Hypothesis UI itself from the public, serve the +enabled build behind an access gate (e.g. a Cloudflare Access review URL) rather +than on the public production site. + ## Deployment Pushes to `main` deploy to GitHub Pages via [`.github/workflows/deploy.yml`](./.github/workflows/deploy.yml). Set the `SITE_URL` repo variable for a custom domain (e.g. `https://learnvc.org`). +Production builds leave Hypothesis comments off (see above). diff --git a/src/_data/site.js b/src/_data/site.js index c06f0c2..82b71f8 100644 --- a/src/_data/site.js +++ b/src/_data/site.js @@ -19,6 +19,15 @@ export default { 'Digital Bazaar builds open, standards-based infrastructure for ' + 'Verifiable Credentials and decentralized identity.' }, + // Inline review comments via Hypothesis (https://web.hypothes.is). + // Off by default so production carries no third-party script. Enable on a + // review deployment with HYPOTHESIS_COMMENTS=1. Set HYPOTHESIS_GROUP to a + // Hypothesis private group id to scope the client to the DB review group; + // logged-in members of that group see/post comments, the public does not. + comments: { + enabled: process.env.HYPOTHESIS_COMMENTS === '1', + group: process.env.HYPOTHESIS_GROUP || '' + }, // Top-level nav. Verticals are appended automatically from the collection. nav: [ {text: 'Home', url: '/'}, diff --git a/src/_includes/layouts/base.njk b/src/_includes/layouts/base.njk index e1ddd08..889b7d3 100644 --- a/src/_includes/layouts/base.njk +++ b/src/_includes/layouts/base.njk @@ -59,5 +59,18 @@ {{ content | safe }} {% include "partials/footer.njk" %} + + {# Inline review comments (Hypothesis). Loads only when explicitly enabled + (HYPOTHESIS_COMMENTS=1) so production ships no third-party script. When a + private group id is configured, the client is scoped to it: logged-in DB + group members see and post comments; the public does not. #} + {% if site.comments.enabled %} + {% if site.comments.group %} + + {% endif %} + + {% endif %} From f406fda8e10713de6f8f2735ee5ab7d2a17e936a Mon Sep 17 00:00:00 2001 From: Derek Scruggs Date: Tue, 9 Jun 2026 09:02:03 -0500 Subject: [PATCH 2/5] Enable Hypothesis review comments on PR previews. Wire the Hypothesis env vars into the Cloudflare Pages preview build so each PR preview carries inline review comments, scoped to a private group. Production (GitHub Pages) is untouched and never loads Hypothesis. The build only enables comments when the HYPOTHESIS_GROUP repository variable is set, so previews stay clean until the private group id is configured. Harden the site config so comments require both the flag and a group, never loading in public groupless mode by accident. Co-Authored-By: Claude Opus 4.8 --- .github/workflows/preview.yml | 14 ++++++++++++-- README.md | 12 +++++++++--- src/_data/site.js | 5 ++++- 3 files changed, 25 insertions(+), 6 deletions(-) diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 79ca284..768c5ae 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -10,8 +10,11 @@ name: Deploy PR preview to Cloudflare Pages # 2. Add repository secrets: # CLOUDFLARE_API_TOKEN - token scoped to "Cloudflare Pages: Edit". # CLOUDFLARE_ACCOUNT_ID - your Cloudflare account id. -# Until both secrets exist the deploy step is skipped, so merging this file -# changes nothing. +# 3. (Optional) Add repository variable HYPOTHESIS_GROUP - the Hypothesis +# private group id. When set, PR previews load Hypothesis inline review +# comments scoped to that group; production (GitHub Pages) never does. +# Until the Cloudflare secrets exist the deploy step is skipped, so merging this +# file changes nothing. on: pull_request: @@ -46,6 +49,13 @@ jobs: # Each PR preview is served from its own *.pages.dev root, so # absolute URLs resolve correctly. SITE_URL is left at its default. SITE_URL: ${{ vars.PREVIEW_SITE_URL || 'https://learnvcorg.pages.dev' }} + # Inline review comments (Hypothesis) on previews only — never on + # production (GitHub Pages). Enabled only when the HYPOTHESIS_GROUP + # repo variable is set, so previews stay clean until the DB private + # group id is configured; an unset var means comments stay off rather + # than defaulting to public annotations. + HYPOTHESIS_COMMENTS: ${{ vars.HYPOTHESIS_GROUP != '' && '1' || '0' }} + HYPOTHESIS_GROUP: ${{ vars.HYPOTHESIS_GROUP }} - name: Check for Cloudflare credentials id: creds diff --git a/README.md b/README.md index 851a884..2ac4fbc 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,15 @@ HYPOTHESIS_COMMENTS=1 HYPOTHESIS_GROUP= npm run build it to use public Hypothesis annotations (not recommended for review). Reviewers join the private group, log in to Hypothesis, highlight text, and -comment. To also hide the Hypothesis UI itself from the public, serve the -enabled build behind an access gate (e.g. a Cloudflare Access review URL) rather -than on the public production site. +comment. + +**Where it's enabled:** PR previews on Cloudflare Pages only. Set the +`HYPOTHESIS_GROUP` repository variable to your private group id; the preview +workflow then builds each PR preview with comments on, scoped to that group. +Production (GitHub Pages) never loads Hypothesis. Comments stay off until the +variable is set. To also hide the Hypothesis UI from the public, keep the +enabled build behind an access gate (e.g. Cloudflare Access) rather than the +public site. ## Deployment diff --git a/src/_data/site.js b/src/_data/site.js index 82b71f8..1bb9b8d 100644 --- a/src/_data/site.js +++ b/src/_data/site.js @@ -25,7 +25,10 @@ export default { // Hypothesis private group id to scope the client to the DB review group; // logged-in members of that group see/post comments, the public does not. comments: { - enabled: process.env.HYPOTHESIS_COMMENTS === '1', + // Require both the flag and a private group id, so comments never load in + // public (groupless) mode by accident. + enabled: + process.env.HYPOTHESIS_COMMENTS === '1' && !!process.env.HYPOTHESIS_GROUP, group: process.env.HYPOTHESIS_GROUP || '' }, // Top-level nav. Verticals are appended automatically from the collection. From 17c762bf6cb7bd4fa046fcdbe0b185d4f7462955 Mon Sep 17 00:00:00 2001 From: Derek Scruggs Date: Tue, 9 Jun 2026 11:45:23 -0500 Subject: [PATCH 3/5] Apply home-page editorial review feedback. Work through the review notes left on the home page: - Lead with Student IDs; rename Education to "Diplomas"; hide Supply Chain from the chooser, nav, footer, sitemap, and llms.txt for now (the page still builds at /supply-chain/ and is one line to relist). - Rewrite the "Why VCALM?" blurb around the vendor-lock-in framing and the formats/protocols VCALM supports (W3C VCs, mDL, mDoc, SD-JWT, OID4VCI, OID4VP, HAIP, DIDComm). - Expand "VCALM" to its full name in the site description, tighten the call to action, and update the company blurb. - Add a question mark to "What is VCALM?", drop the "Why VCALM" and "See an example" links for now, collapse the footer About column, and add Verifiable Credentials and Decentralized Identifiers reference links. Co-Authored-By: Claude Opus 4.8 --- src/_data/site.js | 13 +++++++------ src/_includes/partials/footer.njk | 9 +++++---- src/index.njk | 14 ++++++++++---- src/verticals/education/index.njk | 6 +++--- src/verticals/student-id/index.njk | 2 +- src/verticals/supply-chain/supply-chain.json | 4 +++- 6 files changed, 29 insertions(+), 19 deletions(-) diff --git a/src/_data/site.js b/src/_data/site.js index 1bb9b8d..9c29abe 100644 --- a/src/_data/site.js +++ b/src/_data/site.js @@ -10,14 +10,15 @@ export default { tagline: 'Issue and verify W3C Verifiable Credentials — without vendor lock-in.', description: 'A guide to issuing and verifying W3C Verifiable ' + - 'Credentials with VCALM (the VC API). Pick a vertical, see how it ' + - 'works, ship.', + 'Credentials with the Verifiable Credential API for Lifecycle Management (VCALM). Pick a vertical, learn how it ' + + 'works, ship it.', company: { name: 'Digital Bazaar, Inc.', url: 'https://digitalbazaar.com', blurb: - 'Digital Bazaar builds open, standards-based infrastructure for ' + - 'Verifiable Credentials and decentralized identity.' + 'Digital Bazaar builds open, standards-based, production-grade digital ' + + 'credential infrastructure for some of the largest organizations and ' + + 'governments in the world.' }, // Inline review comments via Hypothesis (https://web.hypothes.is). // Off by default so production carries no third-party script. Enable on a @@ -34,8 +35,8 @@ export default { // Top-level nav. Verticals are appended automatically from the collection. nav: [ {text: 'Home', url: '/'}, - {text: 'What is VCALM', url: '/what-is-vcalm/'}, - {text: 'Why VCALM', url: '/why-vcalm/'}, + {text: 'What is VCALM?', url: '/what-is-vcalm/'}, + // {text: 'Why VCALM', url: '/why-vcalm/'}, {text: 'About', url: '/company/about/'}, {text: 'Contact', url: '/company/contact/'} ] diff --git a/src/_includes/partials/footer.njk b/src/_includes/partials/footer.njk index 62195fb..9e38019 100644 --- a/src/_includes/partials/footer.njk +++ b/src/_includes/partials/footer.njk @@ -12,16 +12,17 @@