# @basenative/markdown 中文文档

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

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:50:55.657Z
中文译文更新时间：2026-10-31T15:48:26.713Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basenative/markdown
原文对照：https://npmcn.com/package/%40basenative/markdown/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/markdown#readme
源码仓库：https://github.com/DuganLabs/BaseNative

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

- 包体积（解压后）：41.9 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-18T05:29:28.514Z
- 最新版本发布：2026-10-31T13:50:55.312Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

零依赖ES模块降价解析器和ssr安全的HTML渲染器

## 安装

```sh
npm install @basenative/markdown
```

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

## README

# @basenative /减价

零依赖ES模块降价解析器和ssr安全的HTML渲染器。

## 功能

-   **零依赖关系** —不需要外部包装
-   **纯ES模块** -工作在Node.js 22+和现代浏览器
-   **SSR-safe** —无DOM访问，生成纯HTML字符串
-   **以安全为目的** XSS预防，URL清理，HTML实体转义
-   **AST-first** -解析到AST和单独渲染，或使用方便 `parse()` 对HTML

## 支持减价

-   航空运输税目(`#`–`######`)及settext标题(`===`， `---` 突显出)
-   段落
-   大胆的`**text**`， `__text__`）
-   斜体(`*text*`， `_text_`）
-   粗体加斜体(`***text***`， `___text___`）
-   删除线(`~~text~~`）
-   内联代码(`` `text` ``)和带有内嵌反勾的双反勾代码
-   链接(`[text](url)`)及标题连结(`[text](url "title")`）
-   图像(`![alt](url)`）
-   autolink (`<https://example.com>`， `<user@example.com>`）
-   无序列表(`-`， `*`， `+`)和有序列表(`1.`， `2.`,……)
-   嵌套列表（缩进两个空格）
-   任务列表(`- [ ] todo`， `- [x] done`) - GFM
-   代码块——用 ` ``` ` 或者 `~~~`，带有可选的语言标记
-   您(`>`)与延迟延拓
-   横规(`---`， `___`， `***`）
-   表- ggm样式，具有列对齐(`:---`， `:---:`， `---:`）
-   硬断行(两个尾随空格或尾随 `\`）
-   用于标点符号的反斜杠转义
-   yaml样式的页眉(`---` … `---`）

## 使用

```js
import { parse, parseAST, render, parseFrontmatter } from '@basenative/markdown';

// One-shot: markdown → HTML
const html = parse('# Hello\n\nThis is **bold**.');

// Two-step: markdown → AST → HTML (lets you transform the AST)
const ast = parseAST('# Hello');
const html2 = render(ast);

// Frontmatter
const { meta, content } = parseFrontmatter(`---
title: Post
---

# Body`);
```

渲染器也可以作为单独的子路径导入：

```js
import { render } from '@basenative/markdown/renderer';
```

## 表

```md
| Name  | Role     | Score |
| :---  | :------: | ----: |
| Alice | designer |    42 |
| Bob   | engineer |   100 |
```

列对齐是从分隔行(`:---` 离开了, `:---:` 中心, `---:` 右)，并发出为 `style="text-align:..."` 在每个细胞上。

## 安全

渲染器包括内置的XSS攻击保护：

-   HTML实体在所有文本节点（包括表格单元格）中进行转义。
-   `javascript:`， `data:`, `vbscript:` url被阻断
-   图像、文本和代码语言类被转义
-   所有属性都被安全引用

## 任务列表

```md
- [x] Write the parser
- [x] Write the renderer
- [ ] Ship it
```

渲染为 `<ul class="task-list">` 与 `<input type="checkbox" disabled>` (或 `checked disabled`在每一个里面 `<li class="task-list-item">`.

## 限制

-   没有参考样式的链接(`[text][id]` + `[id]: url`）
-   没有HTML直通-原始HTML被转义
-   不支持LaTeX/math
-   没有自定义语法扩展

## 许可证

apache - 2.0

## 常见问题

### @basenative/markdown 是什么？

零依赖ES模块降价解析器和ssr安全的HTML渲染器

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

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

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

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

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

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

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

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

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

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