markdown-to-html

Name: markdown-to-html
Author: github

github.com/github文档处理40.5k9.9k 次安装1 天前更新

代码仓库

关于 markdown-to-html

markdown-to-html 是将 Markdown 转为 HTML 并指导编写自定义转换脚本的技能，面向开发者和文档作者，涵盖 marked.js、pandoc、gomarkdown 及静态站点工作流。

主要功能

01将 Markdown 文件转换为 HTML
02处理单文件和批量转换
03配置 marked.js 和 pandoc
04使用 Go Markdown 解析器与 Jekyll
05处理净化与渲染问题

适用场景

01从 Markdown 生成 HTML 文档
02预览渲染后的 Markdown
03基于 Markdown 构建静态站点
04为自定义工具选择转换工作流

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/github/awesome-copilot --skill markdown-to-html

安装后在 Claude Code 中输入/markdown-to-html确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

basic-markdown-to-html.md

code-blocks-to-html.md

collapsed-sections-to-html.md

collapsed-sections.md

code-blocks.md

gomarkdown.md

jekyll.md

marked.md

hugo.md

basic-markdown.md

tables-to-html.md

tables.md

pandoc.md

writing-mathematical-expressions-to-html.md

writing-mathematical-expressions.md

详细介绍

Markdown 转 HTML 转换

使用 marked.js 库将 Markdown 文档转换为 HTML 的专家技能，或编写数据转换脚本；在这种情况下，脚本类似于 markedJS/marked 仓库。对于自定义脚本，知识不仅限于 marked.js，还利用 pandoc 和 gomarkdown/markdown 等工具的数据转换方法；jekyll/jekyll 和 gohugoio/hugo 用于模板系统。

转换脚本或工具应处理单个文件、批量转换和高级配置。

何时使用此技能

用户要求"将 markdown 转换为 html"或"转换 md 文件"
用户希望将"渲染 markdown"作为 HTML 输出
用户需要从 .md 文件生成 HTML 文档
用户正在从 Markdown 内容构建静态站点
用户正在构建将 markdown 转换为 html 的模板系统
用户正在为现有模板系统开发工具、小部件或自定义模板
用户希望预览渲染为 HTML 的 Markdown

将 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>&lt;p&gt;paragraph tag&lt;/p&gt;</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>
    ```

数学表达式转换

    ```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><mn>2</mn></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><mn>2</mn></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（用于命令行或编程用法）
为命令行全局安装 marked：npm install -g marked
或本地安装：npm install marked

快速转换方法

见 marked.md 快速转换方法

分步工作流

见 marked.md 分步工作流

命令行配置

使用配置文件

创建 ~/.marked.json 以持久化选项：

{
  "gfm": true,
  "breaks": true
}

或使用自定义配置：

marked -i input.md -o output.html -c config.json

命令行选项参考

选项	描述
`-i, --input <file>`	输入 Markdown 文件
`-o, --output <file>`	输出 HTML 文件
`-s, --string <string>`	解析字符串而非文件
`-c, --config <file>`	使用自定义配置文件
`--gfm`	启用 GitHub Flavored Markdown
`--breaks`	将换行转换为 `<br>`
`--help`	显示所有选项

安全警告

⚠️ Marked 不会清理输出的 HTML。 对于不受信任的输入，请使用清理器：

import { marked } from 'marked';
import DOMPurify from 'dompurify';

const unsafeHtml = marked.parse(untrustedMarkdown);
const safeHtml = DOMPurify.sanitize(unsafeHtml);

推荐的清理器：

支持的 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 清理输出

使用 `pandoc`

前置要求

已安装 Pandoc（从 https://pandoc.org/installing.html 下载）
如需 PDF 输出：需安装 LaTeX（macOS 上为 MacTeX，Windows 上为 MiKTeX，Linux 上为 texlive）
可访问终端/命令提示符

快速转换方法

方法 1：命令行基本转换

# Convert markdown to HTML
pandoc input.md -o output.html

# Convert with standalone document (includes header/footer)
pandoc input.md -s -o output.html

