fix(plugin-api-doc-gen): plugin-api-doc-gen should have anchor

e2e/tests/api-docgen.test.ts → e2e/tests/plugin-api-docgen.test.ts

@@ -23,6 +23,9 @@ test.describe('api-docgen test', async () => {
 
   test('Index page', async ({ page }) => {
     await page.goto(`http://localhost:${appPort}`);
+    const tableH3 = await page.$('#button');
+    expect(tableH3).toBeTruthy();
+
     const table = await page.$('table');
     const tableContent = await page.evaluate(table => table?.innerHTML, table);
 

packages/plugin-api-docgen/package.json

@@ -26,13 +26,16 @@
     "@rspress/shared": "workspace:*",
     "chokidar": "^3.6.0",
     "documentation": "14.0.3",
+    "github-slugger": "^2.0.0",
     "react-docgen-typescript": "2.2.2",
     "react-markdown": "8.0.7",
-    "remark-gfm": "3.0.1"
+    "remark-gfm": "3.0.1",
+    "unist-util-visit": "^4.1.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.49.2",
     "@rslib/core": "0.5.2",
+    "@types/hast": "^2.3.10",
     "@types/mdast": "^3.0.15",
     "@types/node": "^18.11.17",
     "@types/react": "^18.3.18",
@@ -41,8 +44,7 @@
     "react-dom": "^18.3.1",
     "react-router-dom": "^6.29.0",
     "typescript": "^5.5.3",
-    "unified": "^10.1.2",
-    "unist-util-visit": "^4.1.2"
+    "unified": "^10.1.2"
   },
   "peerDependencies": {
     "@rspress/core": "workspace:^1.43.13",

packages/plugin-api-docgen/static/global-components/API.tsx

@@ -5,6 +5,97 @@ import { getCustomMDXComponent } from '@rspress/core/theme';
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import './API.scss';
+import GithubSlugger from 'github-slugger';
+import type { Content, Element, Root } from 'hast';
+// biome-ignore lint/style/useImportType: <exact>
+import React from 'react';
+import type { Plugin } from 'unified';
+import { visit } from 'unist-util-visit';
+
+function headingRank(node: Root | Content): number | null {
+  const name =
+    (node && node.type === 'element' && node.tagName.toLowerCase()) || '';
+  const code =
+    name.length === 2 && name.charCodeAt(0) === 104 /* `h` */
+      ? name.charCodeAt(1)
+      : 0;
+  return code > 48 /* `0` */ && code < 55 /* `7` */
+    ? code - 48 /* `0` */
+    : null;
+}
+
+const rehypeHeaderAnchor: Plugin<[], Root> = () => {
+  const slugger = new GithubSlugger();
+  return tree => {
+    visit(tree, 'element', node => {
+      if (!headingRank(node)) {
+        return;
+      }
+      // generate id
+
+      if (!node.properties?.id) {
+        const text = collectHeaderText(node);
+        node.properties ??= {};
+        node.properties.id = slugger.slug(text);
+      }
+      // apply to headings
+      node.children.unshift(create(node));
+    });
+  };
+};
+
+/**
+ * Create an `a`.
+ *
+ * @param {Readonly<Element>} node
+ *   Related heading.
+ * @returns {Element}
+ *   Link.
+ */
+function create(node: Element): Element {
+  return {
+    type: 'element',
+    tagName: 'a',
+    properties: {
+      class: 'header-anchor',
+      ariaHidden: 'true',
+      href: `#${node.properties!.id}`,
+    },
+    children: [
+      {
+        type: 'text',
+        value: '#',
+      },
+    ],
+  };
+}
+
+const extractTextAndId = (title?: string): string => {
+  if (!title) {
+    return '';
+  }
+  const text = title.trimEnd();
+  return text;
+};
+
+const collectHeaderText = (node: Element): string => {
+  let text = '';
+  node.children.forEach(child => {
+    if (child.type === 'text') {
+      const textPart = extractTextAndId(child.value);
+      child.value = textPart;
+      text += textPart;
+    }
+    if (child.type === 'element') {
+      child.children.forEach(c => {
+        if (c.type === 'text') {
+          text += c.value;
+        }
+      });
+    }
+  });
+  return text;
+};
 
 export default (props: { moduleName: string }) => {
   const lang = useLang();
@@ -18,6 +109,7 @@ export default (props: { moduleName: string }) => {
   return (
     <ReactMarkdown
       remarkPlugins={[[remarkGfm]]}
+      rehypePlugins={[[rehypeHeaderAnchor]]}
       components={getCustomMDXComponent() as Record<string, React.ElementType>}
       skipHtml={true}
       className="rspress-plugin-api-docgen"