Merge PR #481: Fix Pages deploy: repoint link probes off pruned docs + verify render in PR CI

Author: merge-queue-bot

.github/workflows/pages.yml

@@ -11,11 +11,12 @@ name: Deploy mdsmith.dev
 # site is pure HTML built from docs/**/*.md and the homepage data
 # files, so it never needs the registry-publish credentials.
 #
-# The `build-content` job (synced-tree lint) runs on push to main
-# AND on every pull_request that touches the same paths, so a
-# broken-link regression fails the PR rather than only surfacing
-# after merge. The `deploy` job is gated to main, so PR runs stop
-# at the lint and never publish.
+# The `build-content` job runs on push to main AND on every
+# pull_request that touches the same paths. It lints the synced
+# tree, then renders the site with Hugo and runs the rendered-HTML
+# probes (verify-website-links), so a broken-link OR render-link
+# regression fails the PR rather than only surfacing after merge.
+# The `deploy` job is gated to main, so PR runs stop before publish.
 on:
   push:
     branches: [main]
@@ -75,13 +76,14 @@ jobs:
     uses: ./.github/workflows/mdsmith-check.yml
 
   build-content:
-    # The synced-tree lint: build the Hugo content tree from
-    # docs/, then run `mdsmith check` against it with the
-    # build-output config (link integrity on, style rules off).
-    # Catches broken-link regressions on PR rather than only on
-    # the post-merge deploy. deploy `needs: build-content`, so
-    # push / workflow_dispatch / workflow_call runs all gate on
-    # this lint before publishing.
+    # Build the Hugo content tree from docs/, run `mdsmith check`
+    # against it with the build-output config (link integrity on,
+    # style rules off), then render the site with Hugo and probe the
+    # rendered HTML (verify-website-links). Catches both broken-link
+    # and render-link regressions on PR rather than only on the
+    # post-merge deploy. deploy `needs: build-content`, so push /
+    # workflow_dispatch / workflow_call runs all gate on this job
+    # before publishing.
     #
     # deploy re-runs the same sync and lint after the
     # version-stamp + site-assets pulls (which mutate docs/
@@ -96,6 +98,10 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    env:
+      # Render the site with the same Hugo the deploy uses so the
+      # rendered-HTML probes below run on PR, not only post-merge.
+      HUGO_VERSION: "0.161.1"
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
@@ -125,6 +131,45 @@ jobs:
             --config ./website/build-output.mdsmith.yml \
             --no-gitignore \
             ./website/content/docs
+      - name: Install Hugo
+        # `go install` resolves via the Go module proxy with sumdb
+        # checksum verification, so the binary is pinned by content
+        # hash even though the version selector is a tag.
+        run: go install github.com/gohugoio/hugo@v${HUGO_VERSION}
+      - name: Render site
+        # Render the synced tree so the steps below can probe the
+        # real rendered HTML. The synced-tree lint above operates on
+        # the markdown filesystem (pre-render) and cannot see the
+        # render-link hook output, which is exactly what broke the
+        # deploy after the maintainer-doc prune: a probe pinned to a
+        # now-unpublished page. Root baseURL — the production deploy
+        # is served from the domain root, so relURL emits root paths.
+        working-directory: website
+        env:
+          HUGO_ENVIRONMENT: production
+        run: hugo --minify --baseURL "/"
+      - name: Verify render-link hook output
+        # Probe the rendered HTML for the render-link behaviors
+        # (.md → permalink, site-absolute /rules/ hrefs, no leaked
+        # README.md / javascript: / data: targets). The probes live
+        # in internal/release/verifylinks.go with unit-test coverage.
+        # The deploy job runs the same check, but only on main; this
+        # PR-time copy fails a regression before merge.
+        run: |
+          go run ./cmd/mdsmith-release verify-website-links \
+            --dir ./website/public --base-url ""
+      - name: Verify baseURL prefix on absolute hrefs
+        # Re-render with a fake subpath baseURL and re-probe, so a
+        # render-link regression in the relURL prefixing (which a
+        # root-baseURL render cannot exercise) also fails the PR.
+        working-directory: website
+        run: |
+          hugo --minify --baseURL "https://example.com/mdsmith/" \
+            --destination /tmp/baseurl-probe
+          cd ..
+          go run ./cmd/mdsmith-release verify-website-links \
+            --dir /tmp/baseurl-probe \
+            --base-url "https://example.com/mdsmith/"
 
   deploy:
     name: Deploy mdsmith.dev to GitHub Pages

