Add GitHub Pages site for the workshop guide#19
Merged
Conversation
Publishes GettingStartedWithSpec-DrivenDev.md and reference.md as a navigable Jekyll site under docs/, with a sticky per-page heading TOC (minimal-mistakes theme, toc: true via defaults). Source files are symlinked into docs/ so they remain the single source of truth. Fixes one broken link in reference.md — a leftover Google-Docs anchor (?tab=t.0#heading=...) — now pointing at the "Safety first! Sandboxing" section. Deploys via GitHub Actions (push to main + workflow_dispatch), so the PR branch can be previewed before merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
workflow_dispatch needs the workflow YAML on the default branch before it can be invoked. Adding a pull_request trigger lets the PR preview deploy without that chicken-and-egg. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
GitHub runners are x86_64-linux; the lock was arm64-darwin-only from the local macOS build. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lets the first run of this workflow flip the repo Pages source to GitHub Actions rather than requiring a manual Settings toggle. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sourceless
had a problem deploying
to
github-pages
GitHub Actions
Failure
pull_request-triggered runs use refs/pull/N/merge, which can't match a branch policy on the github-pages environment. Triggering on push uses the branch ref directly, which the environment can allow via its custom branch policy list. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
configure-pages@v5 injects baseurl into _config.yml at repo root by default, but ours lives in docs/, so the injection silently missed and the site was served with domain-absolute /assets/... URLs that 404'd against adzerk.github.io/spec-driven-workshop/. Setting url and baseurl explicitly fixes it without needing the workflow to know where the Jekyll config lives. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The guide source starts with a H1 of its own, and the theme's single layout also renders page.title as a heading, so the rendered page showed the same title twice. A scoped hide_page_title flag + a conditional style in the custom head include suppresses the theme heading only on pages that already carry an in-content H1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ohpauleez
approved these changes
Apr 24, 2026
Collaborator
ohpauleez
left a comment
ohpauleez
left a comment
There was a problem hiding this comment.
Thanks! It's nice to see it formatted!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
GettingStartedWithSpec-DrivenDev.mdandreference.mdas a navigable Jekyll site underdocs/, with a sticky per-page heading TOC (minimal-mistakes theme).docs/— they remain the single source of truth and are not duplicated or rewritten.reference.md(a leftover Google-Docs anchor?tab=t.0#heading=...) to point at the "Safety first! Sandboxing" section of the guide. Works on the raw GitHub markdown render and gets rewritten to/guide.html#safety-first-sandboxingon the site byjekyll-relative-links.push: main+workflow_dispatch, so this branch can be previewed at the production Pages URL before merge.One-time repo setup
Settings → Pages → Source: GitHub Actions — required once for
actions/deploy-pages@v4to attach. Cannot be done from code.Test plan
gh workflow run pages.yml --ref worktree-github-pagesto preview this branch athttps://adzerk.github.io/spec-driven-workshop//guide.htmlrenders with a sticky sidebar TOC listing all 23 H3/H4 headings; clicking a TOC entry jumps to the anchor/reference.htmlrenders, and the "strong sandbox" link jumps to/guide.html#safety-first-sandboxingmainre-triggers the workflow automatically and the site stays live