# @canofold/plugins 中文文档

规范地址：https://npmcn.com/package/%40canofold/plugins/

版本：0\.8\.3
npm 元数据更新时间：2026-10-21T13:57:48.719Z
中文译文更新时间：2026-11-09T18:56:28.168Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40canofold/plugins
原文对照：https://npmcn.com/package/%40canofold/plugins/?lang=original
项目主页：https://canofold.dev/
源码仓库：https://github.com/canofold/canofold

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：549 kB，53 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：8 个
- peer 依赖：mermaid ^11\.12\.0 \|\| ^12\.0\.0，canofold ^0\.8\.3，pagefind ^1\.5\.2
- 首次发布：2026-09-05T16:10:13.169Z
- 最新版本发布：2026-10-21T13:57:48.406Z
- 近 30 天下载量：1839（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

Canofold 和 @canofold/ markdown 的官方插件和提供者 .

## 安装

```sh
npm install @canofold/plugins
```

也可以使用：`pnpm add @canofold/plugins`、`yarn add @canofold/plugins`、`bun add @canofold/plugins`

## README

# @canofold/plugins

[English](https://npmcn.com/package/%40canofold/plugins/README.md) | 简体中文

`@canofold/plugins` 提供 Canofold 官方维护的 Markdown 插件和搜索 Provider。所有工厂共用一个包版本，常规站点配置从包根导入。

## 在 Canofold 站点中安装

把插件包安装为开发依赖：

```bash
pnpm add -D @canofold/plugins
```

`mermaid` 和 `pagefind` 是可选 Peer，只在启用对应能力时安装：

```bash
pnpm add -D mermaid pagefind
```

支持 Mermaid 11 和 12，新项目建议使用 Mermaid 12；它要求 Node 22.12+ 和 Safari 17.4+ 或具备同等 ES2024 支持的浏览器。Canofold 默认保留 Dagre 布局和 Classic 外观，作者仍可在图表配置中选择其他布局或外观。运行时从站点安装的 `mermaid` 包构建，不内置于 `@canofold/plugins`。

```ts
import { externalLinks, math, mermaid, pagefind } from '@canofold/plugins'
import { defineConfig } from 'canofold'

export default defineConfig({
  search: { provider: pagefind() },
  markdown: {
    plugins: [math(), mermaid(), externalLinks()]
  }
})
```

## 可用工厂

| 工厂 | 契约 | 作用 |
| --- | --- | --- |
| `externalLinks(options?)` | Markdown 插件 | 为站外 HTTP(S) 链接添加安全属性 |
| `readingTime(options?)` | Markdown 插件 | 添加本地化阅读时长 |
| `linkCard(options?)` | Markdown 插件 | 把独占段落的链接转换为链接卡片 |
| `kroki(options?)` | Markdown 插件 | 渲染 Graphviz、D2 和其他 Kroki 图表 |
| `math(options?)` | Markdown 插件 | 使用 remark-math 和 KaTeX 渲染公式 |
| `mermaid(options?)` | Markdown 插件 | 在浏览器中渲染 Mermaid 围栏 |
| `plantUml(options?)` | Markdown 插件 | 配置可信服务后渲染 PlantUML |
| `pagefind(options?)` | Search Provider | 根据最终静态 HTML 生成 Pagefind 索引 |

在 React 应用中直接配合 `@canofold/markdown` 使用时，应把插件安装为普通应用依赖。启用 `math()` 的 React 宿主还需要导入 `@canofold/plugins/math.css`。

包根入口和 `@canofold/plugins/math` 等工厂子路径属于公共 API。生成站点会自动加载浏览器与 CSS 入口。直接使用 React 或编辑器的宿主可以调用下文带类型的图表客户端入口；它们是生命周期增强器，不是插件工厂。

## 本地 OpenAPI 内容来源

使用独立服务端入口，不放入 `markdown.plugins`：

```ts
import { openapi } from '@canofold/plugins/openapi'

export default {
  sources: [openapi({
    id: 'pet-api', root: 'docs/api', entry: 'docs/api/openapi.yaml',
    version: 'current', locale: 'zh', base: '/api/'
  })]
}
```

本地 OpenAPI 3.0.x/3.1.x JSON/YAML 生成概览及每个入选 path operation 的独立页面，与普通 Markdown/MDX 首页共同构建。`root`、`entry` 均相对于项目，所有引用须在 `root` 内，版本/语言须已配置。`base` 是语言内路由前缀，`info.version` 是 API 版本，不是文档版本。可选 `include.paths` 精确匹配，`include.tags` 匹配任意标签；同时指定时取交集。空数组、重复项或没有匹配结果的选择器报错。

网址使用小写方法和原始 path 的 UTF-8 十六进制编码，每段最多 64 个字符。例如 `/api/` 下 `GET /pets` 为 `/api/get/2f70657473/`；API path 最多 1,024 个 UTF-8 字节。标签只影响展示分组，不复制身份。参数、请求/响应媒体类型、示例、认证、服务器、弃用与原始 schema 组合进入同一条站点/搜索/机器输出链；描述与示例仅作为惰性数据，不执行 Markdown 或请求。

不获取远程引用，schema URI 标识不授予联网权限。符号链接、越界、缺失引用和歧义 Path Item 同名字段明确失败。上限：单文件 16 MiB、单来源 64 MiB/512 文件、JSON 128 层/100 万节点、YAML 别名展开 50、10,000 个接口加概览、生成正文/事实合计 64 MiB、每页引用 schema 16 MiB。失败保留上一份完整构建，不截断事实。首版不含 Swagger 2.0/3.2、远程同步、Try-it-out、SDK 生成和独立 Callback/Webhook 页面。

历史入口与引用须在该版本 `docsDir` 内，快照复制版本内文件但不重写来源配置。浏览器/Markdown 入口不加载解析器；严格 JSON 使用微软 MIT 许可的 `jsonc-parser` 访问器，禁用注释和尾逗号并拒绝重复键；YAML 复用 `yaml`，语法结构校验使用 MIT 许可的 Redocly 2.x。Canofold 0.8 要求 Node 22.12 或更高版本。完整接入及边界见 [OpenAPI 文档](https://canofold.dev/guide/writing/openapi/)。

## 由宿主提供本地图表渲染

PlantUML 和 Kroki 可以把渲染交给浏览器宿主，而不把源码发送给外部服务。编译 Markdown 时选择客户端 renderer，并在 Markdown DOM 挂载后把一个 renderer 函数传给对应的客户端增强器：

```ts
import { kroki } from '@canofold/plugins/kroki'
import { enhance, type DiagramRenderer } from '@canofold/plugins/client/kroki'

export const diagramPlugin = kroki({ renderer: 'client' })

const renderer: DiagramRenderer = async ({ diagramType, source, signal }) => {
  const svg = await renderLocally({ diagramType, source, signal })
  return { svg }
}

const diagrams = enhance(markdownRoot, { renderer })
await diagrams.ready

// Markdown 内容被替换或卸载时执行。
diagrams.dispose()
```

renderer 会收到 `kind`、原始围栏 `language`、映射后的 `diagramType`、`source` 和 `AbortSignal`，并且必须返回非空 SVG 字符串。增强器通过可回收的 `blob:` 图片 URL 展示 SVG，保留源码切换、缩放和放大预览，在失败时显示本地化状态，并在销毁时还原原始 DOM。因此，使用严格 CSP 的宿主需要在 `img-src` 中允许 `blob:`。

即使 Canofold 页面运行时已经先执行过不带 renderer 的增强，再传入 renderer 也会升级现有图表壳，不会重复绑定控件。宿主仍然拥有新返回的生命周期，并且必须在替换或卸载渲染内容时执行 dispose。

Worker、本地进程或编辑器消息桥由宿主负责。`@canofold/plugins` 不启动可执行程序，也不定义 VS Code 协议；`@canofold/markdown` 不感知具体图表运行时。

`kroki()` 默认把图表源码留在本地。远程渲染必须显式配置可信的 Kroki 兼容服务；需要由宿主在本地渲染时使用上文的 renderer：

```ts
kroki()
kroki({ server: 'https://kroki.example' })
kroki({ renderer: 'client' })
```

`plantUml({ renderer: 'client' })` 通过 `@canofold/plugins/client/plantuml` 使用同一套客户端契约。两个工厂都不允许同时设置远程 `server` 和 `renderer: 'client'`。server 必须是没有查询参数或片段的 HTTP(S) 基础 URL。

配置 `server` 后会生成远程图片 URL，浏览器加载图片时会把图表源码发送给该服务。私有内容请使用可信的自托管服务，或选择本地客户端渲染；这项显式配置不在每次构建时重复打印警告。

### 公式隔离与依赖边界

`math()` 的宏只在当前文档内共享，不会修改插件配置或泄漏到下一篇文档。`throwOnError: true` 会使无效公式编译失败；默认值 `false` 保留错误标记。

从 0.4.1 起，发布包包含官方 Markdown 公式适配器，并统一使用直接声明的 KaTeX 0.18.x 渲染器及配套 CSS、字体。消费方不需要添加依赖覆盖规则。

可选 Mermaid 使用其自身的上游运行时，不与 `math()` 共用 KaTeX。Mermaid 12.2.0 已声明 KaTeX 0.18.x，应使用它或更新的受支持版本，不跨版本强制覆盖依赖。Canofold 从安装的包入口构建运行时，并保留 `securityLevel: 'strict'`。

Mermaid 11 的 API 仍受支持，但它包含 KaTeX 0.16.x，存在 [GHSA-238p-pmpm-9mq7](https://github.com/advisories/GHSA-238p-pmpm-9mq7) 低危告警（利用前提是已经发生原型污染）。仅升级 `@canofold/plugins` 不会升级站点的可选 Mermaid Peer；需要安装 `mermaid@^12.2.0` 才能离开受影响的依赖范围，并满足前述浏览器和 Node 要求。

选项、完整示例、生命周期区别和验证方法见[官方插件指南](https://canofold.dev/guide/site/plugins/)。

许可证：MIT

## 常见问题

### @canofold/plugins 是什么？

Canofold 和 @canofold/ markdown 的官方插件和提供者 \.

### 如何安装 @canofold/plugins？

在项目目录运行 npm install @canofold/plugins，或使用 pnpm add / yarn add / bun add。

### @canofold/plugins 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @canofold/plugins 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @canofold/plugins 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @canofold/plugins 可以商用吗？

@canofold/plugins 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @canofold/plugins 的下载量有多少？

根据 npm 官方下载统计，@canofold/plugins 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,839 次，日均约 61 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @canofold/plugins 还在维护吗？

最新版本 0\.8\.3 发布于 2026/10/21（19 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。