cmd/mdsmith-release/main_test.go

@@ -298,17 +298,14 @@ func TestRunBuildWebsiteEndToEnd(t *testing.T) {
 // exercised end-to-end.
 func TestRunVerifyWebsiteLinksHappyPath(t *testing.T) {
 	root := t.TempDir()
-	mq := filepath.Join(root, "development", "merge-queue", "index.html")
-	aa := filepath.Join(root, "development", "architecture-audit", "index.html")
+	ref := filepath.Join(root, "reference", "index.html")
 	st := filepath.Join(root, "reference", "schema-types", "index.html")
 	rule := filepath.Join(root, "rules", "mds001", "index.html")
-	for _, dir := range []string{filepath.Dir(mq), filepath.Dir(aa), filepath.Dir(st), filepath.Dir(rule)} {
+	for _, dir := range []string{filepath.Dir(ref), filepath.Dir(st), filepath.Dir(rule)} {
 		require.NoError(t, os.MkdirAll(dir, 0o755))
 	}
-	require.NoError(t, os.WriteFile(mq,
-		[]byte(`<a href="/development/pr-fixup-workflow/">x</a>`), 0o644))
-	require.NoError(t, os.WriteFile(aa,
-		[]byte(`<a href="/development/architecture/">x</a>`), 0o644))
+	require.NoError(t, os.WriteFile(ref,
+		[]byte(`<a href="/reference/cli/">x</a>`), 0o644))
 	require.NoError(t, os.WriteFile(st,
 		[]byte(`<a href="/rules/mds020-required-structure/">x</a>`), 0o644))
 	require.NoError(t, os.WriteFile(rule,

internal/release/verifylinks.go

@@ -80,16 +80,17 @@ func websiteLinkProbes(prefix string) []linkProbe {
 	hrefEq := `href="?` // allow both quoted (default) and unquoted (minified) emission
 	return []linkProbe{
 		{
+			// A `.md` content link must render to the target
+			// page's clean permalink (trailing slash, no `.md`).
+			// reference/index.md links its sibling `cli.md`, which
+			// Hugo serves at /reference/cli/. Pinned to a stable
+			// user-facing page; the previous form pointed at a
+			// docs/development/ page that the maintainer-doc prune
+			// removed from the published site.
 			name: "sibling .md resolves to target permalink",
-			path: "development/merge-queue/index.html",
+			path: "reference/index.html",
 			wantMatch: regexp.MustCompile(
-				hrefEq + q(prefix) + `/development/pr-fixup-workflow/`),
-		},
-		{
-			name: "index.md drop resolves to section URL on leaf page",
-			path: "development/architecture-audit/index.html",
-			wantMatch: regexp.MustCompile(
-				hrefEq + q(prefix) + `/development/architecture/`),
+				hrefEq + q(prefix) + `/reference/cli/`),
 		},
 		{
 			// The rewriter emits site-absolute `/rules/<id>/`

internal/release/verifylinks_test.go

@@ -19,10 +19,11 @@ import (
 func goodSite(t *testing.T, prefix string) string {
 	t.Helper()
 	root := t.TempDir()
-	writeFile(t, filepath.Join(root, "development", "merge-queue", "index.html"),
-		`<a href="`+prefix+`/development/pr-fixup-workflow/">pr fixup</a>`)
-	writeFile(t, filepath.Join(root, "development", "architecture-audit", "index.html"),
-		`<a href="`+prefix+`/development/architecture/">arch</a>`)
+	// A .md content link rendered to a clean doc permalink
+	// (reference/index.md links its sibling cli.md, served at
+	// /reference/cli/) — satisfies the sibling-.md probe.
+	writeFile(t, filepath.Join(root, "reference", "index.html"),
+		`<a href="`+prefix+`/reference/cli/">cli</a>`)
 	writeFile(t, filepath.Join(root, "reference", "schema-types", "index.html"),
 		`<a href="`+prefix+`/rules/mds020-required-structure/">rule</a>`)
 	writeFile(t, filepath.Join(root, "rules", "mds001", "index.html"),
@@ -48,37 +49,27 @@ func TestVerifyWebsiteLinks_SubpathDeployPasses(t *testing.T) {
 // match `href=value` as well as `href="value"`.
 func TestVerifyWebsiteLinks_AcceptsUnquotedHref(t *testing.T) {
 	root := t.TempDir()
-	writeFile(t, filepath.Join(root, "development", "merge-queue", "index.html"),
-		`<a href=/development/pr-fixup-workflow/>pr fixup</a>`)
-	writeFile(t, filepath.Join(root, "development", "architecture-audit", "index.html"),
-		`<a href=/development/architecture/>arch</a>`)
+	writeFile(t, filepath.Join(root, "reference", "index.html"),
+		`<a href=/reference/cli/>cli</a>`)
 	writeFile(t, filepath.Join(root, "reference", "schema-types", "index.html"),
 		`<a href=/rules/mds020-required-structure/>rule</a>`)
 	writeFile(t, filepath.Join(root, "rules", "mds001", "index.html"),
 		`<a href=/rules/mds021/>sibling</a>`)
 	require.NoError(t, VerifyWebsiteLinks(root, ""))
 }
 
+// TestVerifyWebsiteLinks_FailsOnMissingSiblingMD removes the only
+// clean doc permalink so the recursive sibling-.md probe finds no
+// match anywhere in the rendered tree.
 func TestVerifyWebsiteLinks_FailsOnMissingSiblingMD(t *testing.T) {
 	root := goodSite(t, "")
-	writeFile(t, filepath.Join(root, "development", "merge-queue", "index.html"),
-		`<a href="pr-fixup-workflow.md">stale .md ref</a>`)
+	writeFile(t, filepath.Join(root, "reference", "index.html"),
+		`<a href="cli.md">stale .md ref</a>`)
 	err := VerifyWebsiteLinks(root, "")
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "sibling .md")
 }
 
-func TestVerifyWebsiteLinks_FailsOnIndexMDMisresolved(t *testing.T) {
-	root := goodSite(t, "")
-	// Simulate the bug PR #309 fixed: relative target stayed
-	// relative, browser resolves below the leaf page.
-	writeFile(t, filepath.Join(root, "development", "architecture-audit", "index.html"),
-		`<a href="architecture/">stale relative</a>`)
-	err := VerifyWebsiteLinks(root, "")
-	require.Error(t, err)
-	assert.Contains(t, err.Error(), "index.md drop")
-}
-
 func TestVerifyWebsiteLinks_FailsOnLeakedREADMEHref(t *testing.T) {
 	root := goodSite(t, "")
 	writeFile(t, filepath.Join(root, "rules", "mds999", "index.html"),
@@ -131,10 +122,8 @@ func TestVerifyWebsiteLinks_FailsOnMissingSiteAbsolute(t *testing.T) {
 	// Build a tree that has every required href except the
 	// site-absolute /rules/mdsxxx/ form.
 	root := t.TempDir()
-	writeFile(t, filepath.Join(root, "development", "merge-queue", "index.html"),
-		`<a href="/mdsmith/development/pr-fixup-workflow/">x</a>`)
-	writeFile(t, filepath.Join(root, "development", "architecture-audit", "index.html"),
-		`<a href="/mdsmith/development/architecture/">x</a>`)
+	writeFile(t, filepath.Join(root, "reference", "index.html"),
+		`<a href="/mdsmith/reference/cli/">x</a>`)
 	// No MDS-rule href under any subpath.
 	err := VerifyWebsiteLinks(root, "https://example.com/mdsmith/")
 	require.Error(t, err)
@@ -180,13 +169,11 @@ func TestVerifyWebsiteLinks_InvalidBaseURLWraps(t *testing.T) {
 // calls the callback with a stat error.
 func TestVerifyWebsiteLinks_MissingRecursiveRootWraps(t *testing.T) {
 	root := t.TempDir()
-	// Materialize only the non-recursive probe targets plus a
+	// Materialize only the non-recursive probe target plus a
 	// page carrying the site-absolute rule href, so we reach
 	// the recursive `no README.md leak` probe.
-	writeFile(t, filepath.Join(root, "development", "merge-queue", "index.html"),
-		`<a href="/development/pr-fixup-workflow/">x</a>`)
-	writeFile(t, filepath.Join(root, "development", "architecture-audit", "index.html"),
-		`<a href="/development/architecture/">x</a>`)
+	writeFile(t, filepath.Join(root, "reference", "index.html"),
+		`<a href="/reference/cli/">x</a>`)
 	writeFile(t, filepath.Join(root, "reference", "schema-types", "index.html"),
 		`<a href="/rules/mds020-required-structure/">x</a>`)
 	// rules/ is absent.