ci: preserve hand-maintained CLI command-reference index pages on regen#4836
Merged
Conversation
The CLI command reference is auto-generated MDX. MDX is stricter than plain Markdown: bare angle-bracket placeholders, JSON-in-braces, and broken anchors can compile locally yet fail the site build. Nothing verified the generated output before it landed, so breakage only surfaced downstream. Add a real Docusaurus build as the ground-truth check: - The "CLI Docs Update" workflow now builds the site after regenerating the command reference and before opening its PR, so broken generated docs never become a PR. Because the site sets onBrokenLinks and onBrokenAnchors to 'throw', this also catches broken anchors and links. - A new "Validate CLI Docs Build" workflow runs the same build on any PR that touches docs/cli/**, gating hand edits and the auto-generated PR. Also preserve the hand-maintained command-reference index.mdx landing pages (custom ordering, ReleaseNoteHeader component) across regeneration: gen-docs no longer emits them, so restore them after the rm -rf that refreshes the generated command pages.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview linksThis PR does not change any pages in /docs. If you make updates, links to the modified pages will appear here. |
chaptersix
commented
Jul 7, 2026
The Vercel preview build is the required check on every PR, so it already compiles the generated CLI MDX (and fails on broken links/anchors) once a PR is opened. The extra `yarn build` step in this workflow was therefore redundant, and worse, it ran before the PR was created: if it failed, no PR would open and the failure would only surface in Actions run history that nobody watches. Remove that pre-PR build (and its Node setup / install steps) and the standalone validate-cli-docs-build.yml workflow. Keep the copy + index restore, which is the part that's actually needed alongside the gen-docs change that stops emitting the hand-maintained index pages.
chaptersix
changed the title
ks-temporal
approved these changes
Jul 7, 2026
| # subdirectory produced by -subdir. | ||
| rm -rf docs/cli/command-reference | ||
| mkdir -p docs/cli/command-reference | ||
| cp -r ../cli/dist/docs/* docs/cli/command-reference/ |
There was a problem hiding this comment.
Suggestion: consider using -R instead of -r
Contributor
Author
There was a problem hiding this comment.
Done — switched to cp -R. Identical on the GNU coreutils runner, but -R is the POSIX-standard flag (-r is deprecated on BSD/macOS), so it's the better convention.
lennessyy
approved these changes
Jul 7, 2026
chaptersix
added a commit
to temporalio/cli
that referenced
this pull request
Jul 8, 2026
…#1112) ## Summary This consolidates the excellent groundwork in #980, #1076, and #981 into a single change, and verifies the result against a real Docusaurus 3.10.1 build. Huge thanks to @lennessyy — the approach here is entirely built on those PRs; this just stitches them together and irons out a few interactions between them. gen-docs now escapes the patterns that break Docusaurus MDX (JSX) compilation, on **every** path that writes a command description (including the new split paths): - bare angle-bracket placeholders in prose (e.g. `<base64-encoded-cert>`, `<key>`) → `\<...\>` - single-quoted JSON examples (e.g. `'{"a":"b"}'`, `'Key={"a":"b"}'`) → braces escaped in body text, backticked in option tables - custom heading IDs (e.g. `## Heading {#id}`) → `{/* #id */}`, the form that compiles under Docusaurus 3.10 and still produces the custom anchor Fenced code blocks and inline code spans are left untouched. It also adds the `-subdir` flag (subcommands of the named command are written to a subdirectory, e.g. `-subdir cloud` → `cloud/*.mdx`, with deeper subcommands nested as headings), and a generic auto-generated notice. ## What changed relative to the existing PRs All three PRs were on the right track. The differences here are about how they interact: - **#1076 (MDX escaping):** kept as the core of this change, including the `{#id}` → `{/* #id */}` heading conversion — which I confirmed is exactly right for the 3.10 upgrade (see verification below). Escaping is now also applied to the `-subdir` split output, so cloud docs get the same treatment. Re-added unit tests for the escaping logic. - **#980 (`-subdir`):** kept the split mechanism. Unified the `encodeJSONExample` regex so it matches both `'{...}'` and `'Key={...}'` (the standalone-vs-key-value cases the two PRs handled separately). Intentionally did **not** carry over #980's index-page generation: `command-reference/index.mdx` and `cloud/index.mdx` are hand-maintained on the docs site (custom ordering, the `ReleaseNoteHeader` component), so gen-docs deliberately does not emit them — generating them would overwrite that curated content. The companion docs PR restores those files after each regeneration. - **#981 (generic notice):** folded in — the previous notice pointed at paths that no longer exist and don't hold for cloud-cli inputs. ## Companion PR temporalio/documentation#4836
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
3 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
The gen-docs change in temporalio/cli#1112 stops emitting the CLI command-reference index landing pages (
command-reference/index.mdxandcloud/index.mdx), because those are hand-maintained on the docs site (custom ordering, theReleaseNoteHeadercomponent). This workflow doesrm -rf docs/cli/command-referencebefore regenerating, so without a change here those curated pages would be deleted — breaking thesidebars.jsreferences (and the build).This restores those two files from
HEADafter regeneration. (Thecp -rthat preserves thecloud/subdirectory is already in place.)What changed since first review
This PR originally also added a
yarn buildvalidation step here plus a standalonevalidate-cli-docs-build.ymlworkflow. Per review (thanks @lennessyy) those were dropped:So the PR is now just the index-preservation fix.
Companion PR
temporalio/cli#1112 — the gen-docs change this pairs with. They should land together (this workflow relies on that PR's
-subdirflag, and the index restore pairs with it no longer emitting those pages).