# Explicit format specification
pandoc input.md -f markdown -t html -s -o output.html

方法 2：过滤模式（交互式）

# Start pandoc as a filter
pandoc

# Type markdown, then Ctrl-D (Linux/macOS) or Ctrl-Z+Enter (Windows)
Hello *pandoc*!
# Output: <p>Hello <em>pandoc</em>!</p>

方法 3：格式转换

# HTML to Markdown
pandoc -f html -t markdown input.html -o output.md

# Markdown to LaTeX
pandoc input.md -s -o output.tex

# Markdown to PDF (requires LaTeX)
pandoc input.md -s -o output.pdf

# Markdown to Word
pandoc input.md -s -o output.docx

命令行配置

选项	描述
`-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 输出进行清理

# Run in sandbox mode for untrusted input
pandoc --sandbox input.md -o output.html

支持的 Markdown 风格

风格	支持情况
Pandoc Markdown	100%（原生）
CommonMark	完整（使用 `-f commonmark`）
GitHub Flavored Markdown	完整（使用 `-f gfm`）
MultiMarkdown	部分支持

故障排查

问题	解决方案
PDF 生成失败	安装 LaTeX（MacTeX、MiKTeX 或 texlive）
Windows 上出现编码问题	在使用 pandoc 前运行 `chcp 65001`
缺少独立文档页眉	添加 `-s` 标志以生成完整文档
数学公式未渲染	使用 `--mathml` 或 `--mathjax` 选项
表格未渲染	确保使用竖线和短横线的正确表格语法

使用 `gomarkdown/markdown`

前置要求

已安装 Go 1.18 或更高版本
安装该库：go get github.com/gomarkdown/markdown
如需命令行工具：go install github.com/gomarkdown/mdtohtml@latest

快速转换方法

方法 1：简单转换（Go）

package main

import (
    "fmt"
    "github.com/gomarkdown/markdown"
)

func main() {
    md := []byte("# Hello World\n\nThis is **bold** text.")
    html := markdown.ToHTML(md, nil, nil)
    fmt.Println(string(html))
}

方法 2：命令行工具

# Install mdtohtml
go install github.com/gomarkdown/mdtohtml@latest

# Convert file
mdtohtml input.md output.html

# Convert file (output to stdout)
mdtohtml input.md

方法 3：自定义解析器和渲染器

package main

import (
    "github.com/gomarkdown/markdown"
    "github.com/gomarkdown/markdown/html"
    "github.com/gomarkdown/markdown/parser"
)

func mdToHTML(md []byte) []byte {
    // Create parser with extensions
    extensions := parser.CommonExtensions | parser.AutoHeadingIDs | parser.NoEmptyLineBeforeBlock
    p := parser.NewWithExtensions(extensions)
    doc := p.Parse(md)

    // Create HTML renderer with extensions
    htmlFlags := html.CommonFlags | html.HrefTargetBlank
    opts := html.RendererOptions{Flags: htmlFlags}
    renderer := html.NewRenderer(opts)

    return markdown.Render(doc, renderer)
}

命令行配置

mdtohtml 命令行工具的选项很少：

mdtohtml input-file [output-file]

如需高级配置，可通过编程方式使用 Go 库，并设置解析器和渲染器选项：

解析器扩展	描述
`parser.CommonExtensions`	表格、围栏代码、自动链接、删除线等
`parser.AutoHeadingIDs`	为标题生成 ID
`parser.NoEmptyLineBeforeBlock`	块之前无需空行
`parser.MathJax`	对 LaTeX 数学公式的 MathJax 支持

HTML 标志	描述
`html.CommonFlags`	常用 HTML 输出标志
`html.HrefTargetBlank`	为链接添加 `target="_blank"`
`html.CompletePage`	生成完整的 HTML 页面
`html.UseXHTML`	生成 XHTML 输出

安全警告

⚠️ gomarkdown 不会清理输出的 HTML。 对于不受信任的输入，请使用 Bluemonday：

import (
    "github.com/microcosm-cc/bluemonday"
    "github.com/gomarkdown/markdown"
)

maybeUnsafeHTML := markdown.ToHTML(md, nil, nil)
html := bluemonday.UGCPolicy().SanitizeBytes(maybeUnsafeHTML)

推荐的清理工具：Bluemonday

支持的 Markdown 风格

风格	支持情况
原始 Markdown	100%
CommonMark	高（带扩展）
GitHub Flavored Markdown	高（表格、围栏代码、删除线）
MathJax/LaTeX 数学公式	通过扩展支持
Mmark	支持

故障排查

问题	解决方案
Windows/Mac 换行符未被解析	使用 `parser.NormalizeNewlines(input)`
表格未渲染	启用 `parser.Tables` 扩展
代码块没有高亮	集成 Chroma 等语法高亮工具
数学公式未渲染	启用 `parser.MathJax` 扩展
XSS 漏洞	使用 Bluemonday 清理输出

使用 `jekyll`

前置条件

Ruby 2.7.0 或更高版本
RubyGems
GCC 和 Make（用于原生扩展）
安装 Jekyll 和 Bundler：gem install jekyll bundler

快速转换方法

方法 1：创建新站点

# Create a new Jekyll site
jekyll new myblog

# Change to site directory
cd myblog

# Build and serve locally
bundle exec jekyll serve

# Access at http://localhost:4000

方法 2：构建静态站点

# Build site to _site directory
bundle exec jekyll build

# Build with production environment
JEKYLL_ENV=production bundle exec jekyll build

方法 3：实时重载开发

# Serve with live reload
bundle exec jekyll serve --livereload

# Serve with drafts
bundle exec jekyll serve --drafts

命令行配置

命令	描述
`jekyll new <path>`	创建新的 Jekyll 站点
`jekyll build`	将站点构建到 `_site` 目录
`jekyll serve`	构建并在本地提供服务
`jekyll clean`	删除生成的文件
`jekyll doctor`	检查配置问题

服务选项	描述
`--livereload`	文件变更时重新加载浏览器
`--drafts`	包含草稿文章
`--port <port>`	设置服务端口（默认：4000）
`--host <host>`	设置服务主机（默认：localhost）
`--baseurl <url>`	设置基础 URL

安全警告

⚠️ Jekyll 安全注意事项：

生产环境中避免使用 safe: false
在 _config.yml 中使用 exclude 防止敏感文件被发布
如果接受外部输入，请对用户生成的内容进行清理
保持 Jekyll 和插件更新

# _config.yml security settings
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor

支持的 Markdown 风格

风格	支持情况
Kramdown（默认）	100%
CommonMark	通过插件（jekyll-commonmark）
GitHub Flavored Markdown	通过插件（jekyll-commonmark-ghpages）
RedCarpet	通过插件（已弃用）

在 _config.yml 中配置 Markdown 处理器：

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

故障排除

问题	解决方案
Ruby 3.0+ 无法提供服务	运行 `bundle add webrick`
Gem 依赖错误	运行 `bundle install`
构建缓慢	使用 `--incremental` 标志
Liquid 语法错误	检查内容中未转义的 `{`
插件未加载	添加到 `_config.yml` 插件列表

使用 `hugo`

前置条件

已安装 Hugo（从 https://gohugo.io/installation/ 下载）
Git（推荐用于主题和模块）
Go（可选，用于 Hugo Modules）

快速转换方法

方法 1：创建新站点

# Create a new Hugo site
hugo new site mysite

# Change to site directory
cd mysite

# Add a theme
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml

# Create content
hugo new content posts/my-first-post.md

# Start development server
hugo server -D

方法 2：构建静态站点

# Build site to public directory
hugo

# Build with minification
hugo --minify

# Build for specific environment
hugo --environment production

方法 3：开发服务器

# Start server with drafts
hugo server -D

# Start with live reload and bind to all interfaces
hugo server --bind 0.0.0.0 --baseURL http://localhost:1313/

# Start with specific port
hugo server --port 8080

命令行配置

命令	描述
`hugo new site <name>`	创建新的 Hugo 站点
`hugo new content <path>`	创建新的内容文件
`hugo`	将站点构建到 `public` 目录
`hugo server`	启动开发服务器
`hugo mod init`	初始化 Hugo Modules

构建选项	描述
`-D, --buildDrafts`	包含草稿内容
`-E, --buildExpired`	包含已过期内容
`-F, --buildFuture`	包含未来日期的内容
`--minify`	压缩输出
`--gc`	构建后运行垃圾回收
`-d, --destination <path>`	输出目录

服务选项	描述
`--bind <ip>`	绑定的接口
`-p, --port <port>`	端口号（默认：1313）
`--liveReloadPort <port>`	实时重载端口
`--disableLiveReload`	禁用实时重载
`--navigateToChanged`	导航到已更改的内容

安全警告

⚠️ Hugo 安全注意事项：

在 hugo.toml 中为外部命令配置安全策略
在公共仓库中谨慎使用 --enableGitInfo
验证用户生成内容的短代码参数

# hugo.toml security settings
[security]
  enableInlineShortcodes = false
  [security.exec]
    allow = ['^go$', '^npx$', '^postcss$']
  [security.funcs]
    getenv = ['^HUGO_', '^CI$']
  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

支持的 Markdown 风格

风格	支持情况
Goldmark（默认）	100%（兼容 CommonMark）
GitHub Flavored Markdown	完整支持（表格、删除线、自动链接）
CommonMark	100%
Blackfriday（旧版）	已弃用，不推荐

在 hugo.toml 中配置 Markdown：

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
    [markup.goldmark.renderer]
      unsafe = false  # Set true to allow raw HTML

疑难解答

问题	解决方案
路径上出现“页面未找到”	检查配置中的 `baseURL`
主题未加载	验证 `themes/` 或 Hugo Modules 中的主题
构建缓慢	使用 `--templateMetrics` 识别瓶颈
原始 HTML 未渲染	在 goldmark 配置中设置 `unsafe = true`
图片未加载	检查 `static/` 文件夹结构
模块错误	运行 `hugo mod tidy`

参考资料

支持 Markdown

登录后评论

基本信息

作者: github
仓库: github/awesome-copilot
分类: 文档处理
安装次数: 9,907
GitHub Stars: 40,516

报告问题

markdown-to-html

关于 markdown-to-html

主要功能

适用场景

安装

包含的文件

详细介绍

Markdown 转 HTML 转换

何时使用此技能

将 Markdown 转换为 HTML

基本基础转换

代码块转换

折叠区段转换

数学表达式转换

表格转换

使用 markedJS/marked

先决条件

快速转换方法

分步工作流

命令行配置

使用配置文件

命令行选项参考

安全警告

支持的 Markdown 风格

故障排除

使用 pandoc

前置要求

快速转换方法

方法 1：命令行基本转换

方法 2：过滤模式（交互式）

方法 3：格式转换

命令行配置

安全警告

支持的 Markdown 风格

故障排查

使用 gomarkdown/markdown

前置要求

快速转换方法

方法 1：简单转换（Go）

方法 2：命令行工具

方法 3：自定义解析器和渲染器

命令行配置

安全警告

支持的 Markdown 风格

故障排查

使用 jekyll

前置条件

快速转换方法

方法 1：创建新站点

方法 2：构建静态站点

方法 3：实时重载开发

命令行配置

安全警告

支持的 Markdown 风格

故障排除

使用 hugo

前置条件

快速转换方法

方法 1：创建新站点

方法 2：构建静态站点

方法 3：开发服务器

命令行配置

安全警告

支持的 Markdown 风格

疑难解答

参考资料

编写和设置 Markdown 样式

markedJS/marked

pandoc

gomarkdown/markdown

jekyll

hugo

评论

使用 `markedJS/marked`

使用 `pandoc`

使用 `gomarkdown/markdown`

使用 `jekyll`

使用 `hugo`

`markedJS/marked`

`pandoc`

`gomarkdown/markdown`

`jekyll`

`hugo`