Markdown から HTML への変換完全ガイド：構文の基礎から高度な組版テクニックまで

ドキュメント

なぜ Markdown を使うのか？

Markdown は技術ドキュメントの事実上の標準です。GitHub、Stack Overflow、Notion、VS Code がネイティブでサポートしています。

比較 Markdown Word HTML
学習コスト 低い 中 高い
バージョン管理 ✅ プレーンテキスト ❌ バイナリ ✅ プレーンテキスト
可読性 ✅ ソースがそのまま読める ❌ ❌
表現力 中（拡張で強化） 強い 強い
レンダリングの一貫性 中 ❌ プラットフォームで異なる ✅

基本構文チートシート

見出し

# 見出し 1
## 見出し 2
### 見出し 3
#### 見出し 4
##### 見出し 5
###### 見出し 6

強調

**太字**      → <strong>太字</strong>
*斜体*        → <em>斜体</em>
~~取り消し線~~  → <del>取り消し線</del>
`インラインコード`  → <code>インラインコード</code>

リスト

- 順序なしリスト項目 1
- 順序なしリスト項目 2
  - ネスト項目

1. 順序付きリスト項目 1
2. 順序付きリスト項目 2
   1. ネストされた順序付き項目

- [ ] タスク（未完了）
- [x] タスク（完了）

リンクと画像

