# bananamark 中文文档

规范地址：https://npmcn.com/package/bananamark/

版本：0\.2\.1
npm 元数据更新时间：2026-11-03T02:36:03.972Z
中文译文更新时间：2026-11-03T05:41:51.703Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/bananamark
原文对照：https://npmcn.com/package/bananamark/?lang=original
项目主页：https://github.com/banana-space/banana/tree/main/packages/bananamark#readme
源码仓库：https://github.com/banana-space/banana

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

- 包体积（解压后）：449 kB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：14 个
- peer 依赖：@lezer/common ^1\.5\.3，@lezer/markdown ^1\.8\.0，@lezer/highlight ^1\.2\.5，@codemirror/language ^6\.13\.1，@codemirror/lang-yaml ^6\.1\.3，@codemirror/lang-markdown ^6\.5\.2
- 首次发布：2026-10-28T03:02:33.552Z
- 最新版本发布：2026-11-03T02:36:03.816Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

用于数学写作的Markdown方言：公式，编号章节和定理，交叉引用，参考书目，维基链接和中文排版，呈现为HTML

## 安装

```sh
npm install bananamark
```

也可以使用：`pnpm add bananamark`、`yarn add bananamark`、`bun add bananamark`

## README

# bananamark

香蕉语是Markdown的数学写作方言。它向Markdown添加TeX公式、编号的章节和定理以及交叉引用，并将文档呈现为HTML。

```markdown
## Groups

::: definition [Group] {@def:group}
A **group** is a set with an associative operation, an identity $e$ and inverses.
:::

By @def:group, every group has an identity.
```

这里的章节编号为1，定义的标题为“definition 1.1 （Group）”，参考文献变为阅读“definition 1.1”的链接。

