kimhongyeon/safe-markdown2html

# safe-markdown2html 将 Markdown 转换为 **经过净化的 HTML**。默认安全 —— 防止 XSS 并修复格式错误的标记。 [](https://github.com/kimhongyeon/safe-markdown2html/actions/workflows/ci.yml) [](https://www.npmjs.com/package/safe-markdown2html) [](https://opensource.org/licenses/MIT) ## 功能特性 - **XSS 防护** — HTML 在转换后通过 [DOMPurify](https://github.com/cure53/DOMPurify) 进行净化 - **Markdown 解析** — 由 [marked](https://github.com/markedjs/marked) 驱动 - **安全链接** — 所有 `` 标签自动添加 `target="_blank"` - **粗体语法修复** — 处理带括号的 `**bold**` 无法解析的边缘情况 - **畸形 URL 修正** — 修复因括号而断开的 URL（常见于韩语文本） - **删除线** — 默认保留标准 `` 标签，可选波浪号转换 - **环境感知** — 在浏览器中使用原生 DOM，在 Node.js 中使用 `jsdom`（可选 peer dependency） - **双构建版本** — 同时支持 ESM 和 CommonJS ## 安装 ``` npm install safe-markdown2html ``` 对于 Node.js（服务端），还需安装 `jsdom`： ``` npm install safe-markdown2html jsdom ``` 在浏览器环境中，不需要 `jsdom` —— 会自动使用原生的 `window` 对象。 ## 使用方法 ``` import { safeMarkdown2Html } from 'safe-markdown2html'; const html = safeMarkdown2Html('**Hello** [world](https://example.com)'); //

Hello world

``` 也支持默认导入： ``` import safeMarkdown2Html from 'safe-markdown2html'; ``` ## 环境支持 | 环境 | DOM 来源 | 需要安装 `jsdom` | |---|---|---| | 浏览器 (React, Vue 等) | 原生 `window` | 否 | | Node.js / SSR | `jsdom` | 是 | | 自定义 | `window` 选项 | 否 | 在**浏览器**中，自动使用原生的 `window` 对象 —— 无需额外依赖。 在 **Node.js** 中，`jsdom` 提供 DOMPurify 所需的 DOM 环境。请将其作为 peer dependency 安装： ``` npm install jsdom ``` 你也可以通过 `window` 选项直接传入自定义的 `window` 对象以实现完全控制。 ## 配置选项 所有选项均为可选。已应用合理的默认值。 ``` safeMarkdown2Html(markdown, { linkTargetBlank: true, // Add target="_blank" to links (default: true) fixMalformedUrls: true, // Fix URLs broken by parentheses (default: true) fixBoldSyntax: true, // Fix bold syntax with parentheses (default: true) convertStrikethrough: false, // Convert to tilde ~ (default: false) window: customWindow, // Custom window object for DOMPurify }); ``` | 选项 | 类型 | 默认值 | 描述 | |---|---|---|---| | `linkTargetBlank` | `boolean` | `true` | 为所有锚点标签添加 `target="_blank"` | | `fixMalformedUrls` | `boolean` | `true` | 修复因括号和非 ASCII 字符导致的断开 URL | | `fixBoldSyntax` | `boolean` | `true` | 修复因括号导致解析失败的 `**bold**` 语法 | | `convertStrikethrough` | `boolean` | `false` | 将 `` 标签转换为波浪号 (`~`) 表示法 | | `window` | `object` | 自动检测 | DOMPurify 使用的 Window 对象（浏览器：原生，服务器：JSDOM） | ### 示例 #### 禁用 target="_blank" ``` safeMarkdown2Html('[link](https://example.com)', { linkTargetBlank: false, }); ``` #### 启用删除线转换 ``` safeMarkdown2Html('~~deleted text~~', { convertStrikethrough: true, }); //

~deleted text~

``` #### 自定义 window（测试 / 自定义环境） ``` import { JSDOM } from 'jsdom'; safeMarkdown2Html('**hello**', { window: new JSDOM('').window, }); ``` ## API ### `safeMarkdown2Html(markdown: string, options?: SafeMarkdown2HtmlOptions): string` 将 Markdown 字符串转换为经过净化的 HTML。 **处理流程：** 1. 预处理粗体语法 (`**text**` → ``) —— 如果启用了 `fixBoldSyntax` 2. 解析 Markdown → HTML（通过 `marked`） 3. 净化 HTML（通过 `DOMPurify`） 4. 修复畸形 URL —— 如果启用了 `fixMalformedUrls` 5. 为所有链接添加 `target="_blank"` —— 如果启用了 `linkTargetBlank` 6. 将 `` 标签替换为 `~` —— 如果启用了 `convertStrikethrough` 7. 修复剩余未转换的粗体语法 —— 如果启用了 `fixBoldSyntax` ## 开发 ``` npm install npm test # Run tests npm run build # Build (ESM + CJS + d.ts) npm run lint # Lint npm run typecheck # Type check ``` ## 许可证 [MIT](./LICENSE)