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 6b0890e..2ac4fbc 100644 --- a/README.md +++ b/README.md @@ -51,8 +51,35 @@ 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. + +**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 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..9c29abe 100644 --- a/src/_data/site.js +++ b/src/_data/site.js @@ -10,20 +10,33 @@ 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 + // 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: { + // 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. 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/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 %} 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 @@