docs: add Template Gallery + docs PR preview workflow by rajivml · Pull Request #602 · UiPath/uipath-typescript

rajivml · 2026-07-15T10:58:25Z

What

Adds a Template Gallery to the documentation site, plus the CI to build and preview docs on PRs. Two commits:

docs: — the Template Gallery page + nav entry + a contributor convention.
ci: — a Docs PR Preview workflow (build gate + per-PR preview).

1. Template Gallery (`docs/samples/index.md`, `mkdocs.yml`, `Agents.md`)

A config-driven, browsable index of everything under samples/ — category tabs, framework + tag filters, search, and each sample's demo GIF. New nav entry sits after Sample Application.

Native Material page — no iframe. Scoped under a .tg root and mapped to Material's theme variables, so it follows the docs light/dark toggle and brand color.
Per-card actions: Clone (copies npx degit UiPath/uipath-typescript/samples/<path> <name> — verified for top-level and nested samples) and Open in VS Code (same degit chained with && code <name>).
Self-contained: inline config/CSS/JS, no new build dependencies.
Agents.md gains a convention: adding a sample requires a preview GIF in its screenshots/ folder and a matching Template Gallery entry, so the site stays in sync.

2. Docs PR Preview workflow (`.github/workflows/docs-pr-preview.yml`)

Closes a gap: docs.yml only builds/deploys on a schedule + manual dispatch, so nothing validated or previewed docs on a PR.

