Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions agents/base.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -- <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.<name>.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.<target>` — 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.<target>` to create one.

**3. `.env` and `.env.<target>` — 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 <target>`), 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.
Expand Down
8 changes: 6 additions & 2 deletions bin/workshop-kit.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ const USAGE = `workshop-kit <command>
codedapp <check|pack|publish|deploy|all>
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 <slug> [--title <t>] scaffold a new workshop repo

--help, --version
Expand Down Expand Up @@ -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': {
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
4 changes: 2 additions & 2 deletions src/commands/doctor.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [];

Expand All @@ -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) {
Expand Down
9 changes: 8 additions & 1 deletion src/config/createWorkshopConfig.mjs
Original file line number Diff line number Diff line change
@@ -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:
*
Expand Down Expand Up @@ -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',
Expand Down
Loading