# @godxjp/markdown 中文文档

规范地址：https://npmcn.com/package/%40godxjp/markdown/

版本：33\.30\.5
npm 元数据更新时间：2026-11-13T16:01:24.091Z
中文译文更新时间：2026-11-16T18:07:39.411Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40godxjp/markdown
原文对照：https://npmcn.com/package/%40godxjp/markdown/?lang=original
项目主页：https://github.com/godx-jp/godxjp-ui#readme
源码仓库：https://github.com/godx-jp/godxjp-ui

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

- 包体积（解压后）：118 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：21 个
- peer 依赖：react \>=19\.0\.0，mermaid ^11\.0\.0
- 首次发布：2026-10-02T14:46:17.286Z
- 最新版本发布：2026-11-13T16:01:23.856Z
- 近 30 天下载量：12035（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：144（近 12 个月 144 个）

## 中文简介

GODX 应用程序的 Markdown 渲染器: GFM + 标题主锚, KaTeX 数学, 突出代码, 一个 sanitiser schema, 一个共享的固定器, 和美人鱼在它的 SVG 通过一个故障闭门后才绘制 .

## 安装

```sh
npm install @godxjp/markdown
```

也可以使用：`pnpm add @godxjp/markdown`、`yarn add @godxjp/markdown`、`bun add @godxjp/markdown`

## README

# @ godxjp/ 标记下

GODX 应用程序的 Markdown 渲染器( godx 任务、 godx 内容, 以及后来的邮件、 聊天和 核准)。 一条管线,一条疗养装置,一条固定装置——所以安全装置发生一次.

```bash
pnpm add @godxjp/markdown        # + `mermaid` (optional) to draw ```mermaid fences
```

```tsx
import "@godxjp/markdown/katex.css"; // once, in the app entry: KaTeX's stylesheet + fonts
import { Prose } from "@godxjp/ui/data-display";
import { Markdown } from "@godxjp/markdown";

<Prose>
  <Markdown>{page.body}</Markdown>