Builds the docs on every PR touching docs/** or mkdocs.yml — the build is a CI gate, so a broken docs change fails a check instead of shipping.
Publishes a per-PR preview at …/pr-preview/pr-<N>/ for same-repo PRs, torn down on close.
Security: pull_request (not pull_request_target); write-scoped deploy gated to same-repo PRs; no untrusted event data in run: steps; third-party action pinned to a commit SHA.
One-time after merge: Settings → Actions → Workflow permissions → Read and write (so previews can publish to gh-pages).

Preview

Isolated full-site build of this branch (temporary, personal Pages repo):
https://rajivml.github.io/uipath-typescript/samples/

🤖 Generated with Claude Code

claude · 2026-07-15T11:04:09Z

One issue found — see inline comment on lines 218–219 of docs/samples/index.md: missing closing tag for .tg-body in the card() function. Browsers auto-correct it so the page renders correctly, but the HTML is malformed. Fix: change h += "</div>"; to h += "</div></div>";

claude · 2026-07-15T11:09:08Z

Review summary

One new finding posted this run:

docs/samples/index.md line 182 — ARIA role mismatch on category tabs

Category tabs use role=tab inside a role=tablist but set aria-pressed instead of aria-selected. Screen readers will announce these as toggle buttons rather than tabs, breaking the expected keyboard/AT navigation pattern. The companion CSS selector on line 64 (.tg-pill[aria-pressed=true]) also needs to be updated to [aria-selected=true].

Add a config-driven Template Gallery page that previews every app under samples/, with category tabs, framework and tag filters, search, and a per-card clone command. Rendered natively in Material for MkDocs so it follows the docs light/dark theme. Adds a nav entry after Sample Application and an Agents.md convention to keep the gallery and preview GIFs in sync when samples change.

claude · 2026-07-15T11:14:16Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

claude · 2026-07-15T11:15:11Z

New finding this run:

docs/samples/index.md:182 — role="tab" buttons in renderTabs() use aria-pressed instead of aria-selected. WAI-ARIA requires aria-selected for tab state; aria-pressed is for toggle buttons. The CSS at line 64 also needs a matching [aria-selected="true"] selector so the visual highlight still applies after the fix.

Builds the docs site on every PR touching docs/ or mkdocs.yml (build doubles as a CI gate) and publishes a per-PR preview to gh-pages/pr-preview/pr-<N>/ for same-repo PRs, removed on close. pull_request only, write-scoped deploy gated to same-repo, no untrusted interpolation, third-party action pinned to a SHA.

github-actions · 2026-07-15T11:25:46Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-20 09:02 UTC

role=tab controls require aria-selected, not aria-pressed; screen readers otherwise announce them as toggle buttons. Filter pills keep aria-pressed as they are toggle buttons. CSS matches both states.

claude · 2026-07-15T11:34:33Z

Review summary

One new finding posted this run:

.github/workflows/docs-pr-preview.yml:47 — Node.js 18 instead of 20: The project requires Node 20+ (per architecture.md), and every other workflow in the repo uses Node 20. The workflow should use node-version: "20" to stay consistent and avoid running npm run docs:api under an unsupported Node version.

Use --md-code-font-family for the mono accents so they match inline code elsewhere in the docs, and set card description to 0.8rem to match docs body.

claude · 2026-07-15T11:42:13Z

Review summary

One new finding posted this run:

.github/workflows/docs-pr-preview.yml:84 — Stale version tag in comment: The comment says # v1.6.1 but the PR Preview Action bot confirms the action ran as v1.8.1. The SHA pin is correct for security; only the human-readable label needs updating to # v1.8.1 so future maintainers aren't misled.

(The unresolved Node 18 thread on line 47 remains open from a prior run — no change there.)

Node 20.x is the stated minimum (architecture.md) and what ci.yml/coverage.yml use. Node 18 could produce different docs:api output and breaks once 18 is EOL in runners.

claude · 2026-07-15T11:46:51Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

claude · 2026-07-15T11:48:15Z

Review summary

One new finding posted this run:

docs/samples/index.md:184 — Missing arrow-key navigation on role="tablist": The category tabs use role="tablist" / role="tab" but only wire a click handler. WAI-ARIA requires arrow keys to move focus between tabs; without it, keyboard/AT users can't navigate as expected and screen readers may announce key interactions that have no effect. See the inline suggestion for a keydown handler to add to the tablist container.

(The two previously-flagged unresolved threads — Node.js version and stale action version tag — remain open from prior runs.)

The rossjrw/pr-preview-action SHA ffa7509 is release v1.8.1, not v1.6.1; fix the human-readable label (the SHA pin itself is unchanged).

claude · 2026-07-15T11:49:44Z

Review summary

One new finding posted this run:

docs/samples/index.md:222 — Cached preview GIFs stay hidden: After el.innerHTML = h, if a GIF is already in the browser cache and the card is in the viewport, img.complete is true before the load listener is attached — the event never fires again, so tg-loaded is never added and the image stays at opacity: 0. Fix: add if (img.complete) img.classList.add("tg-loaded"); immediately after the listener registration.

(The two open threads on .github/workflows/docs-pr-preview.yml — Node.js version and stale version comment — remain unresolved from prior runs.)

The category controls are a single-select filter over one grid, not a tab/tabpanel widget. Using role=tablist/tab took on the WAI-ARIA Tabs keyboard contract (arrow-key roving + a controlled tabpanel) that was not implemented. Switch to role=group + aria-pressed toggle buttons, consistent with the framework/tag filters, so standard button semantics and Tab navigation apply.

claude · 2026-07-15T13:34:07Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

Raina451 · 2026-07-20T04:40:14Z

PR Preview Action v1.8.1

🚀 View preview at
https://UiPath.github.io/uipath-typescript/pr-preview/pr-602/

Built to branch gh-pages at 2026-07-15 13:31 UTC.

Preview will be ready when the GitHub Pages deployment is complete.

this preview link show 404 :

Raina451 · 2026-07-20T04:49:18Z

I dont think these filters are accurate:
modular just showed one app - thought we have all sample apps modular except process-app-v0

oauth showed one, all using oauth

can we remove the above filters anyway? and just have these:

Raina451 · 2026-07-20T04:50:32Z

also everytime a new template added , do author need to update samples index file to add respective filter?
is there a recommended way for sample app pr to be? can we add the same in agents doc?

The production docs deploy used `mkdocs gh-deploy --force`, which force-replaces the entire gh-pages branch and deletes the pr-preview/ umbrella dir — so every open PR's preview 404'd whenever prod redeployed. Deploy the already-built site/ via JamesIves/github-pages-deploy-action with `clean-exclude: pr-preview/` (still removes stale docs pages, but keeps previews) and `force: false` (rebase, don't clobber a concurrent preview deploy) — the approach the pr-preview-action docs recommend. Also SHA-pin checkout/setup-node/setup-python to match docs-pr-preview.yml. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Two fixes from PR review of the Template Gallery: - drop the auto-generated tag filters (e.g. "modular", "oauth"): each matched only one app and read as inaccurate. Keep the category tabs, framework filter, and search (tags still feed the search box). - resolve sample assets against a single configurable `ref` (default "main") instead of hardcoding "main" in three places. An open PR's new samples aren't on main yet, so the preview 404'd their GIFs and source links. The docs PR-preview build now rewrites that one ref to the PR's head commit, where the assets exist; production keeps "main" unchanged. HEAD_SHA is passed via env and the rewrite is gated to same-repo PRs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Per review, repo conventions belong in agent_docs (included by Agents.md), not authored inline in Agents.md. Move the "samples must ship a preview GIF + keep the Template Gallery in sync" convention into agent_docs/rules.md (section Documentation) and drop the inline section from Agents.md — it flows back in via the @agent_docs/rules.md include. Also updated the wording: tags are matched by search (the tag filters were removed), category drives the tabs, framework drives the filter. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

claude · 2026-07-20T07:26:44Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

rajivml · 2026-07-20T07:28:32Z

Thanks @Raina451 — the rest of your pass is addressed too:

Filters: dropped the auto-generated tag filters (the inaccurate modular / oauth ones). Kept the category tabs, the framework filter, and search — tags still feed the search box. (a4ab90b)
"Does the author update the index for every new template?" Yes — now documented as a convention in agent_docs/rules.md (Documentation → Samples & Template Gallery): when you add/rename/remove a sample, ship its preview GIF and add/adjust its #tg-data entry in the same PR. (0540b3e)
Preview 404: fixed the gh-pages collision — see the thread on docs.yml; the production deploy no longer wipes pr-preview/. (8ca0cf0)

Left the threads open for you to verify and close.

claude · 2026-07-20T07:29:16Z

+    </div>
+    <div class="tg-row" id="tg-filters">
+      <span class="tg-flabel">Filter</span>
+      <span id="tg-fw"></span>


#tg-tabs has role="group" so AT users get the group context when navigating into it. #tg-fw has neither — screen readers will announce "React, toggle button, not pressed" with no indication these are framework filters. The visual .tg-flabel "Filter" is a sibling span, not programmatically associated.

For consistency, add the group role directly to the tg-fw span:

Suggested change

<span id="tg-fw"></span>

<span id="tg-fw" role="group"></span>

The framework filter container had no group role or accessible name, so AT users heard "React, toggle button" with no filter context. Add role="group" + aria-label, mirroring the category tabs container. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Raina451

we have 2 nav now:

do we need 2 separate nav?
we have 2 naming template and sample apps. is it okay or do we need any changes? templates and samples can be confusing for end user.

rest lgtm

claude · 2026-07-20T07:36:50Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

… link Rename the "Template Gallery" nav entry (and the page title/H1) to "Sample Apps Gallery", and remove the separate "Sample Application" nav item that just linked to the samples/ folder on GitHub — the gallery already links to each sample's source, so the folder link is redundant. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

claude · 2026-07-20T07:50:09Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

claude · 2026-07-20T07:50:59Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

Now that the "Sample Application" folder link was removed from the nav, surface it in the gallery meta row instead. Href is built from the same `ref` as the cards, so previews point at the PR commit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

claude · 2026-07-20T08:10:49Z

+    if (app.preview) h += '<a class="tg-badge-live" href="' + esc(BLOB_BASE + app.preview) + '" target="_blank" rel="noopener" title="View the preview GIF"><span class="blip"></span>Live preview</a>';
+    h += '<div class="tg-glyph"><span class="g">' + esc(monogram(app)) + '</span><span class="s">' + esc(c.label) + "</span></div>";
+    if (app.preview) h += '<img alt="' + esc(app.title) + ' preview" loading="lazy" src="' + esc(RAW_BASE + app.preview) + '" />';
+    h += '<a class="tg-thumblink" href="' + esc(folder) + '" target="_blank" rel="noopener" aria-label="Open ' + esc(app.title) + ' on GitHub"></a>';


The invisible overlay anchor (tg-thumblink) and the title anchor (tg-titlelink on line 238) both link to the same folder URL. This creates two focusable tab stops per card going to the same destination — keyboard users must press Tab twice, and screen readers announce both links.

The overlay's only purpose is to make the thumbnail area mouse-clickable; the title link already provides keyboard and AT access to the same page. Adding aria-hidden="true" and tabindex="-1" removes it from the tab order and AT tree while keeping it mouse-clickable for sighted users:

Suggested change

h += '<a class="tg-thumblink" href="' + esc(folder) + '" target="_blank" rel="noopener" aria-label="Open ' + esc(app.title) + ' on GitHub"></a>';

h += '<a class="tg-thumblink" href="' + esc(folder) + '" target="_blank" rel="noopener" aria-hidden="true" tabindex="-1"></a>';

rajivml · 2026-07-20T08:12:09Z

Thanks @Raina451 — both points from this review are now addressed:

Two nav entries → one. Removed the Sample Application item (it only linked to the samples/ folder on GitHub); that folder is now reachable via a Browse all on GitHub link inside the gallery, so there's a single nav entry. (b7b7400, e61f457)
Naming. Renamed Template Gallery → Sample Apps Gallery across the nav, page title, and H1, so "template" no longer appears — consistent "sample apps" wording for end users. (b7b7400)

Let me know if the naming works for you.

sonarqubecloud · 2026-07-20T08:13:02Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

rajivml requested a review from a team July 15, 2026 10:58