它还支持参考书目、脚注、TikZ图表和中文排版。它可以用作命令或库，并呈现的页面 [香蕉空间](https://bananaspace.org/)，中文数学维基。

## 安装

```sh
npm install bananamark       # in a project
npm install -g bananamark    # for the command, anywhere
```

或不安装： `npx bananamark file.md`． 节点22及以上版本。

## 从命令行

```sh
bananamark file.md
```

写 `file.html` 在文件旁边：一个包含其样式表和字体的整个页面，它可以自己打开并离线工作。错误将其行命名为(`file.md:5: unknown theorem environment: nope`)，命令以状态1退出。

| 选项 | 意义 |
| --- | --- |
| `-o`， `--output <file>` | HTML的去向； `-` 用于标准输出 |
| `--fragment` | 只有主体的HTML，才能放入您自己的页面（样式） [`bananamark/style.css`](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#the-stylesheet) 和 `bananamark/katex.css`） |
| `--css <file or URL>` | 在其他样式表之后添加的样式表，因此具有优先级：嵌入文件，链接URL。可以给几次吗 |
| `--no-default-style` | 省略了bananark的外观和页面布局，只保留公式所需的内容 |
| `--lang <code>` | 页面语言如下： `zh-cn` 给出了中文排版和在前面的问题上；默认的 `en` |
| `--locale <code>` | 错误的语言， `en` 或者 `zh-cn`;默认的 `en` |
| `--dialect <file>` | 一个模块，包含 [方言](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#the-dialect) (下图) |
| `--tikz` | 编译TikZ图（如下） |
| `-h`， `--help`； `-v`， `--version` |  |

与 `-` 作为文件，它读取标准输入并写入标准输出。

**样式表。** 一个页面包含KaTeX的样式表和字体，以及bananark的 [样式表](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#the-stylesheet) 还有几行布局。给定的文件 `--css` 在这些之后，所以一些规则足以改变外观。环境的颜色是自定义属性：

```css
/* mine.css, for bananamark file.md --css mine.css */
:root { --bm-accent-theorem: crimson; }
a { color: teal; }
body { font-family: sans-serif; }
```

从无到有，添加 `--no-default-style`． 嵌入文件中的地址从页面开始，而不是从文件开始。

**前事。** 的行之间，文件开头的一个YAML块 `---`，是可选的。命令如下 `title` （显示为页面的标题，它可能包含公式）， `lang`， `numbering` 和 `typography` (见 [编号](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#numbering) 和 [排版](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#typography))，并忽略其他字段。

```markdown
---
title: Groups and $\mathbb{Z}$
lang: en
---

## Definition {@sec:def}
…
```

没有一个 `title`，则页面的标题是其第一个标题的文本，否则就是文件名。相对图像地址是按原样编写的，因此它们保存HTML所在的位置。

**它写的是什么。** 参考书目随处可见 [代码的语言](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#code-highlighting) 突出显示;Wiki链接是关闭的，因为单个文件没有站点供它们访问，所以 `[[…]]` 保持文本。要更改或添加宏，请给出 `--dialect` 导出方言设置的模块。它不需要导入，所以它可以在任何安装命令的地方工作：

```js
// dialect.mjs
export default { wikiLinks: true, katex: { macros: { '\\RR': '\\mathbb{R}' } } };
```

模块可以导出what `defineDialect` 返回(作为其默认值，或作为 `dialect`)，然后按原样使用。这需要相同的副本 `bananamark` 作为命令，在项目中安装这两个命令。

**TikZ。** 图需要单独的包 [`bananamark-tikz`](https://github.com/banana-space/banana/tree/main/packages/bananamark-tikz#readme)，安装在旁边 `bananamark`． 与 `--tikz` （或方言） `tikz: true`)它们被编译成SVG，它们的字体也被放在页面中；没有它, ` ```tikz ` 块是普通的代码块。要在不安装的情况下尝试： `npx -p bananamark -p bananamark-tikz bananamark file.md --tikz`.

## 在程序中

```js
import { renderDocument } from 'bananamark';
import 'bananamark/katex.css';   // with a bundler; or serve katex/dist/ of the same KaTeX version, 0.18.4
import 'bananamark/style.css';   // a plain look, to start from

const source = '## Groups {@sec:groups}\n\n::: definition [Group] {@def:group}\nA set with an operation…\n:::\n\nBy @def:group, $e$ is unique.';
const result = renderDocument(source, { file: 'groups.md' });
result.html;       // the body's HTML: "Definition 1.1 (Group)", "By Definition 1.1, …"
result.headings;   // [{ level: 2, id: 'groups', number: '1', title: 'Groups' }]
```

要渲染多个页面，一次创建一个处理器：

```js
import { createProcessor, defineDialect } from 'bananamark';

const dialect = defineDialect({ wikiLinks: true, bibliography: true });
const processor = createProcessor({
  dialect,
  resolveWikiLink: target => articles.has(target) ? { url: `/wiki/${encodeURIComponent(target)}/` } : undefined,
});
for (const [file, source] of pages) output.set(file, processor.render(source, { file }).html);
```

页面的首页内容是调用者的：在呈现之前删除它，然后给出 `lineOffset` （正文前的行数），以便错误指向文件自己的行。

## 语法

通用标记与GFM表格，划线和脚注，以及：

| 特征 | 写 |
| --- | --- |
| 公式 | `$…$`， `\(…\)`;显示 `$$…$$`， `\[…\]`;编号: ` ```math {@eq:label} ` 块 |
| 部分 | `##` 标题是编号的； `## Title*` 不是; `{@sec:label}` 最后声明一个标签 |
| Theorem-like环境 | `::: theorem [Title] {@thm:label}` … `:::`； `::: definition (Name)` 给环境起了自己的名字， `remark*` 是数不清的; `::: proof` (类型:看 [默认的环境](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#default-environments)） |
| 交叉引用 | `@label`， `{@label}`， `@-label` （单是数字）， `[text](@label)` |
| 标签列表项 | `(a)`， `iv)`， `(A1)` 诸如列表标记； `(a) {@it:label} text` 可以参考 |
| 数据块 | Fenced阻塞调用者名称，保存有关该页的数据，不显示(参见 [数据块](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#data-blocks)） |
| html样式标签 | `<lang de>…</lang>`;调用者可以添加自己的，而香蕉是现成的 `<align right>…</align>` 和 `<spoiler title="…">…</spoiler>` (见 [html样式标签](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#html-style-tags)） |
| 图像的宽度 | `![caption](image.png){width=200}`： `width` （整个像素）变成 `<img width>` |
| 排版 | 中文排字(见 [排版](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#typography)）; 直引号变成了大引号(参见 [引号](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#quotation-marks))， `--`， `---` 和 `...` 变成-，-，… |
| 裸露的地址 | `https://…`， `http://…`， `www.…` 电子邮件地址也变成了链接，就在汉字后面。地址是ASCII格式，并以非ASCII格式的第一个字符结束； `?!.,:;*_~` 和不平衡 `)` 在它的尽头不是它的一部分。将其他人写为 `[text](…)` 或者 `<…>` |
| Wiki连结(`wikiLinks`） | `[[Target]]`， `[[Target|text]]`;目标可能持有公式 |
| 参考文献(`bibliography`） | 一个 ` ```bibliography ` block (YAML； fields：参见 [参考书目字段](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#bibliography-fields)); `@key` 文中引用了一个条目 |
| TikZ (`tikz`） | 一个 ` ```tikz ` 块(`{caption="…"}` 后 `tikz` 给它一个标题)， `tikzcd` 和 `tikzpicture` 公式中的环境(由 `bananamark-tikz`） |

最后三个是关闭的，除非方言打开它们(参见 [方言](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#the-dialect)):否则 `[[…]]` 为文本，且 ` ```bibliography ` 和 ` ```tikz ` 块是普通的代码块。

在这些文档中 _标签_ 是引用的目标(`{@thm:a}`); `<lang>` 类似的还有 _html样式标签_。这个 [参考](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md) 完整地描述了每个特性，规范文件用示例展示了每个特性。

## 包

| 包 | 为什么 |
| --- | --- |
| `bananamark` (一) | 在Node或浏览器中将页面呈现为HTML |
| [`bananamark-tikz`](https://github.com/banana-space/banana/tree/main/packages/bananamark-tikz#readme) | TikZ图(` ```tikz ` 块, `tikzcd` 在公式中)编译成SVG；节点只 |
| [`bananamark-codemirror`](https://github.com/banana-space/banana/tree/main/packages/bananamark-codemirror#readme) | 在CodeMirror 6中编辑方言：高亮显示，补全，键入时检查 |

一个站点呈现为 `bananamark` (加上 `bananamark-tikz` 图);浏览器中的编辑器添加 `bananamark-codemirror`． 描述一下这个地方的方言 [`defineDialect`](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md#the-dialect)，在自己的模块中，并将其分配给每个模块，以便编辑器像渲染器一样读取页面：

```js
// dialect.js, imported by the site's build and by its editor
import { alignTag, defineDialect } from 'bananamark';
export const dialect = defineDialect({ wikiLinks: true, tags: { align: alignTag } });

// the build
createProcessor({ dialect, resolveWikiLink });
// the editor
new EditorView({ extensions: [basicSetup, bananamark({ dialect })] });   // bananamark-codemirror
```

## 文档

-   [REFERENCE.md](https://github.com/banana-space/banana/blob/main/packages/bananamark/REFERENCE.md)：所有细节：语法，选项，钩子，结果及其错误，消息，扩展，书籍，HTML，排版，KaTeX，高亮显示和API。
-   [`test/spec/`](https://github.com/banana-space/banana/tree/main/packages/bananamark/test/spec)一致性示例，它是方言的规范，保存在存储库中（不在NPM包中）。
-   [CHANGELOG.md](https://github.com/banana-space/banana/blob/main/packages/bananamark/CHANGELOG.md)：每个版本都有什么变化。

## 状态

-   0.2版。在1.0之前，一个小版本（0.3）可能会改变接口和规范描述的HTML；补丁版本（0.2.1）没有。三个软件包一起发布，版本相同； `bananamark-codemirror` 和 `bananamark-tikz` 采取 `bananamark` 作为同一次要版本的对等依赖。
-   节点22及以后版本；从2023年开始的浏览器（样式表需要） `:has()`）。
-   仅限ES模块。还没有TypeScript类型。
-   麻省理工学院的执照。

## 贡献

测试，规范的示例以及如何更新它们：参见 [CONTRIBUTING.md](https://github.com/banana-space/banana/blob/main/packages/CONTRIBUTING.md).

## 常见问题

### bananamark 是什么？

用于数学写作的Markdown方言：公式，编号章节和定理，交叉引用，参考书目，维基链接和中文排版，呈现为HTML

### 如何安装 bananamark？

在项目目录运行 npm install bananamark，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@lezer/common（^1\.5\.3）、@lezer/markdown（^1\.8\.0）、@lezer/highlight（^1\.2\.5）、@codemirror/language（^6\.13\.1）、@codemirror/lang-yaml（^6\.1\.3）、@codemirror/lang-markdown（^6\.5\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 bananamark，可以用 npx bananamark 直接运行。

### bananamark 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bananamark 是否存在。

### bananamark 支持 ESM 还是 CommonJS？

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

### bananamark 需要什么版本的 Node\.js？

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

### bananamark 可以商用吗？

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

### bananamark 还在维护吗？

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