[リンクテキスト](https://example.com)
[タイトル付きリンク](https://example.com "タイトル")
![画像の代替テキスト](image.png)
![タイトル付き画像](image.png "画像タイトル")

引用と水平線

> 引用テキスト
> > ネストされた引用

---

GFM 拡張構文

表

| 左寄せ | 中央揃え | 右寄せ |
|:-------|:--------:|-------:|
| 内容   | 内容     | 内容   |
| 長い内容 | 短い   | 中程度 |

レンダリング結果：

左寄せ 中央揃え 右寄せ
内容 内容 内容
長い内容 短い 中程度

タスクリスト

- [x] 要件分析
- [x] 技術設計
- [ ] 実装
- [ ] テストと受け入れ

フェンス付きコードブロック

```javascript
function hello() {
  console.log('Hello, Markdown!');
}
```

```python
def hello():
    print("Hello, Markdown!")
```

脚注

これは本文[^1]で、もう 1 つの段落[^note]があります。

[^1]: 最初の脚注の内容。
[^note]: カスタム ID の脚注。

高度な組版テクニック

1. 数式（KaTeX/MathJax）

インライン数式：$E = mc^2$

ブロック数式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

行列：
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$

2. Mermaid 図

```mermaid
graph TD
    A[ユーザーリクエスト] --> B{認証チェック}
    B -->|認証済み| C[データ取得]
    B -->|未認証| D[401 を返す]
    C --> E[ページをレンダリング]
```

サポートされる図の種類：

種類 構文キーワード 用途
フローチャート graph 業務フロー、決定木
シーケンス図 sequenceDiagram API 呼び出し、インタラクション
クラス図 classDiagram オブジェクト指向設計
ステート図 stateDiagram 状態マシン
ガントチャート gantt プロジェクトスケジュール
円グラフ pie データの割合

3. 目次（TOC）

<!-- 目次を自動生成 -->
[[toc]]

<!-- または手動で -->
- [インストール](#インストール)
- [設定](#設定)
- [使い方](#使い方)

4. 定義リスト

用語 1
: 定義 1

用語 2
: 定義 2

5. 略語

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

HTML は W3C が策定した標準です。

ツールボックスで Markdown を変換する

操作手順

  1. Markdown エディターを開く
  2. 左側の編集エリアに Markdown を入力
  3. 右側で HTML のレンダリング結果をリアルタイムプレビュー
  4. 「ソース」モードに切り替えて生成された HTML を確認可能
  5. HTML ファイルとしてエクスポート可能

サポートされる拡張

拡張 説明 例
GFM 表、タスクリスト、脚注 GitHub スタイル
数式 KaTeX レンダリング $E=mc^2$
Mermaid 図のレンダリング フローチャート、シーケンス図
シンタックスハイライト Prism.js/highlight.js コードブロックの色付け
Emoji :smile: → 😄 ショートコード置換

Markdown から HTML への変換の仕組み

パースの流れ

Markdown テキスト
  ↓
字句解析（Lexer）→ トークンストリーム
  ↓
構文解析（Parser）→ AST（抽象構文木）
  ↓
レンダラー（Renderer）→ HTML 文字列

主要なパースライブラリ

ライブラリ 言語 特徴 サイズ
marked JS 最速・最も人気 40KB
markdown-it JS プラグインが豊富で拡張可能 60KB
remark JS AST エコシステム、MDX の基盤 100KB+
CommonMark JS 厳密な標準準拠 50KB
pulldown-cmark Rust 究極のパフォーマンス WASM 200KB

marked の基本的な使い方

import { marked } from 'marked';

const html = marked.parse('# Hello **Markdown**');
// <h1>Hello <strong>Markdown</strong></h1>

markdown-it + プラグイン

import MarkdownIt from 'markdown-it';
import mk from 'markdown-it-mark';
import footnote from 'markdown-it-footnote';
import tasklist from 'markdown-it-task-lists';

const md = new MarkdownIt({ html: true, linkify: true })
  .use(mk)
  .use(footnote)
  .use(tasklist);

const result = md.render('# Hello Markdown');

MDX：Markdown + JSX

MDX を使うと、Markdown の中で React コンポーネントを利用できます：

---
title: "私の記事"
---

import { Chart } from './components/Chart';
import { Callout } from './components/Callout';

# データ分析レポート

<Callout type="warning">
  以下のデータは 2026 年 Q1 のサンプリングに基づきます。
</Callout>

## ユーザー増加の傾向

<Chart data={growthData} type="line" />

| 月   | ユーザー数 | 増加率 |
|------|-----------|--------|
| 1月  | 10,000    | -      |
| 2月  | 12,500    | 25%    |
| 3月  | 15,000    | 20%    |

ベストプラクティス

1. ファイル構成

docs/
├── getting-started.md
├── configuration.md
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

2. 執筆ルール

  • 1 行 1 文：Git diff に優しく、変更のレビューがしやすい
  • 見出しレベルを飛ばさない：H1 → H2 → H3。H1 → H3 は避ける
  • コードブロックに言語を指定：````javascript` と書き、````` だけにしない
  • 参照式リンクを使う：長文では [テキスト][ref] が [テキスト](url) よりすっきりする
  • 画像に代替テキストを付ける：![説明](画像) でアクセシビリティ向上

3. Lint ツール

# markdownlint をインストール
npm install -g markdownlint-cli

# チェック
markdownlint docs/**/*.md

# 自動修正
markdownlint docs/**/*.md --fix

よくある質問

Markdown 内の HTML が効かない？

一部のパーサーはデフォルトで生の HTML を無効にしています。html: true オプションを有効にしてください。

表でセル結合ができない？

標準の Markdown 表はセル結合をサポートしていません。必要な場合は HTML の表を使います：

<table>
  <tr>
    <th>名前</th>
    <th>説明</th>
  </tr>
  <tr>
    <td rowspan="2">プロジェクト A</td>
    <td>サブ項目 1</td>
  </tr>
  <tr>
    <td>サブ項目 2</td>
  </tr>
</table>

コードブロック内の Markdown 構文がパースされる？

より多くのバッククォートでネストします：

````markdown
```javascript
console.log('外側ではパースされない');
```


---

## まとめ

Markdown は技術文書作成に最適なフォーマットです。簡潔で、バージョン管理ができ、エコシステムも豊富。基本構文 + GFM 拡張 + 数式 + Mermaid 図をマスターすれば、プロレベルの技術ドキュメントを書けます。ツールボックスの [Markdown エディター](/ja/utils/markdown)はリアルタイムプレビューとエクスポートに対応し、組版ではなく内容に集中できます。
#Markdown#HTML转换#文档编写#排版#教程