# html-to-md

> A JS library for convert HTML to markdown, gzip 10kb

Latest version **0.8.8** (published 2025-04-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install html-to-md
pnpm add html-to-md
yarn add html-to-md
bun add html-to-md
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.8.8 |
| Published | 2025-04-27 |
| First published | 2019-06-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 483.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 160 |
| Author | stonehank |
| Maintainers | stonehank |
| Keywords | html2md, html2markdown, htmlToMarkdown, parseHtml, markdown, html |

## Links

- npm: https://www.npmjs.com/package/html-to-md
- Repository: https://github.com/stonehank/html-to-md
- Homepage: https://github.com/stonehank/html-to-md#README
- Issues: https://github.com/stonehank/html-to-md/issues
- npm.io page: https://npm.io/package/html-to-md

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 0.8.8 (latest) — 2025-04-27
- 0.8.7 — 2025-03-31
- 0.8.6 — 2024-09-02
- 0.8.5 — 2024-01-07
- 0.8.4 — 2023-11-12
- 0.8.3 — 2022-12-04
- 0.8.2 — 2022-11-27
- 0.8.1 — 2022-11-27
- 0.8.0 — 2022-10-16
- 0.7.0 — 2022-10-10
- 0.6.1 — 2022-10-05
- 0.6.0 — 2022-07-24
- 0.5.9 — 2022-07-24
- 0.5.8 — 2022-05-04
- 0.5.7 — 2022-02-06
- … 23 more at https://npm.io/package/html-to-md/versions

## README

> 一个用于转换`HTML`为`Markdown`的工具。[English](./README-EN.md)

---

[![Build Status](https://travis-ci.org/stonehank/html-to-md.svg?branch=master)](https://travis-ci.org/stonehank/html-to-md)
[![npm](https://img.shields.io/npm/v/html-to-md.svg)](https://www.npmjs.com/package/html-to-md)
[![codecov](https://codecov.io/gh/stonehank/html-to-md/branch/master/graph/badge.svg)](https://codecov.io/gh/stonehank/html-to-md)
![npm bundle size](https://img.shields.io/bundlephobia/minzip/html-to-md.svg)
![](https://img.shields.io/badge/dependencies-0-brightgreen)

### 特点

- 快速，小巧，无任何依赖，`gzip` 10kb

- 支持`nodeJS`，参数(html 文本)为字符串

- 200+单元测试和模块测试，覆盖率`97%`

> 注意：只有有效规范的 HTML 文本才能准确显示结果，如`<p>abc<` ，`<i>abc</>`等都是**无效**文本

### 效果

[live-demo](https://stonehank.github.io/html-to-md/)

### 为什么做这个工具

最初的动机是希望将`leetcode-cn`上的题目和自己的解答[搬到`github`](https://github.com/stonehank/leetcode-solution-js)，
但是获取的介绍都是`html`格式文本，因此有了将`html`转换为`markdown`的需求。

找了几个工具，结果并不是很合胃口，有的不支持`nodejs`，有的并不能很好的转换，最终决定自己写一个来用。

刚开始只是写了一个比较简单的，但已经能够处理我的需求。

但后来偶尔一次使用，面对更复杂的`html`格式，就会出现混乱，这个库也就是一个重构版，
当然，它可能还存在很多`bug`没有发现，但希望能在后续不断完善，如果有发现`bug`，请提`issue`或`PR`，我会第一时间进行处理。

### 使用说明

##### 安装

`npm -i html-to-md`

##### 使用

```js
const html2md = require('html-to-md')
// or if you're using ES6
import html2md from 'html-to-md'

console.log(
  html2md('<strong><em>strong and italic</em></strong>', options, force)
)
// ***strong and italic***
```

### 参数(可选)：

#### options:

<table>
<thead>
<tr>
<th align="center">名称</th>
<th align="center">数据类型</th>
<th align="center">默认值</th>
<th align="center">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">skipTags</td>
<td align="center">Array</td>
<td align="left"><pre>
<code>[
  'div',
  'html',
  'body',
  'nav',
  'section',
  'footer',
  'main',
  'aside',
  'article',
  'header'
]</code></pre></td>
<td align="center">需要忽略的标签名</td>
</tr>
<tr>
<td align="center">emptyTags</td>
<td align="center">Array</td>
<td align="center"><code>[]</code></td>
<td align="center">不仅忽略它本身，它内部所有标签名全部忽略</td>
</tr>
<tr>
<td align="center">ignoreTags</td>
<td align="center">Array</td>
<td align="left">
<pre>
<code>[
  '',
  'style',
  'head',
  '!doctype',
  'form',
  'svg',
  'noscript',
  'script',
  'meta'
]</code></pre></td>
<td align="center">忽视标签及其内部所有内容</td>
</tr>
<tr>
<td align="center">aliasTags</td>
<td align="center">Object</td>
<td align="left">
  <pre>
<code>{
  figure :'p',
  figcaption:'p',
  dl:'p', 
  dd:'p', 
  dt:'p'
}</code></pre></td>
<td align="center">为标签定义一个别名(通常作用于一些不常用标签)</td>
</tr>
<tr>
<td align="center">renderCustomTags</td>
<td align="left">&nbsp;&nbsp;<code>Boolean</code> <br>|<code>'SKIP'</code> <br>|<code>'EMPTY'</code> <br>|<code>'IGNORE'</code></td>
<td align="center">
<code>true</code></td>
<td align="left">定义是否渲染自定义标签（非HTML标签），
<ul>
<li><code>true</code>：渲染</li>
<li><code>false | SKIP</code>：添加至<code>skipTags</code></li>
<li><code>EMPTY</code>：添加至<code>emptyTags</code></li>
<li><code>IGNORE</code>：添加至<code>ignoreTags</code></li>
</ul>
</td>
</tr>
<tr>
<td align="center">tagListener</td>
<td align="left">Function</td>
<td align="center">
(tagName: String, props: <a href="#TagListenerProps">TagListenerProps</a>): <a href="#TagListenerReturnProps">TagListenerReturnProps</a> => props
</td>
<td align="left">自定义当前标签部分属性配置</td>
</tr>
</tbody>
</table>

> 优先权：skipTags > emptyTags > ignoreTags > aliasTags

例：

```javascript
html2md('<><b><i>abc</i></b></>', { ignoreTags: [''] })
// ''

html2md('<><b><i>abc</i></b></>', { skipTags: [''] })
// ***abc***

html2md('<><b><i>abc</i></b></>', { emptyTags: [''] })
// abc

html2md('<><b><i>abc</i></b></>', {
  skipTags: [''],
  aliasTags: { b: 'ul', i: 'li' },
})
// *  abc

html2md('<test><b><i>abc</i></b></test>', { renderCustomTags: 'SKIP' })
// ***abc***
```

#### force(Boolean)(默认 false)

|  值   |                说明                 |
| :---: | :---------------------------------: |
| true  |       表示强制使用自定义配置        |
| false | 对自定义配置使用`Object.assign`操作 |

例：

```javascript
// 默认 skipTags 为 ['div','html','body']

// 配置一：
html2md('<div><b><i>abc</i></b></div>', { skipTags: ['b'] }, false)
// skipTags 为 ['div','html','body','b']

// 配置二：
html2md('<div><b><i>abc</i></b></div>', { skipTags: ['b'] }, true)
// 经过配置后 skipTags 为 ['b']
```

#### TagListenerProps

| key           | 说明                                                              |
| ------------- | ----------------------------------------------------------------- |
| parentTag     | 父标签名，没有则为 null                                           |
| prevTagName   | 上一个标签名，没有则为 null                                       |
| nextTagName   | 下一个标签名，没有则为 null                                       |
| isFirstSubTag | 是否当前父标签内部的第一个子标签                                  |
| attrs         | 当前标签的 attributes，以 object 集合方式，例如 { src, href ... } |
| innerHTML     | 内部 HTML 字符串                                                  |
| match         | 当前的 HTML 对应 Markdown 的匹配符号                              |
| language?     | 当前标签语言，只在 pre 标签中出现                                 |
| isSelfClosing | 是否自闭和标签                                                    |

#### TagListenerReturnProps

| key       | 说明                                                              |
| --------- | ----------------------------------------------------------------- |
| attrs     | 当前标签的 attributes，以 object 集合方式，例如 { src, href ... } |
| match     | 返回一个新的自定义匹配符号                                        |
| language? | 返回自定义 pre 标签的 language                                    |

### 支持标签

- `a`
- `b`
- `blockquote`
- `code`
- `del`
- `em`
- `h1~h6`
- `hr`
- `i`
- `img`
- `input`
- `li`
- `ol`
- `p`
- `pre`
- `s`
- `strong`
- `table`
- `tbody`
- `td`
- `th`
- `thead`
- `tr`
- `ul`

---
_Source: https://npm.io/package/html-to-md · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._