mcpField
M
markdown-to-html

markdown-to-html

github.com/githubドキュメント40.5k9.9k 回インストール今日更新
リポジトリ

markdown-to-html について

markdown-to-htmlは、MarkdownをHTMLに変換し、独自の変換スクリプト作成を案内するスキルです。開発者や文書作成者向けに、marked.js、pandoc、gomarkdown、静的サイトの作業手順を扱います。

主な機能

  1. 01MarkdownファイルからHTMLへの変換
  2. 02単一ファイルと一括変換
  3. 03marked.jsとpandocの設定
  4. 04GoのMarkdownパーサーとJekyllの利用
  5. 05サニタイズと描画問題への対処

活用シーン

  1. 01MarkdownからHTML文書を生成
  2. 02描画したMarkdownのプレビュー
  3. 03Markdownを使った静的サイト構築
  4. 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 に変換するテンプレートシステムを構築している場合
  • ユーザーが既存のテンプレートシステム用のツール、ウィジェット、またはカスタムテンプレートに取り組んでいる場合
  • ユーザーが 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 またはプログラムによる使用の場合)
  • CLI 用に marked をグローバルにインストール: 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 オプションリファレンス
オプション説明
-i, --input <file>入力 Markdown ファイル
-o, --output <file>出力 HTML ファイル
-s, --string <string>ファイルの代わりに文字列を解析
-c, --config <file>カスタム構成ファイルを使用
--gfmGitHub 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 フレーバー
フレーバーサポート
オリジナル Markdown100%
CommonMark 0.3198%
GitHub Flavored Markdown97%
トラブルシューティング
問題解決策
ファイル先頭の特殊文字ゼロ幅文字を削除: 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 による基本的な変換
# 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
CLI の設定
オプション説明
-f, --from <format>入力フォーマット (markdown、html、latex など)
-t, --to <format>出力フォーマット (html、latex、pdf、docx など)
-s, --standaloneヘッダー/フッター付きの単独ドキュメントを生成
-o, --output <file>出力ファイル (拡張子から推測)
--mathmlTeX 数式を 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 Markdown100% (ネイティブ)
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 ツール
# 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)
}
CLI の設定

mdtohtml CLI ツールには最小限のオプションしかありません:

mdtohtml input-file [output-file]

高度な設定を行うには、パーサーとレンダラーのオプションを指定して Go ライブラリをプログラムから使用します:

パーサー拡張説明
parser.CommonExtensionsテーブル、フェンス付きコード、自動リンク、取り消し線など
parser.AutoHeadingIDs見出しの ID を生成
parser.NoEmptyLineBeforeBlockブロックの前に空行を必要としない
parser.MathJaxLaTeX 数式の MathJax サポート
HTML フラグ説明
html.CommonFlags一般的な HTML 出力フラグ
html.HrefTargetBlankリンクに target="_blank" を追加
html.CompletePage完全な HTML ページを生成
html.UseXHTMLXHTML 出力を生成
セキュリティに関する警告

⚠️ 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 フレーバー
フレーバーサポート
オリジナル Markdown100%
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: 新しいサイトを作成する
# 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
CLI 設定
コマンド説明
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 の plugins リストに追加する

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
CLI 設定
コマンド説明
hugo new site <name>新しい Hugo サイトを作成する
hugo new content <path>新しいコンテンツファイルを作成する
hugopublic ディレクトリにサイトをビルドする
hugo server開発サーバーを起動する
hugo mod initHugo 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完全対応(テーブル、取り消し線、自動リンク)
CommonMark100%
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
トラブルシューティング
問題解決策
パスで「Page not found」が表示される設定の baseURL を確認してください
テーマが読み込まれないthemes/ または Hugo Modules のテーマを確認してください
ビルドが遅い--templateMetrics を使用してボトルネックを特定してください
生の HTML がレンダリングされないgoldmark 設定で unsafe = true を設定してください
画像が読み込まれないstatic/ フォルダーの構成を確認してください
モジュールエラーhugo mod tidy を実行してください

参考資料

Markdown の記述とスタイリング
markedJS/marked
pandoc
gomarkdown/markdown
jekyll
hugo

コメント