markdown-to-html
热门将 Markdown 文件转换为 HTML，类似于 `marked.js`、`pandoc`、`gomarkdown/markdown` 等工具；或编写自定义脚本将 Markdown 转为 HTML；亦或在使用 `jekyll/jekyll`、`gohugoio/hugo` 等将 Markdown 转换为 HTML 的网页模板系统时使用。当用户要求“将 markdown 转为 html”、“把 md 转成 html”、“渲染 markdown”、“从 markdown 生成 html”，或者处理 .md 文件以及基于 Markdown 的网页模板系统时，均可触发此 Skill。支持 CLI 和 Node.js 工作流，兼容 GFM、CommonMark 及标准 Markdown 语法。
3.6万Star
0Fork
更新于 2026/7/11
SKILL.md
只读
名称
markdown-to-html
描述
将 Markdown 文件转换为 HTML，类似于 `marked.js`、`pandoc`、`gomarkdown/markdown` 等工具；或编写自定义脚本将 Markdown 转为 HTML；亦或在使用 `jekyll/jekyll`、`gohugoio/hugo` 等将 Markdown 转换为 HTML 的网页模板系统时使用。当用户要求“将 markdown 转为 html”、“把 md 转成 html”、“渲染 markdown”、“从 markdown 生成 html”，或者处理 .md 文件以及基于 Markdown 的网页模板系统时，均可触发此 Skill。支持 CLI 和 Node.js 工作流，兼容 GFM、CommonMark 及标准 Markdown 语法。
Markdown 转换为 HTML
用于将 Markdown 文档转换为 HTML 的专家级 Skill。支持使用 marked.js 库，或编写数据转换脚本（如类似于 markedJS/marked 的脚本）。对于自定义脚本，相关知识并不局限于 marked.js，还涵盖了从 pandoc 和 gomarkdown/markdown 借鉴的数据转换方法，以及 jekyll/jekyll 和 gohugoio/hugo 等模板系统的应用。
无论是转换脚本还是工具，都应支持单文件转换、批量转换以及高级配置。
何时使用此 Skill
- 用户要求“将 markdown 转换为 html”或“转换 md 文件”
- 用户希望将 Markdown“渲染”为 HTML 输出
- 用户需要从 .md 文件生成 HTML 文档
- 用户正基于 Markdown 内容构建静态网站
- 用户正在构建将 Markdown 转换为 HTML 的模板系统
- 用户正在为现有的模板系统开发工具、挂件（widget）或自定义模板
- 用户想要预览 Markdown 渲染后的 HTML 效果
将 Markdown 转换为 HTML
基础转换示例
更多详情请参阅 basic-markdown-to-html.md
```markdown
# Level 1
## Level 2
One sentence with a [link](https://example.com), and a HTML snippet like `<p>paragraph tag</p>`.
- `ul` list item 1
- `ul` list item 2
1. `ol` list item 1
2. `ol` list item 1
| Table Item | Description |
| One | One is the spelling of the number `1`. |
| Two | Two is the spelling of the number `2`. |
```js
var one = 1;
var two = 2;
function simpleMath(x, y) {
return x + y;
}
console.log(simpleMath(one, two));
```
```
```html
<h1>Level 1</h1>
<h2>Level 2</h2>
<p>One sentence with a <a href="https://example.com">link</a>, and a HTML snippet like <code><p>paragraph tag</p></code>.</p>
<ul>
<li>`ul` list item 1</li>
<li>`ul` list item 2</li>
</ul>
<ol>
<li>`ol` list item 1</li>
<li>`ol` list item 2</li>
</ol>
<table>
<thead>
<tr>
<th>Table Item</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>One</td>
<td>One is the spelling of the number `1`.</td>
</tr>
<tr>
<td>Two</td>
<td>Two is the spelling of the number `2`.</td>
</tr>
</tbody>
</table>
<pre>
<code>var one = 1;
var two = 2;
function simpleMath(x, y) {
return x + y;
}
console.log(simpleMath(one, two));</code>
</pre>
```
代码块转换示例
更多详情请参阅 code-blocks-to-html.md
```markdown
your code here
```
```html
<pre><code class="language-md">
your code here
</code></pre>
```
```js
console.log("Hello world");
```
```html
<pre><code class="language-js">
console.log("Hello world");
</code></pre>
```
```markdown
```
```
visible backticks
```
```
```
```html
<pre><code>
```
visible backticks
```
</code></pre>
```
折叠区域转换示例
更多详情请参阅 collapsed-sections-to-html.md
```markdown
<details>
<summary>More info</summary>
### Header inside
- Lists
- **Formatting**
- Code blocks
```js
console.log("Hello");
```
</details>
```
```html
<details>
<summary>More info</summary>
<h3>Header inside</h3>
<ul>
<li>Lists</li>
<li><strong>Formatting</strong></li>
<li>Code blocks</li>
</ul>
<pre>
<code class="language-js">console.log("Hello");</code>
</pre>
</details>
```
数学公式转换示例
更多详情请参阅 writing-mathematical-expressions-to-html.md
```markdown
This sentence uses `$` delimiters to show math inline: $\sqrt{3x-1}+(1+x)^2$
```
```html
<p>This sentence uses <code>$</code> delimiters to show math inline:
<math-renderer><math xmlns="http://www.w3.org/1998/Math/MathML">
<msqrt><mn>3</mn><mi>x</mi><mo>−</mo><mn>1</mn></msqrt>
<mo>+</mo><mo>(</mo><mn>1</mn><mo>+</mo><mi>x</mi>
<msup><mo>)</mo><mn>2</mn></msup>
</math>
</math-renderer>
</p>
```
```markdown
**The Cauchy-Schwarz Inequality**\
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
```
```html
<p><strong>The Cauchy-Schwarz Inequality</strong><br>
<math-renderer>
<math xmlns="http://www.w3.org/1998/Math/MathML">
<msup>
<mrow><mo>(</mo>
<munderover><mo data-mjx-texclass="OP">∑</mo>
<mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow><mi>n</mi>
</munderover>
<msub><mi>a</mi><mi>k</mi></msub>
<msub><mi>b</mi><mi>k</mi></msub>
<mo>)</mo>
</mrow>
<mn>2</mn>
</msup>
<mo>≤</mo>
<mrow><mo>(</mo>
<munderover><mo>∑</mo>
<mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow>
<mi>n</mi>
</munderover>
<msubsup><mi>a</mi><mi>k</mi><2</msubsup>
<mo>)</mo>
</mrow>
<mrow><mo>(</mo>
<munderover><mo>∑</mo>
<mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow>
<mi>n</mi>
</munderover>
<msubsup><mi>b</mi><mi>k</mi><2</msubsup>
<mo>)</mo>
</mrow>
</math>
</math-renderer></p>
```
表格转换示例
更多详情请参阅 tables-to-html.md
```markdown
| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
```
```html
<table>
<thead><tr><th>First Header</th><th>Second Header</th></tr></thead>
<tbody>
<tr><td>Content Cell</td><td>Content Cell</td></tr>
<tr><td>Content Cell</td><td>Content Cell</td></tr>
</tbody>
</table>
```
```markdown
| Left-aligned | Center-aligned | Right-aligned |
| :--- | :---: | ---: |
| git status | git status | git status |
| git diff | git diff | git diff |
```
```html
<table>
<thead>
<tr>
<th align="left">Left-aligned</th>
<th align="center">Center-aligned</th>
<th align="right">Right-aligned</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">git status</td>
<td align="center">git status</td>
<td align="right">git status</td>
</tr>
<tr>
<td align="left">git diff</td>
<td align="center">git diff</td>
<td align="right">git diff</td>
</tr>
</tbody>
</table>
```
使用 markedJS/marked
前置条件
- 已安装 Node.js（用于 CLI 或代码调用）
- CLI 全局安装 marked：
npm install -g marked - 或局部安装：
npm install marked
快速转换方法
参阅 marked.md 的 Quick Conversion Methods 章节
分步工作流
参阅 marked.md 的 Step-by-Step Workflows 章节
CLI 配置
使用配置文件
创建 ~/.marked.json 以配置持久化选项：
{
"gfm": true,
"breaks": true
}
或者使用自定义配置文件：
marked -i input.md -o output.html -c config.json
CLI 参数选项说明
| 参数选项 | 说明 |
|---|---|
-i, --input <file> |
输入的 Markdown 文件 |
-o, --output <file> |
输出的 HTML 文件 |
-s, --string <string> |
解析字符串而非文件 |
-c, --config <file> |
使用自定义配置文件 |
--gfm |
启用 GitHub Flavored Markdown |
--breaks |
将换行符转换为 <br> |
--help |
显示所有参数选项 |
安全警告
⚠️ Marked 不会自动过滤/净化（sanitize）输出的 HTML。 如果处理不可信的输入，请配合 HTML 净化工具使用：
import { marked } from 'marked';
import DOMPurify from 'dompurify';
const unsafeHtml = marked.parse(untrustedMarkdown);
const safeHtml = DOMPurify.sanitize(unsafeHtml);
推荐的 HTML 净化工具：
支持的 Markdown 变体/规范
| 规范 / 变体 | 支持度 |
|---|---|
| 原生 Markdown | 100% |
| CommonMark 0.31 | 98% |
| GitHub Flavored Markdown | 97% |
常见问题排查与解决
| 问题表现 | 解决办法 |
|---|---|
| 文件开头存在特殊字符/乱码 | 过滤零宽字符：content.replace(/^[\u200B\u200C\u200D\uFEFF]/,"") |
| 代码块没有高亮显示 | 引入 highlight.js 等语法高亮库 |
| 表格未正常渲染 | 确保配置中开启了 gfm: true |
| 换行符被忽略 | 在配置中设置 breaks: true |
| 担心 XSS 漏洞安全风险 | 使用 DOMPurify 对输出的 HTML 进行净化处理 |
使用 pandoc
前置条件
- 已安装 Pandoc（下载地址：https://pandoc.org/installing.html）
- 如需导出 PDF：需安装 LaTeX 环境（macOS 推荐 MacTeX，Windows 推荐 MiKTeX，Linux 推荐 texlive）
- 可正常使用终端 / 命令提示符
快速转换方法
方法 1：CLI 基础转换
# 将 Markdown 转换为 HTML
pandoc input.md -o output.html
# 转换为独立 HTML 文档（包含完整的 header/footer 标签）
pandoc input.md -s -o output.html
# 显式指定输入与输出格式
pandoc input.md -f markdown -t html -s -o output.html
方法 2：管道/过滤模式（交互式）
# 启动 Pandoc 过滤器
pandoc
# 输入 Markdown，然后按 Ctrl-D (Linux/macOS) 或 Ctrl-Z+回车 (Windows) 提交
Hello *pandoc*!
# 输出结果：<p>Hello <em>pandoc</em>!</p>
方法 3：多格式互相转换
# HTML 转 Markdown
pandoc -f html -t markdown input.html -o output.md
# Markdown 转 LaTeX
pandoc input.md -s -o output.tex
# Markdown 转 PDF（依赖 LaTeX 环境）
pandoc input.md -s -o output.pdf
# Markdown 转 Word
pandoc input.md -s -o output.docx
CLI 参数选项说明
| 参数选项 | 说明 |
|---|---|
-f, --from <format> |
输入格式（markdown、html、latex 等） |
-t, --to <format> |
输出格式（html、latex、pdf、docx 等） |
-s, --standalone |
生成独立的完整文档（包含完整的页头页尾结构） |
-o, --output <file> |
输出文件路径（可根据扩展名自动推导格式） |
--mathml |
将 TeX 数学公式转换为 MathML |
--metadata title="Title" |
设置文档元数据 |
--toc |
自动生成目录表 |
--template <file> |
使用自定义模板 |
--help |
显示所有参数选项 |
安全警告
⚠️ Pandoc 会忠实地解析输入内容。 当处理来源不可信的 Markdown 时：
- 使用
--sandbox沙箱模式来禁止访问外部文件系统 - 在解析前校验输入内容
- 如果要在网页中展示，请对生成的 HTML 进行净化（sanitize）
