Turndown

使用 JavaScript 将 HTML 转换为 Markdown。

项目更新

to-markdown 已更名为 Turndown。详情请参阅迁移指南。
Turndown 仓库的 URL 已更改为 https://github.com/mixmark-io/turndown。

安装

npm:

npm install turndown

浏览器:

<script src="https://unpkg.com/turndown/dist/turndown.js"></script>

对于 RequireJS 使用，UMD 版本位于 lib/turndown.umd.js（用于 Node.js）和 lib/turndown.browser.umd.js（用于浏览器）。这些文件在发布 npm 包时生成。要手动生成它们，请克隆此仓库并运行 npm run build。

使用方法

// 对于 Node.js
var TurndownService = require('turndown')

var turndownService = new TurndownService()
var markdown = turndownService.turndown('<h1>Hello world!</h1>')

Turndown 也接受 DOM 节点作为输入（元素节点、文档节点或文档片段节点）：

var markdown = turndownService.turndown(document.getElementById('content'))

选项

可以在实例化时将选项传递给构造函数。例如：

var turndownService = new TurndownService({ option: 'value' })

选项	有效值	默认值
`headingStyle`	`setext` 或 `atx`	`setext`
`hr`	任何主题分隔符	`* * *`
`bulletListMarker`	`-`、`+` 或 `*`	`*`
`codeBlockStyle`	`indented` 或 `fenced`	`indented`
`fence`	``` 或 `~~~`	```
`emDelimiter`	`_` 或 `*`	`_`
`strongDelimiter`	`**` 或 `__`	`**`
`linkStyle`	`inlined` 或 `referenced`	`inlined`
`linkReferenceStyle`	`full`、`collapsed` 或 `shortcut`	`full`
`preformattedCode`	`false` 或 `true`	`false`

高级选项

选项	有效值	默认值
`blankReplacement`	规则替换函数	见下方特殊规则
`keepReplacement`	规则替换函数	见下方特殊规则
`defaultReplacement`	规则替换函数	见下方特殊规则

方法

`addRule(key, rule)`

key 参数是规则的唯一名称，便于引用。例如：

turndownService.addRule('strikethrough', {
  filter: ['del', 's', 'strike'],
  replacement: function (content) {
    return '~' + content + '~'
  }
})

addRule 返回 TurndownService 实例以支持链式调用。

详见下方的扩展规则。

`keep(filter)`

确定哪些元素应该保留并以 HTML 形式呈现。默认情况下，Turndown 不保留任何元素。filter 参数的工作方式类似于规则过滤器（见下方过滤器部分）。例如：

turndownService.keep(['del', 'ins'])
turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello <del>world</del><ins>World</ins>'

这将使 <del> 和 <ins> 元素在转换时以 HTML 形式呈现。

keep 可以多次调用，新添加的保留过滤器优先级高于旧的。保留过滤器会被标准 CommonMark 规则和任何添加的规则覆盖。要保留通常由这些规则处理的元素，请添加一个具有所需行为的规则。

keep 返回 TurndownService 实例以支持链式调用。

`remove(filter)`

确定哪些元素应该完全移除，即转换为空字符串。默认情况下，Turndown 不移除任何元素。filter 参数的工作方式类似于规则过滤器（见下方过滤器部分）。例如：

turndownService.remove('del')
turndownService.turndown('<p>Hello <del>world</del><ins>World</ins></p>') // 'Hello World'

这将移除 <del> 元素（及其内容）。

remove 可以多次调用，新添加的移除过滤器优先级高于旧的。移除过滤器会被保留过滤器、标准 CommonMark 规则和任何添加的规则覆盖。要移除通常由这些规则处理的元素，请添加一个具有所需行为的规则。

remove 返回 TurndownService 实例以支持链式调用。

`use(plugin|array)`

使用插件或插件数组。例如：

// 从 turndown-plugin-gfm 导入插件
var turndownPluginGfm = require('turndown-plugin-gfm')
var gfm = turndownPluginGfm.gfm
var tables = turndownPluginGfm.tables
var strikethrough = turndownPluginGfm.strikethrough

// 使用 gfm 插件
turndownService.use(gfm)

// 仅使用表格和删除线插件 turndownService.use([tables, strikethrough])


`use` 方法返回 `TurndownService` 实例，可以用于链式调用。

详见下文的**插件**部分。

## 通过规则扩展

Turndown 可以通过添加**规则**来扩展功能。规则是一个包含 `filter` 和 `replacement` 属性的普通 JavaScript 对象。例如，用于转换 `<p>` 元素的规则如下：

```js
{
  filter: 'p',
  replacement: function (content) {
    return '\n\n' + content + '\n\n'
  }
}

过滤器选择 <p> 元素，替换函数返回用两个换行符分隔的 <p> 内容。

`filter` 字符串|数组|函数

filter 属性决定是否应该用规则的 replacement 替换元素。可以简单地使用标签名或标签名数组来选择 DOM 节点：

filter: 'p' 将选择 <p> 元素
filter: ['em', 'i'] 将选择 <em> 或 <i> 元素

filter 属性中的标签名应为小写，无论它们在文档中的形式如何。

或者，filter 可以是一个函数，根据给定节点是否应被替换返回布尔值。该函数接收一个 DOM 节点和 TurndownService 选项作为参数。例如，以下规则在 linkStyle 选项为 inlined 时选择 <a> 元素（带有 href）：

filter: function (node, options) {
  return (
    options.linkStyle === 'inlined' &&
    node.nodeName === 'A' &&
    node.getAttribute('href')
  )
}

`replacement` 函数

replacement 函数决定如何转换元素。它应该返回给定节点的 Markdown 字符串。该函数接收节点内容、节点本身和 TurndownService 选项作为参数。

以下规则展示了如何转换 <em> 元素：

rules.emphasis = {
  filter: ['em', 'i'],

  replacement: function (content, node, options) {
    return options.emDelimiter + content + options.emDelimiter
  }
}

特殊规则

空白规则决定如何处理空白元素。它会覆盖所有规则（甚至通过 addRule 添加的规则）。如果一个节点只包含空白字符，并且不是 <a>、<td>、<th> 或空元素，则该节点被视为空白。可以使用 blankReplacement 选项自定义其行为。

保留规则决定如何处理不应转换的元素，即在 Markdown 输出中以 HTML 形式呈现的元素。默认情况下，不保留任何元素。块级元素将用空行与周围内容分隔。可以使用 keepReplacement 选项自定义其行为。

删除规则决定完全删除哪些元素。默认情况下，不删除任何元素。

默认规则处理其他规则无法识别的节点。默认情况下，它输出节点的文本内容（如果是块级元素，则用空行分隔）。可以使用 defaultReplacement 选项自定义其行为。

规则优先级

Turndown 遍历规则集，并选择第一个匹配 filter 的规则。以下列表描述了优先级顺序：

空白规则
添加的规则（可选）
Commonmark 规则
保留规则
删除规则
默认规则

插件

插件 API 为开发者提供了一种方便的方式来应用多个扩展。插件只是一个以 TurndownService 实例为参数的函数。

转义 Markdown 字符

Turndown 使用反斜杠（\）来转义 HTML 输入中的 Markdown 字符。这确保在将输出重新编译为 HTML 时，这些字符不会被解释为 Markdown。例如，<h1>1. Hello world</h1> 的内容需要转义为 1\. Hello world，否则它将被解释为列表项而不是标题。

为了避免将每个 HTML 元素的内容解析为 Markdown 的复杂性和性能影响，Turndown 使用一组正则表达式来转义潜在的 Markdown 语法。因此，转义规则可能相当激进。