docs-refresh: add registry-based external docs deploy check

.github/workflows/docs-refresh-pr-dry-run.yml

@@ -0,0 +1,103 @@
+name: External docs refresh dry run (temporary)
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - '.github/workflows/docs-refresh*.yml'
+      - 'docs-sources.yml'
+      - 'docs/remote-markdown.md'
+      - 'lib/external-docs.js'
+      - 'lib/generate-docs-fingerprint.js'
+      - 'lib/generate-external-docs-manifest.js'
+      - 'lib/compare-docs-fingerprint.js'
+      - 'package.json'
+      - 'package-lock.json'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: external-docs-refresh-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  dry-run:
+    name: Compare external docs fingerprints without deploying
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate external docs manifest generation
+        run: npm run generate:external-docs
+
+      - name: Generate current docs fingerprint
+        run: npm run docs:fingerprint -- --output /tmp/current-docs-fingerprint.json
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Download deployed docs fingerprint
+        env:
+          DOCS_FINGERPRINT_URL: https://docs.hypercerts.org/docs-fingerprint.json
+        run: |
+          set +e
+          http_code=$(curl -sS -L -w "%{http_code}" \
+            -o /tmp/deployed-docs-fingerprint.json \
+            "$DOCS_FINGERPRINT_URL")
+          curl_status=$?
+          set -e
+
+          if [ "$curl_status" -ne 0 ]; then
+            echo "::error::Failed to download deployed docs fingerprint from $DOCS_FINGERPRINT_URL. Dry-run cannot compare against deployed state."
+            exit 1
+          fi
+
+          case "$http_code" in
+            200)
+              ;;
+            404)
+              echo '{}' > /tmp/deployed-docs-fingerprint.json
+              ;;
+            *)
+              echo "::error::Unexpected HTTP $http_code while downloading $DOCS_FINGERPRINT_URL. Dry-run cannot compare against deployed state."
+              exit 1
+              ;;
+          esac
+
+      - name: Compare fingerprints
+        id: diff
+        run: |
+          node lib/compare-docs-fingerprint.js \
+            /tmp/current-docs-fingerprint.json \
+            /tmp/deployed-docs-fingerprint.json >> "$GITHUB_OUTPUT"
+
+      - name: Report dry-run result
+        run: |
+          if [ "${{ steps.diff.outputs.changed }}" = "true" ]; then
+            echo "::notice::External docs fingerprint differs from the deployed site. The production workflow would trigger the Vercel deploy hook."
+          else
+            echo "::notice::External docs fingerprint matches the deployed site. The production workflow would do nothing."
+          fi
+
+          {
+            echo "### External docs refresh dry run"
+            echo ""
+            echo "This temporary PR-only workflow never calls the Vercel deploy hook."
+            echo ""
+            echo "Changed: ${{ steps.diff.outputs.changed || 'unknown' }}"
+            echo "Reason: ${{ steps.diff.outputs.reason || 'not computed' }}"
+            echo "Current: ${{ steps.diff.outputs.current_fingerprint || 'n/a' }}"
+            echo "Deployed: ${{ steps.diff.outputs.deployed_fingerprint || 'n/a' }}"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/docs-refresh.yml

@@ -0,0 +1,121 @@
+name: Refresh external docs
+
+on:
+  schedule:
+    - cron: '17 * * * *'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Compare fingerprints without posting to the Vercel deploy hook.'
+        required: false
+        default: true
+        type: boolean
+      force_deploy:
+        description: 'Mark the run as changed even when the deployed fingerprint matches.'
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-refresh
+  cancel-in-progress: false
+
+jobs:
+  check-docs:
+    name: Check external docs fingerprint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate current docs fingerprint
+        run: npm run docs:fingerprint -- --output current-docs-fingerprint.json
+        env:
+          DOCS_SOURCE_TOKEN: ${{ secrets.DOCS_SOURCE_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Download deployed docs fingerprint
+        env:
+          DOCS_FINGERPRINT_URL: https://docs.hypercerts.org/docs-fingerprint.json
+        run: |
+          set +e
+          http_code=$(curl -sS -L -w "%{http_code}" \
+            -o deployed-docs-fingerprint.json \
+            "$DOCS_FINGERPRINT_URL")
+          curl_status=$?
+          set -e
+
+          if [ "$curl_status" -ne 0 ]; then
+            echo "::error::Failed to download deployed docs fingerprint from $DOCS_FINGERPRINT_URL. Refusing to deploy on an unknown diff."
+            exit 1
+          fi
+
+          case "$http_code" in
+            200)
+              ;;
+            404)
+              echo '{}' > deployed-docs-fingerprint.json
+              ;;
+            *)
+              echo "::error::Unexpected HTTP $http_code while downloading $DOCS_FINGERPRINT_URL. Refusing to deploy on an unknown diff."
+              exit 1
+              ;;
+          esac
+
+      - name: Check if external docs changed
+        id: diff
+        env:
+          FORCE_DEPLOY: ${{ github.event_name == 'workflow_dispatch' && inputs.force_deploy == true }}
+        run: |
+          node lib/compare-docs-fingerprint.js \
+            current-docs-fingerprint.json \
+            deployed-docs-fingerprint.json >> "$GITHUB_OUTPUT"
+
+          if [ "$FORCE_DEPLOY" = "true" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "reason=forced by workflow_dispatch input" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Trigger Vercel deployment
+        if: steps.diff.outputs.changed == 'true'
+        env:
+          DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
+          VERCEL_DEPLOY_HOOK_URL: ${{ secrets.VERCEL_DEPLOY_HOOK_URL }}
+        run: |
+          if [ "$DRY_RUN" = "true" ]; then
+            echo "workflow_dispatch dry_run=true; skipping Vercel deploy hook."
+            exit 0
+          fi
+
+          if [ -z "$VERCEL_DEPLOY_HOOK_URL" ]; then
+            echo "::error::VERCEL_DEPLOY_HOOK_URL is required when external docs have changed. Create a Vercel Deploy Hook for the production branch and store its URL as a GitHub Actions secret."
+            exit 1
+          fi
+
+          curl -fsS -X POST "$VERCEL_DEPLOY_HOOK_URL"
+
+      - name: Write summary
+        if: always()
+        run: |
+          {
+            echo "### External docs refresh"
+            echo ""
+            echo "Changed: ${{ steps.diff.outputs.changed || 'unknown' }}"
+            echo "Reason: ${{ steps.diff.outputs.reason || 'not computed' }}"
+            echo "Dry run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}"
+            echo "Current: ${{ steps.diff.outputs.current_fingerprint || 'n/a' }}"
+            echo "Deployed: ${{ steps.diff.outputs.deployed_fingerprint || 'n/a' }}"
+          } >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -6,6 +6,10 @@ out/
 
 # Generated at build time by lib/generate-*.js — no need to track
 public/raw/
+public/external-docs.json
+public/docs-fingerprint.json
 public/search-index.json
 public/sitemap.xml
+current-docs-fingerprint.json
+deployed-docs-fingerprint.json
 lib/lastUpdated.json

components/CopyRawButton.js

@@ -1,18 +1,59 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { useRouter } from 'next/router';
 
-function getRawUrl(currentPath) {
+const EXTERNAL_DOCS_MANIFEST_URL = '/external-docs.json';
+
+function getGeneratedRawUrl(currentPath) {
   if (currentPath === '/') return '/raw/index.md';
   return `/raw${currentPath}.md`;
 }
 
-export function CopyRawButton() {
+async function getExternalDocRawUrl(externalDoc, signal) {
+  const response = await fetch(EXTERNAL_DOCS_MANIFEST_URL, {
+    cache: 'no-store',
+    signal,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Could not load ${EXTERNAL_DOCS_MANIFEST_URL}. Run npm run generate:external-docs before starting the docs site.`);
+  }
+
+  const manifest = await response.json();
+  const rawUrl = manifest?.sources?.[externalDoc]?.rawUrl;
+  if (!rawUrl) {
+    throw new Error(`External docs source "${externalDoc}" does not define a raw Markdown URL.`);
+  }
+
+  return rawUrl;
+}
+
+/**
+ * Render page-level actions for copying or viewing the Markdown source for the current docs page.
+ * Pages that render canonical Markdown from another repository can set `externalDoc` in frontmatter so these actions use the registry source instead of the generated local fallback.
+ */
+export function CopyRawButton({ frontmatter }) {
   const [copied, setCopied] = useState(false);
   const [copyError, setCopyError] = useState(false);
   const [isCopying, setIsCopying] = useState(false);
+  const [externalRawUrl, setExternalRawUrl] = useState(null);
   const router = useRouter();
   const currentPath = router.asPath.split('#')[0].split('?')[0] || '/';
-  const rawUrl = getRawUrl(currentPath);
+  const generatedRawUrl = getGeneratedRawUrl(currentPath);
+  const rawUrl = frontmatter?.rawUrl || externalRawUrl || generatedRawUrl;
+
+  useEffect(() => {
+    if (!frontmatter?.externalDoc || frontmatter?.rawUrl) {
+      setExternalRawUrl(null);
+      return undefined;
+    }
+
+    const controller = new AbortController();
+    getExternalDocRawUrl(frontmatter.externalDoc, controller.signal)
+      .then(setExternalRawUrl)
+      .catch(() => setExternalRawUrl(null));
+
+    return () => controller.abort();
+  }, [frontmatter?.externalDoc, frontmatter?.rawUrl]);
 
   const handleCopy = async () => {
     setIsCopying(true);

components/Layout.js

@@ -201,7 +201,7 @@ export default function Layout({ children, frontmatter }) {
 
         <main className="layout-content" id="main-content">
           <Breadcrumbs />
-          {frontmatter && <CopyRawButton />}
+          {frontmatter && <CopyRawButton frontmatter={frontmatter} />}
           <LastUpdated />
           <article>{children}</article>