ci/docs: escape MDX-incompatible patterns and add -subdir to gen-docs#1112
Open
chaptersix wants to merge 3 commits into
Open
ci/docs: escape MDX-incompatible patterns and add -subdir to gen-docs#1112chaptersix wants to merge 3 commits into
chaptersix wants to merge 3 commits into
Conversation
chaptersix
force-pushed
the
docs/gen-docs-mdx-fixes
branch
2 times, most recently
from
ee208c9 to
c76b195
Compare
Generated MDX docs contain patterns that are valid CommonMark but break
Docusaurus MDX (JSX) compilation under Docusaurus 3.10+:
- bare angle-bracket placeholders in prose (e.g. <base64-encoded-cert>,
<key>), which MDX parses as unclosed JSX/HTML tags;
- curly braces in single-quoted JSON examples (e.g. '{"a":"b"}'), which
MDX parses as JSX expressions; and
- custom heading IDs (e.g. "## Heading {#id}"), which MDX parses as a JSX
expression and rejects with "Could not parse expression with acorn".
Add escapeMDXDescription() and apply it to every path that writes a
command description (including the new split paths), leaving fenced code
blocks and inline code spans untouched. Custom heading IDs are converted
to Docusaurus's MDX comment form ({/* #id */}), which compiles and still
produces the custom anchor. Unify the JSON-escaping regex so
encodeJSONExample (option table cells) also matches both 'Key={...}' and
standalone '{...}' forms.
Add a -subdir flag so a command's subcommands can each be written to their
own file within a subdirectory (e.g. -subdir cloud produces cloud/*.mdx),
which the cloud CLI extension needs to avoid a single ~2800-line page.
Deeper subcommands nest as headings within their parent's file. Index and
landing pages are intentionally not generated, since the docs site
hand-maintains them (custom ordering, embedded components).
Replace the hardcoded (and incorrect) source path in the auto-generated
notice with a generic message, since inputs can come from multiple repos.
Add unit tests for the escaping functions and subdir generation. Verified
the generated output compiles with a real Docusaurus 3.10.1 build.
chaptersix
force-pushed
the
docs/gen-docs-mdx-fixes
branch
from
c76b195 to
75ae654
Compare
There was a problem hiding this comment.
Pull request overview
This PR updates the gen-docs generator to better support Docusaurus MDX output by escaping MDX-incompatible patterns in generated descriptions, and adds a -subdir flag to split large command trees into per-subcommand files under a directory.
Changes:
- Add
-subdirflag tocmd/gen-docsand route split command output intosubdir/*.mdx(creating directories as needed). - Apply MDX-escaping to command description prose (while preserving fenced/inline code) and unify JSON-in-single-quotes handling.
- Add unit tests covering MDX escaping, JSON example encoding, and
-subdirsplitting behavior.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| internal/commandsgen/docs.go | Implements -subdir splitting, generic auto-generated notice, and MDX escaping for descriptions. |
| internal/commandsgen/docs_test.go | Adds tests for MDX escaping, JSON example encoding, and split output generation. |
| cmd/gen-docs/main.go | Wires up -subdir flag and ensures split output directories exist before writing. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Addresses review feedback on the -subdir output: - Direct-child leaf pages (e.g. cloud login) now go through the same writeLeafOptions path as deeper leaves, so they render a Global Flags section instead of silently omitting it. writeLeafOptions now only emits the "#global-flags" link when inherited options actually exist, so a leaf with no inherited options can't link to an anchor that isn't generated. - Non-leaf split pages (e.g. cloud namespace) now include the command's own description before the boilerplate, matching how non-split subcommand pages render it. Split subcommand headings keep the path relative to the split root (e.g. "ha update", "cert-ca create") rather than only the final segment: within one aggregated file that keeps each heading's anchor unique and stable, which other docs link to (e.g. /cloud/high-availability/enable -> cloud/namespace#ha-update). Verified with a Docusaurus 3.10.1 build.
ks-temporal
approved these changes
Jul 7, 2026
ks-temporal
left a comment
ks-temporal
left a comment
There was a problem hiding this comment.
Looks good. I left some suggestions, mostly to update code comment.
…cal) - Note that FullName segments are single-space separated (ancestor routing). - Document that a multi-word split root is hyphenated into one directory. - Use c.FullName directly instead of re-joining the split parts. - Note that code-fence markers are assumed to start their own line. No change to generated output.
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.
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):
<base64-encoded-cert>,<key>) →\<...\>'{"a":"b"}','Key={"a":"b"}') → braces escaped in body text, backticked in option tables## Heading {#id}) →{/* #id */}, the form that compiles under Docusaurus 3.10 and still produces the custom anchorFenced code blocks and inline code spans are left untouched.
It also adds the
-subdirflag (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:
{#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-subdirsplit output, so cloud docs get the same treatment. Re-added unit tests for the escaping logic.-subdir): kept the split mechanism. Unified theencodeJSONExampleregex so it matches both'{...}'and'Key={...}'(the standalone-vs-key-value cases the two PRs handled separately). Intentionally did not carry over ci: add -subdir flag to gen-docs to support cloud CLI extension docs #980's index-page generation:command-reference/index.mdxandcloud/index.mdxare hand-maintained on the docs site (custom ordering, theReleaseNoteHeadercomponent), 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.Companion PR
temporalio/documentation#4836