heliannuuthus · heliannuuthus · Jan 20, 2026
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -0,0 +1,43 @@
+module.exports = {
+  root: true,
+  extends: [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended",
+    "plugin:react/jsx-runtime"
+  ],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: "module",
+    ecmaFeatures: {
+      jsx: true
+    }
+  },
+  plugins: ["@typescript-eslint", "react", "react-hooks"],
+  settings: {
+    react: {
+      version: "detect"
+    }
+  },
+  env: {
+    browser: true,
+    node: true,
+    es2022: true
+  },
+  rules: {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "react/prop-types": "off",
+    "react/react-in-jsx-scope": "off"
+  },
+  ignorePatterns: [
+    "build/",
+    "dist/",
+    "node_modules/",
+    "*.config.js",
+    "*.config.ts",
+    ".docusaurus/"
+  ]
+};
diff --git a/README.md b/README.md
@@ -15,3 +15,104 @@
 - [开发效率工具](https://site.heliannuuthus.com/blog/development-tools): 一些工具，来自我对编程的习惯和偏好
 - [SPIFFE](https://site.heliannuuthus.com/blog/spiffe): 一套开源标准，解决由于现代网络环境中资源动态变化（如弹性扩缩容、多运行时等）与环境复杂异构（如多云混合架构、跨平台支持等）所带来安全问题。
 - [MCP 身份认证协议](https://site.heliannuuthus.com/blog/OAuth2.1-MCP): 解释 OAuth2.1 如何解决 Agent 通过 MCP 协议调用外部工具的身份和权限问题。
+
+## 项目结构
+
+本项目采用 **Monorepo** 架构，使用 [pnpm workspace](https://pnpm.io/workspaces) 进行依赖管理。
+
+```
+heliannuuthus.github.io/
+├── packages/              # Remark/Rehype 插件包
+│   ├── remark-admomition/      # 自定义 Admonition 插件
+│   ├── remark-breaks/          # 换行处理插件
+│   ├── remark-collapse/        # 折叠内容插件
+│   ├── remark-collapse-heading/# 标题折叠插件
+│   ├── remark-comment-tooltip/ # 注释提示插件
+│   ├── remark-external-link/   # 外部链接处理插件
+│   ├── remark-markmap/         # Markmap 思维导图插件
+│   ├── remark-mermaid/         # Mermaid 图表插件
+│   ├── remark-tables/          # 表格增强插件
+│   ├── remark-tabs/            # 标签页插件
+│   └── remark-terminology/     # 术语表插件
+├── plugins/               # Docusaurus 插件
+│   ├── docusaurus-alias/      # 路径别名插件
+│   ├── docusaurus-authors/    # 作者管理插件
+│   ├── docusaurus-terminology/# 术语表插件
+│   ├── parse-md/              # Markdown 解析工具
+│   └── terminology-store/     # 术语存储工具
+├── blog/                  # 博客文章
+│   └── YYYY-MM/               # 按年月组织
+│       ├── _codes/            # 代码示例
+│       ├── _contents/         # 内容片段
+│       └── _partials/         # 可复用部分
+├── essay/                 # 随笔文章
+├── terminologies/         # 术语表定义
+├── src/                   # 源代码
+│   ├── components/        # React 组件
+│   ├── pages/             # 页面组件
+│   ├── theme/             # 主题定制
+│   └── utils/             # 工具函数
+└── static/                # 静态资源
+
+```
+
+### 内容组织说明
+
+- `_codes/`: 存放代码示例文件，可通过 `remark-code-import` 插件在文章中引用
+- `_contents/`: 存放内容片段，用于模块化组织长文章
+- `_partials/`: 存放可复用的 Markdown 片段
+
+## 开发指南
+
+### 环境要求
+
+- Node.js >= 22.0
+- pnpm >= 10.0
+
+### 安装依赖
+
+```bash
+pnpm install
+```
+
+### 开发命令
+
+```bash
+# 启动开发服务器
+pnpm start
+
+# 构建项目
+pnpm build
+
+# 类型检查
+pnpm typecheck
+
+# 代码检查
+pnpm lint
+
+# 代码格式化（自动修复）
+pnpm lint:fix
+
+# 构建所有 packages 和 plugins
+pnpm rebuild:all
+```
+
+### 构建流程
+
+1. **构建 packages**: 先运行测试，然后构建所有 remark/rehype 插件
+2. **构建 plugins**: 先构建依赖项（parse-md, terminology-store），再构建其他插件
+3. **构建网站**: 使用 Docusaurus 构建最终网站
+
+### 添加新的插件
+
+1. 在 `packages/` 或 `plugins/` 目录下创建新包
+2. 确保包名以 `heliannuuthus-` 开头
+3. 在根目录 `package.json` 中添加依赖引用（使用 `file:` 协议）
+4. 运行 `pnpm install` 安装依赖
+
+### 代码规范
+
+- 使用 TypeScript 编写代码
+- 遵循 Prettier 代码格式化规则
+- 使用 ESLint 进行代码检查
+- 避免使用 `any` 类型，优先使用具体类型定义
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -11,6 +11,7 @@ import remarkMarkmap from "heliannuuthus-remark-markmap";
 import remarkTables from "heliannuuthus-remark-tables";
 import remarkTabs from "heliannuuthus-remark-tabs";
 import remarkTerminology from "heliannuuthus-remark-terminology";
+import { Link } from "mdast";
 import path from "path";
 import { themes as prismThemes } from "prism-react-renderer";
 import rehypeKatex from "rehype-katex";
@@ -34,7 +35,7 @@ const remarkPlugins = [
       href: "/external-link",
       target: "_blank",
       rel: ["noopener", "noreferrer"],
-      test: (node: any) => node.url.startsWith("http")
+      test: (node: Link) => node.url.startsWith("http")
     }
   ],
   remarkCommentTooltip,

diff --git a/package.json b/package.json
@@ -13,28 +13,30 @@
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
-    "rebuild:all": "pnpm rebuild:plugins && pnpm rebuild:packages",
-    "install:plugins": "cd plugins && pnpm build && cd ..",
-    "clean:plugins": "cd plugins && pnpm clean && cd ..",
-    "rebuild:plugins": "cd plugins && pnpm build && cd .. && pnpm i",
-    "install:packages": "cd packages && pnpm build && cd ..",
-    "clean:packages": "cd packages && pnpm clean && cd ..",
-    "rebuild:packages": "cd packages && pnpm build && cd .. && pnpm i"
+    "lint": "eslint . --ext .ts,.tsx,.js,.jsx",
+    "lint:fix": "eslint . --ext .ts,.tsx,.js,.jsx --fix",
+    "rebuild:all": "pnpm rebuild:packages && pnpm rebuild:plugins",
+    "install:plugins": "pnpm --filter './plugins/*' build",
+    "clean:plugins": "pnpm --filter './plugins/*' clean",
+    "rebuild:plugins": "pnpm --filter './plugins/*' build && pnpm install",
+    "install:packages": "pnpm --filter './packages/*' build",
+    "clean:packages": "pnpm --filter './packages/*' clean",
+    "rebuild:packages": "pnpm --filter './packages/*' build && pnpm install"
   },
   "dependencies": {
     "@ant-design/icons": "^5.6.1",
     "@ant-design/v5-patch-for-react-19": "^1.0.3",
-    "@docusaurus/core": "3.8.1",
-    "@docusaurus/faster": "^3.8.1",
-    "@docusaurus/plugin-content-blog": "^3.8.1",
-    "@docusaurus/plugin-content-docs": "^3.8.1",
-    "@docusaurus/plugin-content-pages": "^3.8.1",
-    "@docusaurus/plugin-sitemap": "^3.8.1",
-    "@docusaurus/plugin-svgr": "^3.8.1",
-    "@docusaurus/theme-classic": "^3.8.1",
-    "@docusaurus/theme-common": "^3.8.1",
-    "@docusaurus/theme-mermaid": "^3.8.1",
-    "@docusaurus/theme-search-algolia": "^3.8.1",
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/faster": "^3.9.2",
+    "@docusaurus/plugin-content-blog": "^3.9.2",
+    "@docusaurus/plugin-content-docs": "^3.9.2",
+    "@docusaurus/plugin-content-pages": "^3.9.2",
+    "@docusaurus/plugin-sitemap": "^3.9.2",
+    "@docusaurus/plugin-svgr": "^3.9.2",
+    "@docusaurus/theme-classic": "^3.9.2",
+    "@docusaurus/theme-common": "^3.9.2",
+    "@docusaurus/theme-mermaid": "^3.9.2",
+    "@docusaurus/theme-search-algolia": "^3.9.2",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
     "animate.css": "^4.1.1",
@@ -91,15 +93,20 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.8.1",
-    "@docusaurus/tsconfig": "3.8.1",
-    "@docusaurus/types": "3.8.1",
+    "@docusaurus/module-type-aliases": "3.9.2",
+    "@docusaurus/tsconfig": "3.9.2",
+    "@docusaurus/types": "3.9.2",
     "@trivago/prettier-plugin-sort-imports": "^5.2.2",
     "@types/d3": "^7.4.3",
     "@types/file-saver": "^2.0.7",
     "@types/react": "^19.1.12",
     "@types/react-dom": "^19.1.9",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
     "acorn": "^8.15.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-react": "^7.37.0",
+    "eslint-plugin-react-hooks": "^5.1.0",
     "prettier": "^3.6.2",
     "prettier-plugin-organize-imports": "^4.2.0",
     "remark-code-import": "^1.2.0",

diff --git a/packages/package.json b/packages/package.json
@@ -2,7 +2,7 @@
   "name": "heliannuuthus-docusaurus-packages",
   "private": true,
   "scripts": {
-    "build": "pnpm install && pnpm vitest --run && pnpm -r build",
+    "build": "pnpm vitest --run && pnpm --filter './packages/*' build",
     "clean": "pnpm -r clean",
     "typecheck": "tsc --noEmit",
     "test": "vitest",

diff --git a/packages/remark-admomition/package.json b/packages/remark-admomition/package.json
@@ -10,7 +10,14 @@
     "build": "tsup",
     "clean": "rm -rf dist"
   },
+  "dependencies": {
+    "mdast-util-directive": "^3.1.0",
+    "mdast-util-mdx-jsx": "^3.2.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0"
+  },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.0",
     "@types/unist": "^3.0.3",
     "tsup": "^8.0.0",

diff --git a/packages/remark-admomition/tsup.config.ts b/packages/remark-admomition/tsup.config.ts
@@ -5,5 +5,9 @@ export default defineConfig({
   format: ["esm"],
   dts: true,
   clean: true,
-  sourcemap: true
+  sourcemap: true,
+  external: [
+    // Mark all dependencies as external
+    /^[^./]|^\.[^./]|^\.\.[^/]/
+  ]
 });
diff --git a/packages/remark-breaks/package.json b/packages/remark-breaks/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "heliannuuthus-remark-external-link",
+  "name": "heliannuuthus-remark-breaks",
   "version": "1.0.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,13 @@
     "build": "tsup",
     "clean": "rm -rf dist"
   },
+  "dependencies": {
+    "mdast-util-find-and-replace": "^3.0.2",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0"
+  },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.0",
     "@types/unist": "^3.0.3",
     "tsup": "^8.0.0",

diff --git a/packages/remark-breaks/tsup.config.ts b/packages/remark-breaks/tsup.config.ts
@@ -5,5 +5,9 @@ export default defineConfig({
   format: ["esm"],
   dts: true,
   clean: true,
-  sourcemap: true
+  sourcemap: true,
+  external: [
+    // Mark all dependencies as external
+    /^[^./]|^\.[^./]|^\.\.[^/]/
+  ]
 });
diff --git a/packages/remark-collapse-heading/package.json b/packages/remark-collapse-heading/package.json
@@ -10,7 +10,12 @@
     "build": "tsup",
     "clean": "rm -rf dist"
   },
+  "dependencies": {
+    "mdast-util-to-string": "^4.0.0",
+    "unified": "^11.0.5"
+  },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.0",
     "@types/unist": "^3.0.3",
     "tsup": "^8.0.0",

diff --git a/packages/remark-collapse-heading/tsup.config.ts b/packages/remark-collapse-heading/tsup.config.ts
@@ -5,5 +5,9 @@ export default defineConfig({
   format: ["esm"],
   dts: true,
   clean: true,
-  sourcemap: true
+  sourcemap: true,
+  external: [
+    // Mark all dependencies as external
+    /^[^./]|^\.[^./]|^\.\.[^/]/
+  ]
 });
diff --git a/packages/remark-collapse/package.json b/packages/remark-collapse/package.json
@@ -10,7 +10,14 @@
     "build": "tsup",
     "clean": "rm -rf dist"
   },
