# @canofold/markdown 中文文档
规范地址：https://npmcn.com/package/%40canofold/markdown/
版本：0\.8\.3
npm 元数据更新时间：2026-10-21T13:58:46.425Z
中文译文更新时间：2026-11-09T17:11:46.678Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40canofold/markdown
原文对照：https://npmcn.com/package/%40canofold/markdown/?lang=original
项目主页：https://canofold.dev/markdown/
源码仓库：https://github.com/canofold/canofold
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：744 kB，138 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：21 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2026-09-05T16:09:02.745Z
- 最新版本发布：2026-10-21T13:58:46.058Z
- 近 30 天下载量：2187（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）
## 中文简介
用于知识和文件网站的交互式、可主题的Markdown渲染器.
## 安装
```sh
npm install @canofold/markdown
```
也可以使用：`pnpm add @canofold/markdown`、`yarn add @canofold/markdown`、`bun add @canofold/markdown`
## README
# @canofold/markdown
[English](https://npmcn.com/package/%40canofold/markdown/README.md) | 简体中文
`@canofold/markdown` 是可独立使用的 Markdown SDK。它提供 React 渲染、Markdown 与可信 MDX 的构建或 SSR、内容分析、结构样式和按行为加载的浏览器增强。视觉主题由 `@canofold/themes` 提供。
## 安装与渲染
```bash
pnpm add @canofold/markdown @canofold/themes react react-dom
```
```tsx
import { Markdown } from '@canofold/markdown'
import '@canofold/markdown/base.css'
import '@canofold/themes/canofold.css'
export function Article({ source }: { source: string }) {
return
}
```
## 公开入口
- `@canofold/markdown` 提供 React 渲染器和插件契约。
- `@canofold/markdown/server` 提供 Markdown 与可信 MDX 的构建或 SSR 渲染器。
- 服务端渲染器的 `analyze()` 返回编译后的内容事实及 `assets` 资源需求，不执行作者的 MDX 组件。宿主可在渲染页面前准备交互脚本和样式。
- `@canofold/markdown/server/analyze` 只分析文档能力，不执行渲染。
- `@canofold/markdown/client` 增强已经生成的静态 HTML。
- `@canofold/markdown/base.css` 提供 Markdown 结构与交互样式。
- `@canofold/themes` 提供主题契约和官方视觉主题；在 `base.css` 之后引入其中一个主题 CSS 入口。
在 Vite 等 bundler 中导入 `@canofold/markdown/client` 时，React 与 React DOM 继续由宿主应用的 peer dependency 提供，不会隐藏内置另一份 React。Canofold CLI 生成不依赖 bundler 的独立静态站点时，会自动选择自包含的本地浏览器资源；两种消费方式使用同一个公开入口，不需要用户配置 alias、import map 或运行时路径。
数学公式等可选语法由 `@canofold/plugins` 提供：
```bash
pnpm add @canofold/plugins
```
```tsx
import { Markdown } from '@canofold/markdown'
import { math } from '@canofold/plugins'
import '@canofold/markdown/base.css'
import '@canofold/themes/canofold.css'
import '@canofold/plugins/math.css'
```
渲染选项、MDX、写作语法、主题和浏览器增强见 [Markdown SDK 文档](https://canofold.dev/markdown/)。
编写预览可设置 `options={{ directives: { invalid: 'literal' } }}`，把格式错误或未知的富内容指令显示为转义后的原文，其余文档照常渲染。默认值仍为 `error`，构建时继续检查指令拼写。`format:check` 这样的普通冒号文本会保留为文本，除非该指令名属于内置语法或已由插件明确声明。此策略不会吞掉插件异常，也不会放宽 HTML 清理、媒体 URL 校验或 MDX 执行边界。
许可证：MIT
## 常见问题
### @canofold/markdown 是什么？
用于知识和文件网站的交互式、可主题的Markdown渲染器\.
### 如何安装 @canofold/markdown？
在项目目录运行 npm install @canofold/markdown，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @canofold/markdown 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @canofold/markdown 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @canofold/markdown 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @canofold/markdown 可以商用吗？
@canofold/markdown 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @canofold/markdown 的下载量有多少？
根据 npm 官方下载统计，@canofold/markdown 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,187 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @canofold/markdown 还在维护吗？
最新版本 0\.8\.3 发布于 2026/10/21（19 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。