前言
在前端开发中，文档的输出和协作是很重要的一环。而 Confluence 是企业中使用较多的的在线文档协作平台之一，而 markdown 是一种格式简单、易学易写的文档格式，并且与 GitHub 等工具具有天然的结合优势，因此我们常常会使用 markdown 作为自己工作中的常用文档形式。然而将 markdown 文档转换为 Confluence 文档需要两者之间的转换，此时我们可以使用 markdown-confluence-converter 这个 npm 包来实现这个转换的过程。
安装
我们首先需要通过 npm 安装 markdown-confluence-converter 这个 npm 包。
npm install markdown-confluence-converter
使用
安装完成后，我们可以通过 require 或 import 的方式引入这个 npm 包，并使用它提供的转换函数进行 markdown 和 Confluence 文档之间的转换。
示例代码
-- -------------------- ---- ------- -- -- --- - ----- - ------------- ------------ - - ----------------------------------------- -- -------- ---- ----- ------------ - - - --- ----------- ------------------ - -------- -- --- - ---- - ---- --- --- -- ---- -- ---- - --- - --- - --- - - --- - --- - --- - - - - - - - - - - - - - - - ---------------- ---------------------- ------ -- -- - -------- --- ---------- -- ----- -------------- - ----------------------------------------- ----------------------------展开代码
API 说明
markdown-confluence-converter 提供了两个函数，分别用于将 markdown 转换为 Confluence 格式，和将 Confluence 格式转换为 markdown 格式。
fromMarkdown(markdownText: string, options?: MarkdownOptions): Node
将 markdown 文本转换成 Confluence 文档的抽象语法树（AST）。
参数：
markdownText：要转换的 markdown 文本。options：选项对象，具体可以设置文档转换的转换方式，不设置采用默认值。支持的选项项见下方表格。
返回值：
- 转换后的 Confluence AST。
toConfluence(confluenceAst: Node, options?: ConfluenceOptions): string
将 Confluence 文档的 AST 转换为字符串。
参数：
confluenceAst：要转换的 Confluence AST。options：选项对象，具体可以设置文档转换的转换方式，不设置采用默认值。支持的选项项见下方表格。
返回值：
- 转换后的 Confluence 文本。
选项对象
MarkdownOptions:
| 名称 | 类型 | 描述 |
|---|---|---|
| gfm | boolean | 是否启用 GFM（GitHub Flavored Markdown）模式。默认值为 true，即启用。 |
| tables | boolean | 是否支持表格。默认值为 true，即启用。 |
| breaks | boolean | 是否支持换行符。默认值为 false。 |
| pedantic | boolean | 是否启用警告模式。默认值为 false。 |
| sanitize | boolean | 是否启用 XSS 过滤。默认值为 false。 |
| toc | boolean | 是否支持自动生成目录。默认值为 false。 |
| mangle | boolean | 是否启用名称压缩。默认值为 false。 |
| smartLists | boolean | 是否启用智能列表。默认值为 true。 |
| smartypants | boolean | 是否启用智能引号和破折号。默认值为 false。 |
ConfluenceOptions:
| 名称 | 类型 | 描述 |
|---|---|---|
| topLevelElement | string | 顶层元素的名称。默认为 body，其他可取值有 cell, fieldset, and table。 |
| gfm | boolean | 是否启用 GFM（GitHub Flavored Markdown）模式。默认值为 true，即启用。 |
| encodeHtmlEntities | boolean | 是否将 HTML 实体编码为文本。默认值为 true。 |
| suffix | string | 用于添加到每个块的结尾的字符串。默认为 ''。 |
| blockRules | { [...] } | 定义每个场景下将如何处理每个块级元素的数组。默认为标准 Markdown 规则。 |
| inlineRules | { [...] } | 定义每个场景下将如何处理每个行级元素的数组。默认为标准 Markdown 规则。 |
| slugify | (s: string) => string | 定义以 URL 友好方式处理锚点名称的函数。默认为 slugify。 |
总结
通过使用 markdown-confluence-converter，我们可以很方便地将 markdown 文档转换为 Confluence 文档进行上传和协作。同时，通过合理地设置选项对象，还可以实现一些更加多样化的转换方式。这个 npm 包在项目中有着广泛的使用场景，建议开发者们还是要多学习多使用。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055ae181e8991b448d887e
