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 に変換するテンプレートシステムを構築している場合
• ユーザーが既存のテンプレートシステムのツール、ウィジェット、またはカスタムテンプレートで作業している場合
• ユーザーが 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>&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>
    ```

数式変換

詳細については 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><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 がインストールされていること
• 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 は出力 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 フレーバー

フレーバー	サポート
Original 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: 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 設定

オプション	説明
-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 出力をサニタイズ

# 信頼されていない入力に対してサンドボックスモードで実行
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
• 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 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 フレーバー

フレーバー	サポート
Original Markdown	100%
CommonMark	高い (拡張機能付き)
GitHub Flavored Markdown	高い (テーブル、フェンスコード、打消し線)
MathJax/LaTeX Math	拡張機能でサポート
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: 新しいサイトを作成

# 新しい 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 new <path>	新しい Jekyll サイトを作成
jekyll build	_site ディレクトリにサイトをビルド
jekyll serve	ビルドしてローカルで提供
jekyll clean	生成されたファイルを削除
jekyll doctor	設定の問題をチェック

Serve オプション	説明
--livereload	変更時にブラウザをリロード
--drafts	ドラフト投稿を含める
--port <port>	サーバーポートを設定 (デフォルト: 4000)
--host <host>	サーバーホストを設定 (デフォルト: localhost)
--baseurl <url>	ベース URL を設定

セキュリティに関する警告

⚠️ Jekyll セキュリティに関する考慮事項:

• プロダクション環境で safe: false を使用しないでください
• _config.yml で exclude を使用して、機密ファイルが公開されないようにします
• 外部入力を受け入れる場合は、ユーザー生成コンテンツをサニタイズ
• Jekyll とプラグインを更新し続ける

# _config.yml セキュリティ設定
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: 新しいサイトを作成

# 新しい 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 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>	出力ディレクトリ

Server オプション	説明
--bind <ip>	バインドするインターフェース
-p, --port <port>	ポート番号 (デフォルト: 1313)
--liveReloadPort <port>	ライブリロードポート
--disableLiveReload	ライブリロードを無効化
--navigateToChanged	変更されたコンテンツに移動

セキュリティに関する警告

⚠️ Hugo セキュリティに関する考慮事項:

• 外部コマンドの実行ポリシーを hugo.toml で設定
• --enableGitInfo をパブリックリポジトリで慎重に使用
• ユーザー生成コンテンツのショートコードパラメーターを検証

# hugo.toml セキュリティ設定
[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  # raw HTML を許可する場合は true に設定

トラブルシューティング

問題	解決方法
パスで「ページが見つかりません」	設定で baseURL を確認
テーマが読み込まれない	テーマが themes/ または Hugo Modules にあることを確認
ビルドが遅い	--templateMetrics を使用してボトルネックを特定
raw HTML がレンダリングされない	goldmark 設定で unsafe = true を設定
画像が読み込まれない	static/ フォルダー構造を確認
モジュールエラー	hugo mod tidy を実行

参照

Markdown の記述とスタイリング

• basic-markdown.md
• code-blocks.md
• collapsed-sections.md
• tables.md
• writing-mathematical-expressions.md
• Markdown Guide: 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/
  • インストール
  • ジェネレータ
  • コンバーター
  • コマンド
  • タグ
  • フィルター
  • フック
• 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