Repository navigation
Explicit onBrokenAnchors, doctor target argument, and accurate config guidance - #1
Merged
Merged
Conversation
A link to a heading that was renamed breaks silently, and workshops accumulate those as exercises are reordered and retitled. onBrokenLinks already covers links between pages; this is the in-page equivalent. Set to 'warn', which is also the Docusaurus default, so this changes no behaviour today — it makes the choice visible and gives one place to tighten it later. Deliberately not 'throw': a stale anchor is a content bug, not a reason to block a deploy on the morning of a workshop. The tradeoff is that the warning only shows in build output, so a green exit code does not mean the anchors are clean. This replaces the hand-rolled 39-line postbuild script the case management workshop carried, which walked build/docs/**/*.html to reimplement the same check. That script did fail the build; nothing does now, which is the intended change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`workshop-kit doctor bellevue-2026` silently ignored the argument and reported the default target instead, so `npm run target:check -- <target>` confirmed the wrong tenant while looking like it had confirmed the right one. That is worse than erroring, since the command exists to be trusted before a deploy. build, start and preview already take a positional target via takeTarget(), and getTarget() already accepts an explicit name — doctor just never passed one through. This wires it up the same way. Found while migrating the case management workshop, whose pre-kit script did accept the argument, so its README instructions had quietly become wrong. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The shared guidance said session-specific workshop values "must come from .env
via docusaurus.config.ts customFields.workshop". That described the pre-kit
architecture. Nothing in the kit reads a plain .env for workshop values — they
come from config/workshop-targets.json, which createWorkshopConfig publishes as
customFields.workshop. Because base.md is the fenced region of every repo's
AGENTS.md, that one wrong line was misleading in all four.
Replaced with the actual layout, since the overlap between the files is what
makes this confusing:
config/workshop-targets.json participant-visible values; committed; read by
the site and by every CLI command
.env.deploy.<target> UIPATH_FOLDER_KEY and two optional packaging
values; git-ignored; read only by codedapp
.env / .env.<target> WORKSHOP_TARGET/START/END and RE_CONTEXT; read
only by the pulse dashboard
Also records that WORKSHOP_UIPATH_* keys sitting in a .env are dead leftovers
(coding-agents-workshop still has four of them), and the target precedence:
explicit CLI argument, then WORKSHOP_TARGET, then defaultTarget.
The fence hash moves from 199aad91 to 35131c9d, so every repo needs
`npm run prepare:docs` when it repins. No repo breaks before then: each checks
against the base.md in its own pinned kit.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
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.
Three changes, all surfaced while migrating a fourth workshop (case management) onto the kit. Releases as
v1.2.0.onBrokenAnchorsset explicitlyonBrokenLinksalready covers links between pages; this is the in-page equivalent. Set to'warn', which is also the Docusaurus default, so this changes no behaviour today — it makes the choice visible and gives one place to tighten it later.Deliberately not
'throw': a stale anchor is a content bug, not a reason to block a deploy on the morning of a workshop. The tradeoff is that a green exit code no longer means the anchors are clean — the warning only appears in build output.This replaces a hand-rolled 39-line postbuild script the case management workshop carried, which walked
build/docs/**/*.htmlto reimplement the same check. That script did fail the build; nothing does now. That is a deliberate reduction in enforcement, recorded inTODO.md.Verified by planting a link to a non-existent anchor: Docusaurus names the exact page and anchor, and the build exits 0.
doctoraccepts a positional targetworkshop-kit doctor bellevue-2026silently ignored the argument and reported the default target, sonpm run target:check -- <target>confirmed the wrong tenant while looking like it had confirmed the right one. Worse than erroring, for a command whose whole purpose is to be trusted before a deploy.build,startandpreviewalready take a positional target viatakeTarget(), andgetTarget()already accepts an explicit name —doctorjust never passed one through.agents/base.md: the three config surfacesThe shared guidance claimed session-specific workshop values "must come from
.envviadocusaurus.config.tscustomFields.workshop". That described the pre-kit architecture — nothing in the kit reads a plain.envfor workshop values. Becausebase.mdis the fenced region of every repo'sAGENTS.md, that one wrong line was misleading in all four repos.Replaced with what actually reads what:
config/workshop-targets.json.env.deploy.<target>codedappcommands.env/.env.<target>Also records that stray
WORKSHOP_UIPATH_*keys in a.envare dead leftovers (coding-agents-workshopstill has four), and the target precedence: explicit CLI argument, thenWORKSHOP_TARGET, thendefaultTarget.Follow-up required after merge
The fence hash moves
199aad91->35131c9d, so all four repos neednpm run prepare:docsto regenerateAGENTS.mdas part of their repin to v1.2.0. Repinning without regenerating leavesagents:checkfailing.Nothing breaks before then: each repo validates against the
base.mdin its own pinned kit, confirmed green on all four today.Tag
v1.2.0and force-movev1after merge.Verification
Ran the
kit-ci.ymlchecks locally:npm run validate, every module parses, CLI responds, and the AGENTS.md fence round-trip (including that a tampered fence still fails the check).🤖 Generated with Claude Code