markdown-to-html

name: markdown-to-html description: '將 Markdown 檔案轉換為 HTML，類似於 marked.js、pandoc、gomarkdown/markdown 或類似工具；或是編寫自定義指令稿來將 Markdown 轉換為 HTML，以及/或者在 jekyll/jekyll、gohugoio/hugo 或類似的使用 Markdown 文件並將其轉換為 HTML 輸出的網頁模板系統上工作。當被要求「將 markdown 轉換為 html」、「將 md 轉換為 html」、「渲染 markdown」、「從 markdown 產生 html」，或者在處理 .md 檔案以及/或者將 markdown 轉換為 HTML 輸出的網頁模板系統時使用。支援 GFM、CommonMark 和標準 Markdown 版本的 CLI 和 Node.js 工作流。'

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
    # 第一級標題
    ## 第二級標題

    包含[連結](https://example.com)的句子，以及像 `<p>段落標籤</p>` 這樣的 HTML 片段。

    - `ul` 清單項目 1
    - `ul` 清單項目 2

    1. `ol` 清單項目 1
    2. `ol` 清單項目 1

    | 表格項目 | 描述 |
    | 一 | 一是數字 `1` 的拼法。 |
    | 二 | 二是數字 `2` 的拼法。 |

    ```js
    var one = 1;
    var two = 2;

    function simpleMath(x, y) {
     return x + y;
    }
    console.log(simpleMath(one, two));
    ```
    ```

    ```html
    <h1>第一級標題</h1>
    <h2>第二級標題</h2>

    <p>包含 <a href="https://example.com">連結</a> 的句子，以及像 <code>&lt;p&gt;段落標籤&lt;/p&gt;</code> 這樣的 HTML 片段。</p>

    <ul>
     <li>`ul` 清單項目 1</li>
     <li>`ul` 清單項目 2</li>
    </ul>

    <ol>
     <li>`ol` 清單項目 1</li>
     <li>`ol` 清單項目 2</li>
    </ol>

    <table>
     <thead>
      <tr>
       <th>表格項目</th>
       <th>描述</th>
      </tr>
     </thead>
     <tbody>
      <tr>
       <td>一</td>
       <td>一是數字 `1` 的拼法。</td>
      </tr>
      <tr>
       <td>二</td>
       <td>二是數字 `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
    在此輸入您的程式碼
    ```

    ```html
    <pre><code class="language-md">
    在此輸入您的程式碼
    </code></pre>
    ```

    ```js
    console.log("Hello world");
    ```

    ```html
    <pre><code class="language-js">
    console.log("Hello world");
    </code></pre>
    ```

    ```markdown
      ```

      ```
      可見的反引號
      ```

      ```
    ```

    ```html
      <pre><code>
      ```

      可見的反引號

      ```
      </code></pre>
    ```

摺疊區塊轉換

更多資訊請參閱 collapsed-sections-to-html.md

    ```markdown
    <details>
    <summary>更多資訊</summary>

    ### 內部的標題

    - 清單
    - **格式設定**
    - 程式碼區塊

        ```js
        console.log("Hello");
        ```

    </details>
    ```

    ```html
    <details>
    <summary>更多資訊</summary>

    <h3>內部的標題</h3>

    <ul>
     <li>清單</li>
     <li><strong>格式設定</strong></li>
     <li>程式碼區塊</li>
    </ul>

    <pre>
     <code class="language-js">console.log("Hello");</code>
    </pre>

    </details>
    ```

數學運算式轉換

更多資訊請參閱 writing-mathematical-expressions-to-html.md

    ```markdown
    此句子使用 `$` 分隔符號來顯示行內數學運算式：$\\sqrt{3x-1}+(1+x)^2$
    ```

    ```html
    <p>此句子使用 <code>$</code> 分隔符號來顯示行內數學運算式：
     <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
    **柯西-史瓦茲不等式**\
    $$\\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>柯西-史瓦茲不等式</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
    | 第一個標題  | 第二個標題 |
    | ------------- | ------------- |
    | 內容儲存格  | 內容儲存格  |
    | 內容儲存格  | 內容儲存格  |
    ```

    ```html
    <table>
     <thead><tr><th>第一個標題</th><th>第二個標題</th></tr></thead>
     <tbody>
      <tr><td>內容儲存格</td><td>內容儲存格</td></tr>
      <tr><td>內容儲存格</td><td>內容儲存格</td></tr>
     </tbody>
    </table>
    ```

    ```markdown
    | 左對齊 | 置中對齊 | 右對齊 |
    | :---         |     :---:      |          ---: |
    | git status   | git status     | git status    |
    | git diff     | git diff       | git diff      |
    ```

    ```html
    <table>
      <thead>
       <tr>
        <th align="left">左對齊</th>
        <th align="center">置中對齊</th>
        <th align="right">右對齊</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 或程式化使用)
• 全域安裝 marked 用於 CLI：npm install -g marked
• 或本地安裝：npm install marked

快速轉換方法

請參閱 marked.md 快速轉換方法

逐步工作流

請參閱 marked.md 逐步工作流

CLI 配置

使用配置檔案

建立 ~/.marked.json 用於持久性選項：

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

或使用自定義配置：

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

CLI 選項參考

安全警告

⚠️ Marked 不會消毒輸出 HTML。 對於不受信任的輸入，請使用消毒劑：

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

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

建議的消毒劑：

• DOMPurify (建議)
• sanitize-html
• js-xss

支援的 Markdown 版本

疑難排解

使用 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

# 轉換為獨立文件 (包含頁首/頁尾)
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+Enter (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 配置

安全警告

⚠️ Pandoc 會忠實地處理輸入。 轉換不受信任的 markdown 時：

• 使用 --sandbox 模式停用外部檔案存取
• 在處理前驗證輸入
• 如果在瀏覽器中顯示，請消毒 HTML 輸出

# 對於不受信任的輸入，在沙盒模式下執行
pandoc --sandbox input.md -o output.html

支援的 Markdown 版本

疑難排解

使用 gomarkdown/markdown

先決條件

• 已安裝 Go 1.18 或更高版本
• 安裝函式庫：go get github.com/gomarkdown/markdown
• 用於 CLI 工具：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：CLI 工具

# 安裝 mdtohtml
go install github.com/gomarkdown/mdtohtml@latest

# 轉換檔案
mdtohtml input.md output.html

# 轉換檔案 (輸出到標準輸出 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 {
    // 建立帶有擴充功能的解析器
    extensions := parser.CommonExtensions | parser.AutoHeadingIDs | parser.NoEmptyLineBeforeBlock
    p := parser.NewWithExtensions(extensions)
    doc := p.Parse(md)

    // 建立帶有擴充功能的 HTML 渲染器
    htmlFlags := html.CommonFlags | html.HrefTargetBlank
    opts := html.RendererOptions{Flags: htmlFlags}
    renderer := html.NewRenderer(opts)

    return markdown.Render(doc, renderer)
}

CLI 配置

mdtohtml CLI 工具的選項很少：

mdtohtml 輸入檔案 [輸出檔案]

對於進階配置，請以程式化方式搭配解析器和渲染器選項使用 Go 函式庫：

安全警告

⚠️ 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 版本

疑難排解

使用 jekyll

先決條件

• Ruby 版本 2.7.0 或更高
• RubyGems
• GCC 和 Make (用於原生擴充功能)
• 安裝 Jekyll 和 Bundler：gem install jekyll bundler

快速轉換方法

方法 1：建立新網站

# 建立新的 Jekyll 網站
jekyll new myblog

# 切換到網站目錄
cd myblog

# 在本地建構並提供服務
bundle exec jekyll serve

# 存取路徑為 http://localhost:4000

方法 2：建構靜態網站

# 將網站建構到 _site 目錄
bundle exec jekyll build

# 在生產環境中建構
JEKYLL_ENV=production bundle exec jekyll build

方法 3：即時重新載入開發

# 包含即時重新載入功能提供服務
bundle exec jekyll serve --livereload

# 包含草稿提供服務
bundle exec jekyll serve --drafts

CLI 配置

安全警告

⚠️ Jekyll 安全考量事項：

• 避免在生產環境中使用 safe: false
• 在 _config.yml 中使用 exclude 防止敏感檔案被發佈
• 如果接受外部輸入，請消毒使用者產生的內容
• 保持 Jekyll 和外掛程式更新

# _config.yml 安全設定
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor

支援的 Markdown 版本

在 _config.yml 中配置 markdown 處理器：

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

疑難排解

使用 hugo

先決條件

• 已安裝 Hugo (從 https://gohugo.io/installation/ 下載)
• Git (建議用於佈景主題和模組)
• Go (選用，用於 Hugo Modules)

快速轉換方法

方法 1：建立新網站

# 建立新的 Hugo 網站
hugo new site mysite

# 切換到網站目錄
cd mysite

# 新增佈景主題
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml

# 建立內容
hugo new content posts/my-first-post.md

# 啟動開發伺服器
hugo server -D

方法 2：建構靜態網站

# 將網站建構到 public 目錄
hugo

# 包含縮減功能進行建構
hugo --minify

# 針對特定環境進行建構
hugo --environment production

方法 3：開發伺服器

# 包含草稿啟動伺服器
hugo server -D

# 啟動包含即時重新載入的伺服器，並繫結到所有介面
hugo server --bind 0.0.0.0 --baseURL http://localhost:1313/

# 使用特定連接埠啟動
hugo server --port 8080

CLI 配置

安全警告

⚠️ Hugo 安全考量事項：

• 在 hugo.toml 中為外部指令配置安全原則
• 對公共套件庫謹慎使用 --enableGitInfo
• 驗證使用者產生內容的 shortcode 參數

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

支援的 Markdown 版本

在 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  # 設定為 true 以允許原始 HTML

疑難排解

參考資料

編寫和設定 Markdown 樣式

• basic-markdown.md
• code-blocks.md
• collapsed-sections.md
• tables.md
• writing-mathematical-expressions.md
• Markdown 指南：https://www.markdownguide.org/basic-syntax/
• 設定 Markdown 樣式：https://github.com/sindresorhus/github-markdown-css

markedJS/marked

• 官方文件：https://marked.js.org/
• 進階選項：https://marked.js.org/using_advanced
• 擴充性：https://marked.js.org/using_pro
• GitHub 套件庫：https://github.com/markedjs/marked

pandoc

• 入門：https://pandoc.org/getting-started.html
• 官方文件：https://pandoc.org/MANUAL.html
• 擴充性：https://pandoc.org/extras.html
• GitHub 套件庫：https://github.com/jgm/pandoc

gomarkdown/markdown

• 官方文件：https://pkg.go.dev/github.com/gomarkdown/markdown
• 進階配置：https://pkg.go.dev/github.com/gomarkdown/markdown@v0.0.0-20250810172220-2e2c11897d1a/html
• Markdown 處理：https://blog.kowalczyk.info/article/cxn3/advanced-markdown-processing-in-go.html
• GitHub 套件庫：https://github.com/gomarkdown/markdown

jekyll

• 官方文件：https://jekyllrb.com/docs/
• 配置選項：https://jekyllrb.com/docs/configuration/options/
• 外掛程式：https://jekyllrb.com/docs/plugins/
  • 安裝
  • 產生器 (Generators)
  • 轉換器 (Converters)
  • 指令
  • 標籤 (Tags)
  • 篩選器
  • 掛鉤 (Hooks)
• GitHub 套件庫：https://github.com/jekyll/jekyll

hugo

• 官方文件：https://gohugo.io/documentation/
• 所有設定：https://gohugo.io/configuration/all/
• 編輯器外掛程式：https://gohugo.io/tools/editors/
• GitHub 套件庫：https://github.com/gohugoio/hugo