docmd 拥有模块化的插件架构。必需的插件随核心包一起发布，无需安装。可选插件可通过一条 CLI 命令安装。

安装插件

使用 docmd CLI 安装和移除插件：

# 安装插件
npx @docmd/core add <plugin-name>

# 移除插件
npx @docmd/core remove <plugin-name>

安装程序会检测您的包管理器（npm、pnpm、yarn 或 bun）。它会将短名称解析为完整包名，并将配置注入到您的 docmd.config.json 中。

使用 --verbose（或 -V）获取完整的安装程序输出：

npx @docmd/core add <plugin-name> -V

必需的插件

这些插件与 @docmd/core 捆绑。无需安装。在您的 docmd.config.json 中启用它们：

  "plugins": {
    "search": {},
    "seo": { "aiBots": false },
    "sitemap": {},
    "analytics": {},
    "llms": {},
    "okf": {},
    "mermaid": {},
    "openapi": {},
    "git": {}
  }

可选插件

可选插件需要先安装才能启用。

自动安装

当您将一个官方插件添加到 docmd.config.json 但尚未安装时，docmd 会在下次构建时自动下载并安装它。这适用于官方注册表中的所有插件。

{
  "plugins": {
    "pwa": {}
  }
}

自动安装程序：

• 仅针对官方 @docmd/plugin-* 包。
• 锁定版本以匹配您的 @docmd/core 安装。
• 检测并使用您项目的包管理器。
• 在终端中报告进度。

第三方与自定义插件

出于安全考虑，安装程序强制执行官方注册表白名单。第三方插件必须使用您的包管理器原生安装：

npm install my-custom-plugin
# 或 pnpm add、yarn add、bun add

安装后，使用其精确的包名将插件添加到您的 docmd.config.json：

{
  "plugins": {
    "my-custom-plugin": {
      "someOption": true
    }
  }
}

如果该插件符合 docmd 的要求，它会在构建期间自动激活。否则，引擎会报告错误。

插件作用域与 noStyle 覆盖

插件会全局注入 CSS 和行为。但是，您可以配置它们以绕过特定页面，或完全禁用在无样式落地页（noStyle: true）上的执行。

全局配置范围

通过您的 docmd.config.json 指示任何插件自动跳过 noStyle 页面：

{
  "plugins": {
    "math": {
      "noStyle": false
    }
  }
}

页面本地作用域（Frontmatter）

您可以通过 markdown frontmatter 为每个文档明确启用或禁用任何插件。

---
noStyle: true
plugins:
  math: true
  threads: false
---

# Only Math renders here, Threads are completely blocked

插件生命周期

插件会钩入构建和开发过程的不同阶段：

插件安全性

插件系统保证构建安全：

• 验证：无效的插件描述符在加载时即被拒绝。
• 隔离：每次钩子调用都被包裹在 try/catch 中。损坏的插件不会导致构建崩溃。
• 能力强制：插件只能注册它们声明过的钩子。

完整 API 参考请参阅 构建插件。