@rspress/plugin-api-docgen 2.0.0-beta.2 → 2.0.0-beta.20

package/README.md

@@ -1,3 +1,3 @@
 # @rspress/plugin-api-docgen
 
-The auto api generate plugin for [Rspress](https://rspress.dev).
+The auto api generate plugin for [Rspress](https://rspress.rs).

package/dist/index.js

@@ -1,27 +1,27 @@
-import * as __WEBPACK_EXTERNAL_MODULE_node_fs_5ea92f0c__ from "node:fs";
-import * as __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__ from "node:path";
-import * as __WEBPACK_EXTERNAL_MODULE__rspress_shared_logger_4374e44a__ from "@rspress/shared/logger";
-import * as __WEBPACK_EXTERNAL_MODULE__rspress_shared_baa012d0__ from "@rspress/shared";
-import * as __WEBPACK_EXTERNAL_MODULE_chokidar__ from "chokidar";
-import * as __WEBPACK_EXTERNAL_MODULE_react_docgen_typescript_e816f54f__ from "react-docgen-typescript";
-__WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(__dirname, '..');
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { logger } from "@rspress/shared/logger";
+import { RSPRESS_TEMP_DIR } from "@rspress/shared";
+import chokidar from "chokidar";
+import { withCompilerOptions, withCustomConfig, withDefaultConfig } from "react-docgen-typescript";
+node_path.join(__dirname, '..');
 const apiDocMap = {};
 const locales = {
     zh: {
-        copy: '复制',
-        copied: '复制成功',
-        expand: '展开代码',
-        collapse: '收起代码',
-        className: '节点类名',
-        style: '节点样式',
-        children: '子节点',
-        disabled: '是否禁用',
-        required: '必填',
-        property: '属性',
-        description: '说明',
-        type: '类型',
-        defaultValue: '默认值',
-        overview: '概览'
+        copy: "\u590D\u5236",
+        copied: "\u590D\u5236\u6210\u529F",
+        expand: "\u5C55\u5F00\u4EE3\u7801",
+        collapse: "\u6536\u8D77\u4EE3\u7801",
+        className: "\u8282\u70B9\u7C7B\u540D",
+        style: "\u8282\u70B9\u6837\u5F0F",
+        children: "\u5B50\u8282\u70B9",
+        disabled: "\u662F\u5426\u7981\u7528",
+        required: "\u5FC5\u586B",
+        property: "\u5C5E\u6027",
+        description: "\u8BF4\u660E",
+        type: "\u7C7B\u578B",
+        defaultValue: "\u9ED8\u8BA4\u503C",
+        overview: "\u6982\u89C8"
     },
     en: {
         copy: 'Copy',
@@ -40,20 +40,20 @@ const locales = {
         overview: 'Overview'
     },
     ru: {
-        copy: 'Копировать',
-        copied: 'Скопировано успешно',
-        expand: 'Развернуть код',
-        collapse: 'Свернуть код',
-        className: 'Имя класса узла',
-        style: 'Стиль узла',
-        children: 'Дочерние элементы',
-        disabled: 'Отключено',
-        required: 'Обязательно',
-        property: 'Свойство',
-        description: 'Описание',
-        type: 'Тип',
-        defaultValue: 'Значение по умолчанию',
-        overview: 'Обзор'
+        copy: "\u041A\u043E\u043F\u0438\u0440\u043E\u0432\u0430\u0442\u044C",
+        copied: "\u0421\u043A\u043E\u043F\u0438\u0440\u043E\u0432\u0430\u043D\u043E \u0443\u0441\u043F\u0435\u0448\u043D\u043E",
+        expand: "\u0420\u0430\u0437\u0432\u0435\u0440\u043D\u0443\u0442\u044C \u043A\u043E\u0434",
+        collapse: "\u0421\u0432\u0435\u0440\u043D\u0443\u0442\u044C \u043A\u043E\u0434",
+        className: "\u0418\u043C\u044F \u043A\u043B\u0430\u0441\u0441\u0430 \u0443\u0437\u043B\u0430",
+        style: "\u0421\u0442\u0438\u043B\u044C \u0443\u0437\u043B\u0430",
+        children: "\u0414\u043E\u0447\u0435\u0440\u043D\u0438\u0435 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u044B",
+        disabled: "\u041E\u0442\u043A\u043B\u044E\u0447\u0435\u043D\u043E",
+        required: "\u041E\u0431\u044F\u0437\u0430\u0442\u0435\u043B\u044C\u043D\u043E",
+        property: "\u0421\u0432\u043E\u0439\u0441\u0442\u0432\u043E",
+        description: "\u041E\u043F\u0438\u0441\u0430\u043D\u0438\u0435",
+        type: "\u0422\u0438\u043F",
+        defaultValue: "\u0417\u043D\u0430\u0447\u0435\u043D\u0438\u0435 \u043F\u043E \u0443\u043C\u043E\u043B\u0447\u0430\u043D\u0438\u044E",
+        overview: "\u041E\u0431\u0437\u043E\u0440"
     }
 };
 const isToolEntries = (obj)=>!!obj.documentation || !!obj["react-docgen-typescript"];
@@ -62,7 +62,7 @@ const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptio
     const genApiDoc = async (entry, tool)=>{
         if (0 === Object.keys(entry).length) return;
         await Promise.all(Object.entries(entry).map(async ([key, value])=>{
-            const moduleSourceFilePath = __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].resolve(appDir, value);
+            const moduleSourceFilePath = node_path.resolve(appDir, value);
             watchFileMap[moduleSourceFilePath] = {
                 apiParseTool,
                 moduleName: key
@@ -91,22 +91,22 @@ const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptio
                         },
                         ...restOptions
                     };
-                    let fileParser = (0, __WEBPACK_EXTERNAL_MODULE_react_docgen_typescript_e816f54f__.withDefaultConfig)(parserOpts);
-                    if (tsconfigPath?.[key]) fileParser = (0, __WEBPACK_EXTERNAL_MODULE_react_docgen_typescript_e816f54f__.withCustomConfig)(tsconfigPath[key], parserOpts);
-                    else if (compilerOptions?.[key]) fileParser = (0, __WEBPACK_EXTERNAL_MODULE_react_docgen_typescript_e816f54f__.withCompilerOptions)(compilerOptions[key], parserOpts);
+                    let fileParser = withDefaultConfig(parserOpts);
+                    if (tsconfigPath?.[key]) fileParser = withCustomConfig(tsconfigPath[key], parserOpts);
+                    else if (compilerOptions?.[key]) fileParser = withCompilerOptions(compilerOptions[key], parserOpts);
                     const componentDoc = fileParser.parse(moduleSourceFilePath);
-                    if (0 === componentDoc.length) __WEBPACK_EXTERNAL_MODULE__rspress_shared_logger_4374e44a__.logger.warn('[module-doc-plugin]', `Unable to parse API document in ${moduleSourceFilePath}`);
+                    if (0 === componentDoc.length) logger.warn('[module-doc-plugin]', `Unable to parse API document in ${moduleSourceFilePath}`);
                     if (languages.length > 0) languages.forEach((language)=>{
                         apiDocMap[`${key}-${language}`] = generateTable(componentDoc, language);
                     });
                     else apiDocMap[key] = generateTable(componentDoc, 'en');
                 }
             } catch (e) {
-                if (e instanceof Error) __WEBPACK_EXTERNAL_MODULE__rspress_shared_logger_4374e44a__.logger.error('[module-doc-plugin]', 'Generate API table error:\n', e);
+                if (e instanceof Error) logger.error('[module-doc-plugin]', 'Generate API table error:\n', e);
             }
         }));
     };
