From 0f960aa1cc5c1bd53d04e5afbf1e6874134c0a4f Mon Sep 17 00:00:00 2001 From: Tjeerd Stap Date: Thu, 20 Aug 2026 15:44:15 -0700 Subject: [PATCH 1/3] Set onBrokenAnchors explicitly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- package.json | 2 +- src/config/createWorkshopConfig.mjs | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 4664fc9..1d53f1e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@uipath-lab-tec/workshop-kit", - "version": "1.1.0", + "version": "1.2.0", "description": "Shared Docusaurus infrastructure for UiPath LAB TEC workshop repos.", "license": "UNLICENSED", "type": "module", diff --git a/src/config/createWorkshopConfig.mjs b/src/config/createWorkshopConfig.mjs index 8391e49..008e741 100644 --- a/src/config/createWorkshopConfig.mjs +++ b/src/config/createWorkshopConfig.mjs @@ -1,7 +1,8 @@ /** * Docusaurus config factory. Owns everything the three workshop sites had * identical: the classic preset, themeConfig, navbar and footer shape, - * onBrokenLinks, i18n, future flags, and the customFields.workshop wiring. + * onBrokenLinks/onBrokenAnchors, i18n, future flags, and the customFields.workshop + * wiring. * * A content repo's docusaurus.config.ts becomes: * @@ -100,6 +101,12 @@ export function createWorkshopConfig(overrides = {}) { projectName, onBrokenLinks: 'throw', + // Set explicitly, though 'warn' is also the Docusaurus default: a renamed + // heading breaks every in-page link pointing at it, and a workshop + // accumulates that as exercises are reordered. Deliberately not 'throw' — + // a stale anchor is a content bug, not a reason to block a deploy the day + // of a workshop. Read the build output rather than trusting a green exit. + onBrokenAnchors: 'warn', i18n: { defaultLocale: 'en', From c615dbd7ca49a24317b64a5616da694d348f1ea7 Mon Sep 17 00:00:00 2001 From: Tjeerd Stap Date: Thu, 20 Aug 2026 15:44:43 -0700 Subject: [PATCH 2/3] Let doctor inspect the target you name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `workshop-kit doctor bellevue-2026` silently ignored the argument and reported the default target instead, so `npm run target:check -- ` 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 --- bin/workshop-kit.mjs | 8 ++++++-- src/commands/doctor.mjs | 4 ++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/bin/workshop-kit.mjs b/bin/workshop-kit.mjs index 9c37cf3..e4af01e 100755 --- a/bin/workshop-kit.mjs +++ b/bin/workshop-kit.mjs @@ -25,7 +25,7 @@ const USAGE = `workshop-kit codedapp pulse tenant pulse dashboard validate-config check every target in config/workshop-targets.json - doctor report kit version, resolved target and drift + doctor [target] report kit version, resolved target and drift init --product [--title ] scaffold a new workshop repo --help, --version @@ -167,8 +167,12 @@ async function main() { } case 'doctor': { + // Accepts a target the same way build/start/preview do. Without this it + // silently reported the default target while the caller believed they + // were inspecting the one they named. + const target = takeTarget(argv); const {doctor} = await import(join(commandsDir, 'doctor.mjs')); - return doctor({}); + return doctor({target}); } case 'init': { diff --git a/src/commands/doctor.mjs b/src/commands/doctor.mjs index cd19000..24cdcc9 100644 --- a/src/commands/doctor.mjs +++ b/src/commands/doctor.mjs @@ -14,7 +14,7 @@ import {agentsCheck} from './agents-build.mjs'; const kitRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..'); -export function doctor({root = process.cwd()} = {}) { +export function doctor({root = process.cwd(), target: explicitTarget} = {}) { const kit = JSON.parse(readFileSync(join(kitRoot, 'package.json'), 'utf8')); const notes = []; @@ -39,7 +39,7 @@ export function doctor({root = process.cwd()} = {}) { console.log(`default ${config.defaultTarget}`); try { - const {targetName, target} = getTarget(); + const {targetName, target} = getTarget(explicitTarget); console.log(`resolved ${targetName} -> ${target.siteUrl}${target.baseUrl}`); console.log(`tenant check ${target.requiresTenantAccess ? 'enabled' : 'disabled'} for this target`); } catch (error) { From 0fb009c005559835f0263d21fac53fc576eef536 Mon Sep 17 00:00:00 2001 From: Tjeerd Stap Date: Fri, 21 Aug 2026 08:52:04 -0700 Subject: [PATCH 3/3] Document the three config surfaces, and drop a stale .env claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. UIPATH_FOLDER_KEY and two optional packaging values; git-ignored; read only by codedapp .env / .env. 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 --- agents/base.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/agents/base.md b/agents/base.md index 08fa6c4..1441ce1 100644 --- a/agents/base.md +++ b/agents/base.md @@ -38,8 +38,36 @@ This section is shared workshop guidance. Keep it exactly the same across worksh - Verify MDX changes with `npm run build` when practical; the repo scripts should run the docs preparation and checks automatically. Before deploying a target, run `npm run build:target -- `. ### Workshop Configuration Variables -- Session-specific workshop values must come from `.env` via `docusaurus.config.ts` `customFields.workshop`; do not hard-code them in docs. -- Required variables are `WORKSHOP_UIPATH_ORG_NAME`, `WORKSHOP_UIPATH_TENANT_NAME`, `WORKSHOP_UIPATH_TENANT_URL`, and `WORKSHOP_ORCHESTRATOR_PARENT_FOLDER`. + +There are three separate configuration surfaces. They are not interchangeable, +and each has exactly one owner. If you are unsure where a value belongs, ask +which of these three reads it. + +**1. `config/workshop-targets.json` — everything participants see. Committed.** +- The single source for org name, tenant name, tenant URL and parent folder. Per target, under `targets..workshop`. +- `createWorkshopConfig()` reads it at build time and publishes it as Docusaurus `customFields.workshop`; the `WorkshopEnv` components read it from there. Docs never see a file or an env var. +- Every `workshop-kit` command reads the same file, so the CLI and the rendered site can never disagree. +- Safe for participants to read. Never put a folder key, credential, token or any deployment-only value here. +- Base fields are `uipathOrgName`, `uipathTenantName`, `uipathTenantUrl`, `orchestratorParentFolder`, rendered by the tokens `WORKSHOP_UIPATH_ORG_NAME`, `WORKSHOP_UIPATH_TENANT_NAME`, `WORKSHOP_UIPATH_TENANT_URL`, `WORKSHOP_ORCHESTRATOR_PARENT_FOLDER`. Declare anything extra under `extraFields`, which derives the token, the type and the payload from one place. + +**2. `.env.deploy.` — deployment only. Git-ignored, never committed.** +- Read by the `codedapp` commands and nothing else. It has no effect on the built site. +- Supplies exactly three values: `UIPATH_FOLDER_KEY` (required to deploy), `UIPATH_CODEDAPP_VERSION` and `UIPATH_CODEDAPP_AUTHOR` (both optional). +- An already-set process env var wins over the file. +- Copy `.env.deploy.example` to `.env.deploy.` to create one. + +**3. `.env` and `.env.` — the tenant pulse dashboard only.** +- Read by `workshop-kit pulse` and nothing else. Not by the build, not by the docs, not by deployment. +- Supplies `WORKSHOP_TARGET`, `WORKSHOP_START`, `WORKSHOP_END`, `RE_CONTEXT`. +- A plain `.env` does **not** feed workshop values into the site. If you find `WORKSHOP_UIPATH_*` keys in a `.env`, they are dead leftovers from before the kit; the values in `config/workshop-targets.json` are what actually render. Do not add them, and do not trust them when they are there. + +**Choosing the target.** All three layers are keyed by target name. Precedence is +an explicit CLI argument (`workshop-kit build `), then the +`WORKSHOP_TARGET` env var, then `defaultTarget` in +`config/workshop-targets.json`. `build:target` and `start:target` set +`WORKSHOP_TARGET` for the Docusaurus process. + +Other rules for these values: - Use `WorkshopValue`, `WorkshopLink`, or `WorkshopCodeBlock` from `src/components/WorkshopEnv.tsx` when showing these values in MDX. - In copyable prompts, use `WorkshopCodeBlock` and tokens such as `{{WORKSHOP_UIPATH_ORG_NAME}}` so rendered prompts include the current session values. - Keep participant-specific names such as participant folder names and exercise bucket names as explicit placeholders unless a dedicated workshop variable exists for them.