GitHubのREADMEを書くとき、Notionでドキュメントを作るとき、Zennやdev.toで記事を投稿するとき、共通して使われているのがMarkdownという記法です。# 見出し と書くと大きな見出しになり、**太字** と書くと太字になる、あの書き方のことです。
HTMLを書かなくても構造化されたドキュメントが作れる、それがMarkdownの魅力です。この記事では、Markdownの基本的な記法と実際の活用例を一通り紹介します。
Markdownとは？
Markdownは、2004年にJohn Gruberが作った軽量マークアップ言語です。プレーンテキストで書けて、HTMLに変換できるのが特徴です。「読みやすいプレーンテキストでドキュメントを書いて、必要に応じてHTMLに変換する」というコンセプトで設計されています。
たとえば、HTMLで見出しを書くと <h1>タイトル</h1> と書く必要がありますが、Markdownでは # タイトル の一行だけです。同じ構造をはるかにシンプルに表現できます。
基本記法一覧
| 記法 | Markdown | 変換後のHTML |
|---|---|---|
| 見出し | # 見出し1〜###### 見出し6 |
<h1>〜<h6> |
| 太字 | **テキスト** |
<strong>テキスト</strong> |
| 斜体 | *テキスト* |
<em>テキスト</em> |
| インラインコード | `コード` |
<code>コード</code> |
| コードブロック | ```言語名 で囲む |
<pre><code> |
| リスト | - 項目 または 1. 項目 |
<ul> / <ol> |
| リンク | [テキスト](URL) |
<a href="URL"> |
| 画像 |  |
<img src="URL" alt="alt"> |
| 引用 | > テキスト |
<blockquote> |
| 水平線 | --- |
<hr> |
実際の使い方と変換例
README.mdの書き方
GitHubリポジトリのトップに置く README.md はMarkdownで書きます。プロジェクトの概要・インストール手順・使い方を記載するのが一般的です。
# my-project シンプルなToDoアプリです。 ## インストール ```bash npm install npm run dev ``` ## 使い方 1. タスクを入力する 2. Enterキーで追加 3. クリックで完了マーク
HTMLへの変換
上記のMarkdownを変換すると、ブラウザで表示できるHTMLになります。Markdown to HTML変換ツールを使えば、変換結果をリアルタイムで確認しながら作業できます。また、ドキュメントの文字数を確認したい場合は文字数カウンター、差分を比較したい場合はテキスト差分チェッカーも合わせて使えます。
コードブロックのシンタックスハイライト
GitHubやNotionなど多くのサービスでは、コードブロックに言語名を指定するとシンタックスハイライトが有効になります。
```javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet('World'));
```
よくある質問（FAQ）
- MarkdownはHTMLの代わりになりますか？
- ドキュメントや記事を書く用途では十分代わりになります。ただし、複雑なレイアウトや細かいスタイリングはHTMLとCSSが必要です。Markdownは「構造化されたテキスト」を書くのに特化した言語で、デザインやレイアウトの制御はHTMLに任せるというのが基本的な役割分担です。
- Markdownに対応していないサービスではどうすればいいですか？
- MarkdownをHTMLに変換してからコピーする方法が使えます。メールクライアントやWordなどMarkdown非対応の環境では、変換後のHTMLやリッチテキストを貼り付けることで書式を保持できます。Markdown to HTML変換ツールで変換後のHTMLを取得できます。
- GitHub Markdownと通常のMarkdownの違いは？
- GitHubはGFM（GitHub Flavored Markdown）という独自拡張を使っています。通常のMarkdownにはないテーブル記法、タスクリスト（
- [x] 完了）、メンション（@username）、Issue参照（#123）などが追加されています。NotionやZennなどもそれぞれ独自の拡張を持っており、サービスによって使える記法が微妙に異なります。
まとめ
- MarkdownはJohn Gruberが作った軽量マークアップ言語で、テキストで書いてHTMLに変換できる
- GitHubのREADME・Notion・技術ブログなど、開発者が日常的に使う場面で広く採用されている
- 基本記法（見出し・太字・コードブロック・リンクなど）を覚えれば大半のドキュメントは書ける
- GitHubなどのサービスごとに独自拡張（GFM等）がある
Markdownを使った作業には以下のツールが役立ちます。
- Markdown to HTML変換：MarkdownをHTMLに変換してプレビュー
- 文字数カウンター：記事・ドキュメントの文字数確認
- テキスト差分チェッカー：文章の変更前後を比較