</Prose>;
```

## 它意味着什么

GFM — 表格、 任务列表( 只读), 有栅栏的代码 `language-*` 分类、自动链接、脚注、, 通过打击——和 `id` 各行其道(吉特胡布,去重写). 输出相同 作为 `react-markdown` + 键 `remark-gfm` + 键 `rehype-sanitize`,这就是应用程序 之前提供.

**数学** —— 说 `$…$` 财务报告和审定财务报表 `$$…$$` 内线, a `$$` 块或一个 ` ```math ` 用于显示的栅栏——是 kaTeX 在解析时绘制( 没有 DOM: 在浏览器、 服务器、 工作人 中相同的 HTML) , 如 HTML 加上 MathML,所以一个屏幕读取器会读取公式. 内容为字面的TeX: `\,` 保留它 反斜线。 单人 `$` 遵守潘多克的规矩,所以价格维持原教旨主义: `$5 and $10` 财务报告和审定财务报表 `$5-$10` 为: 文本(打开处) `$` 之后是非空格,关闭后是非空格,而不是 以 `\`,而不是后面的数字)。 写入 `\$` 一个字形的美元,任何地方。 一个可以 不分析其来源于 `.katex-error`。 。 。 .

**KaTeX 样式表是主机要加载的**,一次: `import "@godxjp/markdown/katex.css"`。 `@import`编号 `katex/dist/katex.min.css` 从 KaTeX 此软件包依赖于( 所以 CSS 总是 匹配渲染器; 任何解析 CSS 的捆绑器 `@import` 从 `node_modules` 维特 网络包装, esbuilt ——复制字体),并让一个宽放的公式卷轴来代替拓宽页面. 没有它, 公式会变成未拼接的文本加 MathML .

**语法颜色** - 一种已知语言的栅栏在解剖时间是象征的,每个标志都是 `<span data-code-token="…">`,带有工具包的名称(`comment`, (中文(简体) ), `keyword`, (中文(简体) ), `string`, (中文(简体) ), `string-expression`, (中文(简体) ), `function`, (中文(简体) ), `constant`, (中文(简体) ), `parameter`, (中文(简体) ), `punctuation`, (中文(简体) ), `link`, (中文(简体) ), `inserted`, (中文(简体) ), `deleted`, (中文(简体) ), `changed`) (中文(简体) ). `Prose` 颜色来自 `--code-block-token-*` 轻而易举 轻而易举 这个包裹没有代码调色板 语言:出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出击出, java, javascript, json, markdown, php, python, 生锈, sql, typescript, xml/html, yaml (与他们的) 化名 : `ts`, (中文(简体) ), `js`, (中文(简体) ), `jsx`, (中文(简体) ), `tsx`, (中文(简体) ), `sh`, (中文(简体) ), `zsh`, (中文(简体) ), `yml`, (中文(简体) ), `html`, (中文(简体) ), `py`, (中文(简体) ), `rs`(中文(简体) ). 任何其他语言, 一个没有围栏的栅栏, ` ```mermaid ` 财务报告和审定财务报表 ` ```math ` 保留纯文本.

每个表格都会在滚动框内制作(`.ui-prose-table-scroll`,样式由 `Prose`),键盘 - 只在浮出水面时可聚焦,所以一个宽的表格滚动而不是扩大页面.

## 安全问题

-   **无生 HTML.** 源代码中的 HTML 被丢弃,从未被解析成元素 .
-   **一个计划** (单位:千美元)`markdownSchema`: 允许链接 `http`, (中文(简体) ), `https`, (中文(简体) ), `mailto` 和相对的URL; 允许图像 `http`, (中文(简体) ), `https` 和相对的 URL. `javascript:`, (中文(简体) ), `data:` 以及所有其他计划 已删除 —— 包括由标签或新行拆分的方案。 SVG 从未从 URL 内置 .
-   **KaTeX 运行与 `trust: false`, (中文(简体) ), `strict: "error"` 财务报告和审定财务报表 `maxSize: 10`**在疗养者之前, 和计划允许KaTeX 准确的表达: MathML 元素, KaTeX 自己的类名, 仅以几何为主的内线样式(长度、颜色、关键词——不) `url()`,完全没有括号)和 `svg` 编号 : `path` 编号 : `line` 用于基和伸缩箭头(无) `href`,没有 `<image>`) (中文(简体) ). `\href`, (中文(简体) ), `\url`, (中文(简体) ), `\includegraphics`, (中文(简体) ), `\htmlClass`, (中文(简体) ), `\htmlId`, (中文(简体) ), `\htmlStyle` 财务报告和审定财务报表 `\htmlData` 作为《京都议定书》缔约方会议的《公约》 自有源文本。 一种非标准构件仍然在画 (rehype-katex 重试 ), `trust` 实值 从未放松); 用户大小的框(`\rule{9999em}{9999em}`)被封为10em.
-   **代码符号** 为: `span`s 的唯一属性是 `data-code-token`十二个名字; 身体不能薄荷( raw HTML 被丢弃) .
-   **美人鱼在SVG过后才成为图片 `checkMermaidSvg`**: 无 `<script>`, (中文(简体) ), `<foreignObject>`, (中文(简体) ), `<a>`, (中文(简体) ), `<image>`,事件处理器,无碎片 `href`, (中文(简体) ), `url()` 离开 文档,或 `@import`。一个失败的图表,或者一个没有 `mermaid`,显示代码.

## 主机扩展点

| 道具 | 使用情况 |
| --- | --- |
| `remarkPlugins` | 主机标记(呼叫,嵌入). 他们的输出仍被消毒. |
| `schema` | `{ tagNames, attributes }` 标记需要。 已经限制的属性规则被合并到其中(`code` `className` + 键 `math-inline`) (中文(简体) ). 无法扩展 URL 策略 . |
| `resolveUrl(url, key)` | 映射主机计划( I)`asset:…`)在疗养者判断它之前使用真实的URL. |
| `headingId({ depth, text, index })` | 使用服务器指定的主机, 而不是弹簧 . |
| `components` | 元素覆盖。 在主机前画出人鱼围栏 `pre` 所以一个主机代码渲染器会保留美人鱼. |
| `rehypePlugins` | 跑去疗养所——仅演示. |
| `mermaid={false}` | 将"美人鱼"围栏作为密码(或交给主机) `pre`) (中文(简体) ). |
| `highlight={false}` | 留下有栅栏的代码作为纯文本——一个主机 `pre` 运行自己的亮点。 一个主机 `pre` 以其他方式收到标记 `<code>`。 。 。 . |
| `allowedElements` 编号 : `unwrapDisallowed` | 将身体缩小(活动饲料: `strong`, (中文(简体) ), `em`, (中文(简体) ), `del`, (中文(简体) ), `code`) (中文(简体) ). 只取取去. |
| `shortCellLength` | 手持一个短符号的表格单元格( 无空白, 默认情况下为 24 个字符) 获得 `data-short`· ; `Prose` 保持一条线. `false` 关掉. |
| `directives` | 用于容器指令的主制造器 包件没有模型,按名称——见"指令块". |

### 指令块

装箱的集装箱指令不能作为模型—— `:::poll[…]{…}`页:1 `::::form` 举行投票 内容 a `div.ui-prose-directive` (标签为一款). 一个主机赋予它的意义 登记出纸器名称:

```tsx
<Markdown
  directives={{
    // { name, label, attributes, source, body, children }: label / source / body as written
    // (free of a containing callout's `> `), children = the rendered body without the label.
    poll: (block) => {
      const poll = parsePoll(block.source); // the host's own grammar and validation
      return poll ? <PollCard poll={poll} /> : undefined; // undefined: render it as before
    },
    form: (block) => <SurveyForm title={block.label}>{block.children}</SurveyForm>,
  }}
