IT 技書の森

Markdown

プレーンテキストで記述し、HTML に変換できる軽量マークアップ言語

ドキュメントデータ形式

Markdown とは

Markdown は、John Gruber が 2004 年に開発した軽量マークアップ言語で、プレーンテキストで記述した文書を HTML に変換できる。GitHub の README、技術ブログ、ドキュメントサイト、チャットツール (Slack, Discord) で広く使われている。

記法がシンプルで、特別なエディタなしにテキストエディタで読み書きできる。HTML を直接書くより圧倒的に速く、プレーンテキストの状態でも読みやすい。

主要な記法

# 見出し 1
## 見出し 2
### 見出し 3

**太字** *斜体* ~~取り消し線~~ `インラインコード`

- 箇条書き
- 箇条書き
  - ネスト

1. 番号付きリスト
2. 番号付きリスト

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

> 引用ブロック

| 列 1 | 列 2 | 列 3 |
|------|------|------|
| A    | B    | C    |

Markdown の方言

オリジナルの Markdown は仕様が曖昧で、実装ごとに挙動が異なる問題があった。これを解決するために複数の拡張仕様が生まれた。

方言 特徴 使われる場所
CommonMark 厳密な仕様、曖昧さを排除 多くのパーサーの基盤
GFM (GitHub Flavored) テーブル、タスクリスト、自動リンク GitHub
MDX JSX コンポーネントを埋め込み可能 Next.js、Docusaurus

MDX: Markdown + React

MDX は Markdown 内に React コンポーネントを埋め込める拡張で、Next.js や Docusaurus などの技術ドキュメントサイトで広く使われている。

静的サイトジェネレーターとの連携

Markdown は静的サイトジェネレーター (Next.js, Astro, Hugo, Gatsby) のコンテンツソースとして使われる。YAML frontmatter でメタデータを記述し、本文を Markdown で書く。

---
title: "記事タイトル"
publishedDate: "2025-06-01"
tags: ["JavaScript", "TypeScript"]
---

## 本文

ここから記事の本文が始まる。

Markdown が適さないケース

  • 複雑なレイアウト (多段組み、フロート) → HTML/CSS
  • 構造化データ → JSON, YAML
  • リッチなインタラクション → MDX or カスタムコンポーネント
  • 印刷用の文書 → LaTeX, Word

さらに掘り下げるなら関連書籍が参考になる。

関連用語