handle top sections

Author: panteliselef

.typedoc/custom-plugin.mjs

@@ -1,4 +1,4 @@
-// @ts-check
+// @ts-check - Enable TypeScript checks for safer MDX post-processing and link rewriting
 import { MarkdownPageEvent } from 'typedoc-plugin-markdown';
 
 /**
@@ -83,6 +83,19 @@ function getRelativeLinkReplacements() {
 
 function getCatchAllReplacements() {
   return [
+    // Robustly remove the full Experimental section (including optional Example/code block)
+    // from the first "**`Experimental`**" until the next heading (## ...) or end of file.
+    // This covers variations in wording/whitespace and ensures the block is stripped.
+    {
+      pattern: /(?:^|\r?\n)\*\*`Experimental`\*\*[\s\S]*?(?=(?:\r?\n##\s)|$)/g,
+      replace: '',
+    },
+    // As a safeguard, remove any leftover Example section that specifically shows ClerkProvider clerkJsVersion snippet
+    {
+      pattern:
+        /(?:^|\r?\n)## Example\r?\n(?:\r?\n)?```tsx[\s\S]*?ClerkProvider\s+clerkJsVersion="[^"]*"[\s\S]*?```(?:\r?\n)?/g,
+      replace: '',
+    },
     {
       pattern: /\(setActiveParams\)/g,
       replace: '([setActiveParams](/docs/references/javascript/types/set-active-params))',
@@ -135,12 +148,6 @@ function getCatchAllReplacements() {
       pattern: /\*\*Deprecated\*\*/g,
       replace: '**Deprecated.**',
     },
-    // Remove the standard experimental API notice block (with or without leading/trailing whitespace or newlines)
-    {
-      pattern:
-        /(?:\r?\n)?\*\*`Experimental`\*\*\r?\n\r?\nThis is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change\.\r?\nIt is advised to pin the SDK version to avoid breaking changes\.\r?\n?/g,
-      replace: '',
-    },
     {
       /**
        * By default, `@default` is output with "**Default** `value`". We want to capture the value and place it inside "Defaults to `value`."

.typedoc/custom-theme.mjs

@@ -46,6 +46,21 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
     this.partials = {
       ...superPartials,
+      /**
+       * This hides the "Experimental" section from the output (by default).
+       * @param {import('typedoc').Comment} model
+       * @param {{ headingLevel?: number; showSummary?: boolean; showTags?: boolean; showReturns?: boolean; isTableColumn?: boolean }} [options]
+       */
+      comment: (model, options) => {
+        if (model?.modifierTags.has('@experimental')) {
+          const originalBlockTags = model.blockTags;
+          model.blockTags = model.blockTags.filter(tag => tag.name !== '@example');
+          const res = superPartials.comment(model, options);
+          model.blockTags = originalBlockTags;
+          return res;
+        }
+        return superPartials.comment(model, options);
+      },
       /**
        * This hides the "Type parameters" section and the signature title from the output (by default). Shows the signature title if the `@displayFunctionSignature` tag is present.
        * @param {import('typedoc').SignatureReflection} model