-    __WEBPACK_EXTERNAL_MODULE__rspress_shared_logger_4374e44a__.logger.info('[module-doc-plugin]', 'Start to generate API table...');
+    logger.info('[module-doc-plugin]', 'Start to generate API table...');
     if (isToolEntries(entries)) {
         const reactEntries = entries["react-docgen-typescript"];
         const documentationEntries = entries.documentation;
@@ -116,7 +116,7 @@ const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptio
         ]);
     } else await genApiDoc(entries, apiParseTool);
     if (!isProd) {
-        const watcher = __WEBPACK_EXTERNAL_MODULE_chokidar__["default"].watch(Object.keys(watchFileMap), {
+        const watcher = chokidar.watch(Object.keys(watchFileMap), {
             ignoreInitial: true,
             ignorePermissionErrors: true,
             ignored: [
@@ -127,12 +127,12 @@ const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptio
         watcher.on('change', (changed)=>{
             if (isUpdate) return;
             isUpdate = true;
-            __WEBPACK_EXTERNAL_MODULE__rspress_shared_logger_4374e44a__.logger.info('[module-doc-plugin]', 'updating API');
+            logger.info('[module-doc-plugin]', 'updating API');
             const watchFileInfo = watchFileMap[changed];
             if (watchFileInfo) {
                 const { apiParseTool, moduleName } = watchFileInfo;
                 const updateSiteData = ()=>{
-                    const siteDataPath = __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(process.cwd(), 'node_modules', __WEBPACK_EXTERNAL_MODULE__rspress_shared_baa012d0__.RSPRESS_TEMP_DIR, 'runtime', 'virtual-site-data.mjs');
+                    const siteDataPath = node_path.join(process.cwd(), 'node_modules', RSPRESS_TEMP_DIR, 'runtime', 'virtual-site-data.mjs');
                     import(siteDataPath).then((siteData)=>{
                         const data = {
                             ...siteData.default
@@ -140,7 +140,7 @@ const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptio
                         data.pages.forEach((page)=>{
                             page.apiDocMap = apiDocMap;
                         });
-                        __WEBPACK_EXTERNAL_MODULE_node_fs_5ea92f0c__["default"].writeFileSync(siteDataPath, `export default ${JSON.stringify(data)}`);
+                        node_fs.writeFileSync(siteDataPath, `export default ${JSON.stringify(data)}`);
                         isUpdate = false;
                     });
                 };
@@ -150,7 +150,7 @@ const docgen = async ({ entries, languages, apiParseTool, appDir, parseToolOptio
             }
         });
     }
-    __WEBPACK_EXTERNAL_MODULE__rspress_shared_logger_4374e44a__.logger.success('[module-doc-plugin]', 'Generate API table successfully!');
+    logger.success('[module-doc-plugin]', 'Generate API table successfully!');
 };
 function generateTable(componentDoc, language) {
     return componentDoc.map((param)=>{
@@ -226,14 +226,14 @@ function pluginApiDocgen(options) {
             const apiCompRegExp = /(<API\s+moduleName=['"](\S+)['"]\s*(.*)?\/>)|(<API\s+moduleName=['"](\S+)['"]\s*(.*)?>(.*)?<\/API>)/;
             await Promise.all(pages.map(async (page)=>{
                 const { _filepath, lang } = page;
-                let content = await __WEBPACK_EXTERNAL_MODULE_node_fs_5ea92f0c__["default"].promises.readFile(_filepath, 'utf-8');
+                let content = await node_fs.promises.readFile(_filepath, 'utf-8');
                 let matchResult = apiCompRegExp.exec(content);
                 if (!matchResult) return;
                 while(null !== matchResult){
                     const matchContent = matchResult[0];
                     const moduleName = matchResult[2] ?? matchResult[5] ?? '';
                     const apiDoc = apiDocMap[moduleName] ?? apiDocMap[`${moduleName}-${lang ? lang : 'en'}`] ?? '';
-                    if (matchContent && !apiDoc) __WEBPACK_EXTERNAL_MODULE__rspress_shared_logger_4374e44a__.logger.warn(`No api doc found for module: ${moduleName} in lang: ${lang ?? 'en'}`);
+                    if (matchContent && !apiDoc) logger.warn(`No api doc found for module: ${moduleName} in lang: ${lang ?? 'en'}`);
                     content = content.replace(matchContent, apiDoc);
                     matchResult = apiCompRegExp.exec(content);
                 }
@@ -247,7 +247,7 @@ function pluginApiDocgen(options) {
         },
         markdown: {
             globalComponents: [
-                __WEBPACK_EXTERNAL_MODULE_node_path_c5b9b54f__["default"].join(__dirname, '..', 'static', 'global-components', 'API.tsx')
+                node_path.join(__dirname, '..', 'static', 'global-components', 'API.tsx')
             ]
         }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rspress/plugin-api-docgen",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.20",
   "description": "A plugin for rspress to generate api doc.",
   "bugs": "https://github.com/web-infra-dev/rspress/issues",
   "repository": {
@@ -25,27 +25,30 @@
   "dependencies": {
     "chokidar": "^3.6.0",
     "documentation": "14.0.3",
-    "react-docgen-typescript": "2.2.2",
+    "github-slugger": "^2.0.0",
+    "react-docgen-typescript": "2.4.0",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
     "unified": "^11.0.5",
-    "@rspress/shared": "2.0.0-beta.2"
+    "unist-util-visit": "^5.0.0",
+    "@rspress/shared": "2.0.0-beta.20"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.52.4",
-    "@rslib/core": "0.6.5",
+    "@microsoft/api-extractor": "^7.52.8",
+    "@rslib/core": "0.10.4",
+    "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^18.11.17",
-    "@types/react": "^18.3.20",
-    "@types/react-dom": "^18.3.6",
+    "@types/node": "^22.8.1",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router-dom": "^6.29.0",
-    "rsbuild-plugin-publint": "^0.3.0",
+    "rsbuild-plugin-publint": "^0.3.2",
     "typescript": "^5.8.2"
   },
   "peerDependencies": {
-    "@rspress/core": "^2.0.0-beta.2",
+    "@rspress/core": "^2.0.0-beta.20",
     "typescript": "^5.8.2"
   },
   "peerDependenciesMeta": {

package/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.css';
+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.trim());
+      }
+      // 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();
@@ -19,6 +110,7 @@ export default (props: { moduleName: string }) => {
     <div className="rspress-plugin-api-docgen">
       <ReactMarkdown
         remarkPlugins={[[remarkGfm]]}
+        rehypePlugins={[[rehypeHeaderAnchor]]}
         components={
           getCustomMDXComponent() as Record<string, React.ElementType>
         }