docs(repo): stop multi-@example rendering from inserting duplicate commas

[SarahSoutoul]

Description

Discovered when reviewing the latest Typedoc generated PR

Problem

The Typedoc custom plugin's "Examples" replacement rule joined multiple @example values by splitting the captured text on every space and rejoining with , . When an example value contained internal spaces — e.g. an array literal like ["/orgs/:slug", "/orgs/:slug/(.*)"] — it got broken apart and stitched back together with extra commas, producing a duplicate ,, in the generated docs.

Where: .typedoc/custom-plugin.mjs → getCatchAllReplacements(), the **Examples** rule (~line 395).

Fix

Instead of splitting on spaces, it now matches each backtick-delimited example (/`[^`]+`/g) and joins those directly with , , preserving internal spaces.

- return `Examples: ${capturedGroup.split(' ').join(', ')}.`;
+ const examples = capturedGroup.match(/`[^`]+`/g) ?? [];
+ return `Examples: ${examples.join(', ')}.`;

Generated-output-only change; no runtime behavior is affected. The two implementations are identical for every space-free example value — the only outputs that change are the ones that were already broken.

How to test

Unit (fast):

pnpm exec vitest run .typedoc/__tests__/catch-all-replacements.test.ts

The regression case asserts an array-literal example round-trips without a spurious comma.

End-to-end (regenerates docs):

pnpm typedoc:generate

Then check the two affected output files — search for the Examples: line on the organizationPatterns / personalAccountPatterns options:

• .typedoc/docs/backend/authenticate-request-options.mdx
• .typedoc/docs/nextjs/clerk-middleware-options.mdx

Before: Examples: `["/orgs/:slug",, "/orgs/:slug/(.*)"]`, …
After: Examples: `["/orgs/:slug", "/orgs/:slug/(.*)"]`, …

Note: pnpm typedoc:generate runs a full pnpm build first, so it's slow. For the quick path, pnpm test:typedoc generates the docs then runs the .typedoc vitest suite.

Changes

• .typedoc/custom-plugin.mjs — the one-line logic fix (plus an explanatory comment)
• .typedoc/__tests__/catch-all-replacements.test.ts — new test file with 3 cases: single example, multiple examples, and a regression test for examples with internal spaces
• .changeset/typedoc-multi-example-double-comma.md — empty changeset (tooling-only change; no published package is affected)

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: d4576d1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
swingset	Ready	Preview, Comment	Jul 21, 2026 3:40pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		Jul 21, 2026 3:40pm

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9204

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9204

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9204

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9204

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9204

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9204

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9204

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9204

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9204

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9204

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9204

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9204

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9204

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9204

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9204

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9204

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9204

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9204

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9204

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9204

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9204

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9204

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9204

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9204

commit: d4576d1

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f47509c5-a5ce-47f6-960d-1bf7972bfc35

📥 Commits

Reviewing files that changed from the base of the PR and between 180647d and cde9a65.

📒 Files selected for processing (1)

• .typedoc/custom-plugin.mjs

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)

🚧 Files skipped from review as they are similar to previous changes (1)

• .typedoc/custom-plugin.mjs

---

📝 Walkthrough

Walkthrough

The Typedoc catch-all replacement now extracts complete backtick-delimited @example values and joins multiple examples with , instead of splitting on spaces. New tests cover single examples, multiple examples, and values containing internal spaces. A changeset documents the correction.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main fix: preventing duplicate commas in multi-@example Typedoc rendering.
Description check	✅ Passed	The description is directly related and accurately explains the Typedoc bug fix, tests, and generated-docs-only impact.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[wobsoriano]

I think we can do an empty changeset? Since this does not change the backend at all 👍🏼

[SarahSoutoul]

Good pt! All done @wobsoriano

[manovotny]

Pushed a small change directly in f323fc9.

• Condensed the four-line comment on the **Examples** replacement to a single line, per the repo's terse-comment rule in AGENTS.md
• Updated the PR description's "Changes" section — the changeset is empty (tooling-only change), not a @clerk/backend patch