refactor(repo): unify typedoc pipeline around parent H2 aggregator sections

[alexisintech]

Description

Unifies the .typedoc/ pipeline so every reference-object and backend-api parent page carries all the info its extracted sub-docs need in a canonical ## H2 shape, and extract-methods.mjs becomes a pure text-slicer over those H2s — no reflection access, no marker block. Same generated docs.

Before: extract-methods.mjs was a second reflection walker layered on top of the markdown theme. It re-imported TypeDoc AST types, re-derived method/property partitioning, and re-invoked MarkdownThemeContext partials to build each per-method MDX file. Two places in the codebase had to agree on how methods vs properties are partitioned, which acronyms slug how, and which comment tags trigger inline extraction.

After: all reflection work lives in custom-theme.mjs, which now synthesizes:

• ## name()H2 sections for every callable member that typedoc-plugin-markdown doesn't emit naturally (function-typed interface properties, `extraMethodInterfaces`, `@extractMethods` namespace callables like `emailCode.sendCode`). Backend-class methods get a ```typescript `` signature block injected after their natural description so all H2s share one shape.
• ## name`` H2 sections for @extractMethods namespaces with non-callable object-shape members (`emailLink` on `SignInFutureResource`) and each such non-callable member (`emailLink.verification`) — the same rows the marker-block builders used to write directly to sub-docs.
• Overloaded backend-class methods: strip typedoc's per-overload ### Call Signature sub-headings and re-emit a single section for the primary signature, so the parent's shape is uniform across single- and multi-overload methods.

extract-methods.mjs slices those H2s pre-prettier, reshapes each into methods/<slug>.mdx (H2 → H3, then straight verbatim), and defers Properties extraction to a preWriteAsyncJob that reads the (now prettier-aligned) <!-- clerk:properties-start/end --> markers and writes properties.mdx.

Commits

1. refactor(repo): move typedoc reflection work into custom-theme, reduce extract-methods to a marker slicer — the first move: reflection walks live in one place, extract-methods reads marker-wrapped output produced by the theme. Byte-identical to the pre-refactor docs.
2. refactor(repo): text-slice parent H2 aggregator sections into methods sub-docs — the follow-through: parent pages carry the info directly (methods + property tables), extract-methods becomes a pure text-slicer, and the marker-block emission is deleted entirely. Byte-identical for every sub-doc; the only expected output delta is the parent pages themselves, which now show their ## name() / `## `name H2 sections in full.

Refs

• DOCS-11892

Checklist

• pnpm test runs as expected. (.typedoc vitest: 16/16 pass)
• 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: 535edb6

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)
clerk-js-sandbox	Ready	Preview, Comment	Jul 2, 2026 11:24pm
swingset	Ready	Preview, Comment	Jul 2, 2026 11:24pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: dfe94614-0c6d-4408-bd4b-b56a31dcc3a5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 535edb6