>
  {page.body}
</Markdown>
```

该工具包在指令中不验证任何内容; `toggle`, (中文(简体) ), `columns` 财务报告和审定财务报表 `column` 是它自己的,而且 无法注册 。 这个区块的部分来自同一个读取器与解码器 (单位:千美元)`readDirective(source)` 内 `@godxjp/markdown/codec` 返回时 `{ name, label, attributes, source, body }`)),因此编辑和页面都同意一个街区的说法.

图像: 将身体包入 `<Prose imagePreview>` 打开工具箱预览,呼唤 ——没有 `img` 需要操作 表格单元格中的图像保持分数(自然宽度,20雷姆), 所以一个狭长的桌子 而不是压扁它们.

## 语法 v1 和代码 (`@godxjp/markdown/codec`(中文(简体) )

制造器(`RENDERER_VERSION` 6),解码器和 `@godxjp/block-editor` 从一个读取一个语法 一组解析器,所以一个正体在编辑器,服务器和页面中意为相同的东西.

### 语法

-   **全球调频** 表格、任务列表、切换、自动链接、脚注.
    
-   **CJK 友好型重点** —— 说 `の**「強調」**です` 是强壮的。 普通马克的侧翼规则离开 qq () 旁边的字形星号; 解码器、 渲染器和编辑器都使用 CJK友好扩展.
    
-   **点名** - GitHub 警报: `> [!NOTE]`, (中文(简体) ), `[!TIP]`, (中文(简体) ), `[!IMPORTANT]`, (中文(简体) ), `[!WARNING]`, (中文(简体) ), `[!CAUTION]` (输入时对大小写不敏感, 写大写), 同一行的可选纯文本标题 (单位:千美元)`> [!WARNING] Title`;所引之余为体. 折叠标记( E)`[!NOTE]-` 编号 : `+`或一个 未知类型不是点名:它保持一个普通的块状,标记为逐字记录.
    
-   **切换** —— 说 `:::toggle[Summary *inline*]` . `:::`。身体是任何块; 切换巢穴,坐 里面的呼唤和柱子。 未存储打开状态 .
    
-   **列数** - 2-4列,每列可选 `width` (单位:百分率;无 其余部分各占一等分)。 柱从来入巢.
    
    ```md
    ::::columns
    :::column{width=40}
    Left
    :::
    
    :::column
    Right
    :::
    ::::
    ```
    
    仅存在集装箱指令:指令的栅栏长于最深 里面有指示,所以最里面的栅栏总是 `:::`。没有文本(`:name`或叶 (单位:千美元)`::name`指令 -- -- `10:30` 是传教士.
    
-   **维基链接和嵌入式,逐字记录** —— 说 `[[target]]`, (中文(简体) ), `[[target#heading]]`, (中文(简体) ), `[[target|label]]`, (中文(简体) ), `![[embed]]` (单行时为块;内文为逐字记录-) `![[B#見出し]]`, (中文(简体) ), `![[img.png|300]]`) (中文(简体) ). 周围的标记能活下来`**[[x]]**`) (中文(简体) ). 在表格单元格内写入 `[[x\|label]]`。 。 。 .
    
-   **数学** —— 说 `$x$`, (中文(简体) ), `$$x$$`页:1 `$$` 块, a ` ```math ` 栅栏(潘多克的一美元规则, (见上文)。 解码器保留数学逐字记录作为原始内线 / 生块( 栅栏是普通的) `codeBlock{language: "math"}`),所以块编辑器不需要数学节点. 因为 `$` 现在 特别的,文字 `$x$` 文本为文字 `\$x$`一个孤独 `$` (a price) 永远无法逃脱.
    
-   **`asset:` 图像** —— 说 `![alt](asset:id)` 成文的圆通( 渲染器通过 `resolveUrl`) (中文(简体) ).
    
-   **指令块** - 任何其他集装箱指令(`:::poll[label]{id=x anonymous}` . `:::`, (中文(简体) ), 以栅栏长度筑巢)是一 `directive{name, source}` 节点保持它的犬形源,所以 `normalize` 上面是一分之一的 编辑把它作为一个块。 属性值为 a 外部字符 `[\w.-]` 被引用为书面(`closes="2026-11-10T09:00"`(三); `{#x}` 编号 : `{.x}` 为: 写入 `id=x` 编号 : `class=x`。 。 。 .
    
-   **原始块** ——文档中其他任何不建模(raw HTML,脚注定义,链接) 引用定义、 错误的切换或列行、 有元字符串的栏) 被保留为 把那个记下来 说回同样的事情 美人鱼是普通的 ` ```mermaid ` 栅栏.
    

### 代码c

```ts
import { CODEC_ID, normalize, parse, serialize } from "@godxjp/markdown/codec";

CODEC_ID; // "kit-md@2" — bumped whenever serialize would write a body differently (@2: math)
const doc = parse(markdown); // plain JSON, ProseMirror/Tiptap shape
const md = serialize(doc); // canonical Markdown
normalize(markdown) === serialize(parse(markdown)); // what the editor saves
normalize(normalize(x)) === normalize(x); // idempotent, for every fixture
```

纯:没有反应,没有DOM,没有编辑器——它运行在服务器和Cloudflare Worker上.

**条形** (怎样) `serialize` aTX标题; `-` 子弹; `1.` 订购清单; `*em*`· ; `**strong**`· ; ` ``` ` 栅栏(一个缩入的代码块变成栅栏); `---` 规则; `- [ ]` 编号 : `- [x]` 待办事宜; GFM 表格, 有加亮的单元格和对齐行; 点名后的身体 `>` 空白行; 区块之间有一条空白行; LF; 一条后行; 空文档为 `""`。 。 。 .

## 随需要加载 KaTeX并突出显示.js(`@godxjp/markdown/lazy`(中文(简体) )

KaTeX带有它的样式表和字体,并突出出.js,是这个包的大部分重量. 这个 默认条目将它们捆绑在一起,所以第一个渲染是最终的。 客户端的应用程序导入 同一组件来自 `/lazy` 相反:

```tsx
import { Markdown } from "@godxjp/markdown/lazy"; // and drop the global katex.css import
```

每台发动机都是一个单独的块, 第一次被制成的机体需要时取出(math, 或 a) - KaTeX的块带来 `katex.css` 与它—— 和身体重接一旦 来了 在此之前,数学显示它的 TeX 源作为代码和栅栏是简单的,与 `highlight={false}`在只进口的宿主上用Vite计量 `Markdown`: 条目去 从560 KB JS(173 KB gzip)+23.5 KB CSS到220 KB JS(70 KB gzip),没有CSS; KaTeX是一种 262 KB (78 KB gzip) 块 + CSS, 突出显示.js a 81 KB (26 KB gzip) 块.

**为何缺省要急着处理.** 服务器渲染或工作员同步,不能等待 `import()`,而输出不能取决于装入时发生的情况。 与 `/lazy`,服务器 (或客户端水利服务器 HTML)等待 `preloadMarkdownRuntime(body)` 在渲染之前,所以它的 HTML 匹配急切条目的字节表示字节; `RENDERER_VERSION` 描述已完成的输出 从两个条目.

## 存储版本

记录 `MARKDOWN_FORMAT` (单位:千美元)`"md"`和 `RENDERER_VERSION` 每个保存的版本. `RENDERER_VERSION` 当同一输入产生不同时,会更改.

## 固定设备

`MARKDOWN_FIXTURES` 是共享主目录: 输入 Markdown + 准确的已消毒的 HTML, 与 `forbidden` 敌人的下弦 服务器或导出路径符合此列表 .

## 常见问题

### @godxjp/markdown 是什么？

GODX 应用程序的 Markdown 渲染器: GFM \+ 标题主锚, KaTeX 数学, 突出代码, 一个 sanitiser schema, 一个共享的固定器, 和美人鱼在它的 SVG 通过一个故障闭门后才绘制 \.

### 如何安装 @godxjp/markdown？

在项目目录运行 npm install @godxjp/markdown，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @godxjp/markdown 支持 TypeScript 吗？

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

### @godxjp/markdown 支持 ESM 还是 CommonJS？

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

### @godxjp/markdown 可以商用吗？

@godxjp/markdown 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @godxjp/markdown 的下载量有多少？

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

### @godxjp/markdown 还在维护吗？

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