+  "dependencies": {
+    "mdast-util-directive": "^3.1.0",
+    "mdast-util-mdx-jsx": "^3.2.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0"
+  },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.0",
     "@types/unist": "^3.0.3",
     "tsup": "^8.0.0",

diff --git a/packages/remark-collapse/tsup.config.ts b/packages/remark-collapse/tsup.config.ts
@@ -5,5 +5,9 @@ export default defineConfig({
   format: ["esm"],
   dts: true,
   clean: true,
-  sourcemap: true
+  sourcemap: true,
+  external: [
+    // Mark all dependencies as external
+    /^[^./]|^\.[^./]|^\.\.[^/]/
+  ]
 });
diff --git a/packages/remark-comment-tooltip/package.json b/packages/remark-comment-tooltip/package.json
@@ -10,7 +10,14 @@
     "build": "tsup",
     "clean": "rm -rf dist"
   },
+  "dependencies": {
+    "mdast-util-directive": "^3.1.0",
+    "mdast-util-mdx-jsx": "^3.2.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0"
+  },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.0",
     "@types/unist": "^3.0.3",
     "tsup": "^8.0.0",

diff --git a/packages/remark-comment-tooltip/tsup.config.ts b/packages/remark-comment-tooltip/tsup.config.ts
@@ -5,5 +5,9 @@ export default defineConfig({
   format: ["esm"],
   dts: true,
   clean: true,
-  sourcemap: true
+  sourcemap: true,
+  external: [
+    // Mark all dependencies as external
+    /^[^./]|^\.[^./]|^\.\.[^/]/
+  ]
 });
diff --git a/packages/remark-external-link/package.json b/packages/remark-external-link/package.json
@@ -10,7 +10,12 @@
     "build": "tsup",
     "clean": "rm -rf dist"
   },
+  "dependencies": {
+    "unified": "^11.0.5",
+    "unist-util-select": "^5.1.0"
+  },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.13.0",
     "@types/unist": "^3.0.3",
     "tsup": "^8.0.0",