Markdown基本構文：例付き完全ガイド

Markdownの基本構文は、すべての開発者、ライター、コンテンツクリエイターが習得すべき基礎です。ドキュメントの作成、ブログ記事の執筆、GitHubのIssueのフォーマットなど、これらの基本要素は日々の作業で常に使う構成要素です。

このガイドでは、すべての基本構文要素をわかりやすい例、HTML出力との比較、避けるべきよくあるミスとともに解説します。ブックマークしておいてください。思った以上に何度も見返すことになるはずです。

見出し

見出しはコンテンツを論理的な階層に構造化します。Markdownでは、テキストの前に#記号を配置することで6段階の見出しを作成できます。

# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6

これにより以下のHTMLが生成されます：

<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>

見出しのベストプラクティス

#と見出しテキストの間には必ずスペースを入れてください。スペースがないと、一部のパーサーでは見出しとして認識されません。

✅ ## This Works
❌ ##This Doesn't

見出しは順序通りに使いましょう。 H2からH4に飛ばすのは避けてください。ドキュメントの論理的なアウトラインが崩れ、アクセシビリティとSEOの両方に悪影響を与えます。見出しは目次だと考えてください。各レベルは上位のレベルの下に論理的にネストされるべきです。

H1はページごとに1つだけ使いましょう。 H1はページタイトルです。それ以外はすべてH2以下を使用してください。

段落と改行

段落はMarkdownで最もシンプルな要素です。テキストをそのまま書くだけです。段落を分けるには空行を入れます。

This is the first paragraph.

This is the second paragraph.

改行

ここで多くの初心者がつまずきます。ほとんどのMarkdownレンダラーでは、Enterを1回押しただけでは新しい行は作成されません。次のいずれかの方法を使う必要があります：

1. 行末に2つ以上のスペースを入れる（その後Enterを押す）
2. <br> HTMLタグを使う

This is the first line.
This is the second line.

Or use HTML:<br>
This starts a new line.

よくあるミス

2つの行の間でただEnterを押すだけでは、レンダリング後に1つの段落にまとめられてしまいます：

Line one
Line two

これは「Line one Line two」と1行で表示されます。新しい段落には必ず空行を、同じ段落内での改行には行末のスペースを使用してください。

テキストの書式設定

Markdownでは簡単にテキストを強調できます。主な書式設定オプションは以下の通りです：

太字

テキストを二重アスタリスクまたは二重アンダースコアで囲みます：

**This is bold text**
__This is also bold__

HTML出力：<strong>This is bold text</strong>

イタリック

テキストを単一のアスタリスクまたは単一のアンダースコアで囲みます：

*This is italic text*
_This is also italic_

HTML出力：<em>This is italic text</em>

太字とイタリック

三重アスタリスクで両方を組み合わせます：

***Bold and italic***
___Also bold and italic___
**_Or mix like this_**

HTML出力：<strong><em>Bold and italic</em></strong>

取り消し線

二重チルダを使います（GFM拡張ですが、ほぼすべての環境でサポートされています）：

~~This text is crossed out~~

HTML出力：<del>This text is crossed out</del>

よくあるミス

単語の途中でアンダースコアを使う書式設定は、安定して動作しません。単語の途中での強調にはアスタリスクを使いましょう：

✅ This is**very**important
❌ This is__very__important

引用

引用は>文字で作成します。出典の引用、重要な注意事項の強調、主要な情報の呼び出しによく使われます。

> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber

HTML出力：

<blockquote>
  <p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
  — John Gruber</p>
</blockquote>

複数段落の引用

段落間の空行に>を追加します：

> First paragraph of the quote.
>
> Second paragraph of the quote.

ネストされた引用

>>でネストできます：

> This is the outer quote.
>
>> This is a nested quote inside it.

他の要素と組み合わせた引用

引用を他のMarkdown書式と組み合わせることができます：

> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.

リスト

リストはMarkdownで最も頻繁に使われる要素の一つです。順序なしリスト、順序付きリスト、タスクリストの3種類があります。

順序なしリスト

-、*、+をマーカーとして使います。一貫性のために1つを選んで統一しましょう：

- First item
- Second item
- Third item

HTML出力：

<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
</ul>

順序付きリスト

数字の後にピリオドを付けます。実際の数字は関係ありません。Markdownが自動的に番号を振ります：

1. First step
2. Second step
3. Third step

興味深いことに、以下でも同じ出力になります：

1. First step
1. Second step
1. Third step

どちらも正しく1-2-3と番号が振られたリストとして表示されます。ただし、ソースファイルの可読性のために連番を使うのがベストプラクティスです。

ネストされたリスト

2つまたは4つのスペースでインデントしてサブリストを作成します：

1. Main item
   - Sub-item A
   - Sub-item B
     - Sub-sub-item
2. Another main item

タスクリスト

タスクリスト（GFM機能）は、未チェックに- [ ]、チェック済みに- [x]を使います：

- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish

よくあるミス

段落の後にリストが続く場合、リストの前の空行を忘れがちです。一部のパーサーでは空行が必要です：

✅ Here is my list:

- Item one
- Item two

❌ Here is my list:
- Item one
- Item two

コード

コードの表示はMarkdownの最も強力な機能の一つであり、正しく使うことが可読性にとって重要です。

インラインコード

インライン表示にはテキストを単一のバッククォートで囲みます：

Use the `print()` function to output text.

HTML出力：Use the <code>print()</code> function to output text.

コード自体にバッククォートが含まれる場合は、二重バッククォートを使います：

``There is a literal `backtick` here.``

コードブロック

複数行のコードには、三重バッククォート（フェンスドコードブロック）を使い、シンタックスハイライト用に言語識別子をオプションで指定します：

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

言語識別子（javascript、python、html、css、bashなど）を指定すると、ほとんどのレンダラーでシンタックスハイライトが有効になります。必ず指定しましょう。可読性が大幅に向上します。

インデントによるコードブロック

すべての行を4つのスペースまたは1つのタブでインデントすることでもコードブロックを作成できます：

    function add(a, b) {
      return a + b;
    }

ただし、フェンスドコードブロックが強く推奨されます。シンタックスハイライトをサポートし、すべての行をインデントする必要がないためです。

リンク

リンクはコンテンツを接続するために不可欠です。Markdownはいくつかのリンク形式をサポートしています。

インラインリンク

最も一般的な形式で、テキストを角括弧、URLを丸括弧で囲みます：

[Visit Example](https://example.com)

HTML出力：<a href="https://example.com">Visit Example</a>

タイトル付きリンク

URLの後に引用符で囲んだタイトルを追加します（ホバー時にツールチップとして表示されます）：

[Visit Example](https://example.com "Example Website")

参照スタイルリンク

リンクが多い場合にソーステキストを見やすくするため、参照スタイルを使います：

I use [Google][1] and [GitHub][2] daily.

[1]: https://google.com "Google"
[2]: https://github.com "GitHub"

段落がすっきりし、すべてのURLが末尾にまとまります。長いドキュメントで特に便利です。

自動リンク

URLやメールアドレスを山括弧で囲むと自動リンクになります：

<https://example.com>
<contact@example.com>

GitHubなどの最新のレンダラーでは山括弧なしでも自動リンクされますが、山括弧を使うことで互換性を確保できます。

よくあるミス

URL内のスペースにはエンコードが必要であることを忘れがちです。スペースには%20を使いましょう：

✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)

画像

画像はリンクと同じ構文ですが、先頭に感嘆符!を付けます：

![Alt text describing the image](/path/to/image.webp)

HTML出力：<img src="/path/to/image.webp" alt="Alt text describing the image">

タイトル付き画像

![A sunset over the ocean](/images/sunset.webp "Beautiful sunset")

リンク付き画像

リンクと画像の構文を組み合わせて、クリック可能な画像を作成します：

[![Alt text](/images/photo.webp)](https://example.com)

代替テキストのベストプラクティス

常に説明的な代替テキストを書きましょう。 2つの重要な目的があります：

1. アクセシビリティ — スクリーンリーダーが視覚障害のあるユーザーに画像を説明するために使用します
2. SEO — 検索エンジンが画像の内容を理解するために使用します

✅ ![Markdown syntax cheat sheet showing headings, lists, and links](/images/cheatsheet.webp)
❌ ![image](/images/cheatsheet.webp)
❌ ![](/images/cheatsheet.webp)

水平線

水平線（テーマブレイク）を作成して、セクションを視覚的に区切ります。3つ以上のダッシュ、アスタリスク、またはアンダースコアを使います：

---
***
___

3つすべてが同じHTMLを生成します：<hr>

ベストプラクティス： ---を一貫して使用し、前後に必ず空行を入れましょう：

Content above the rule.

---

Content below the rule.

エスケープ文字

Markdownの書式設定を発動させずに、アスタリスクやハッシュ記号をそのまま表示したい場合はどうすればよいでしょうか？文字の前にバックスラッシュ\を置きます：

\* This is not italic \*
\# This is not a heading
\- This is not a list item

エスケープできる文字の一覧は以下の通りです：

\   Backslash
`   Backtick
*   Asterisk
_   Underscore
{}  Curly braces
[]  Square brackets
()  Parentheses
#   Hash
+   Plus sign
-   Hyphen
.   Dot
!   Exclamation mark
|   Pipe

クイックリファレンス早見表

すべての基本構文要素を一覧にまとめました：

Element         Syntax              HTML
--------------  ------------------  -----------
Heading 1       # Text              <h1>
Heading 2       ## Text             <h2>
Heading 3       ### Text            <h3>
Bold            **text**            <strong>
Italic          *text*              <em>
Bold + Italic   ***text***          <strong><em>
Strikethrough   ~~text~~            <del>
Blockquote      > text              <blockquote>
Ordered list    1. item             <ol><li>
Unordered list  - item              <ul><li>
Inline code     `code`              <code>
Link            [text](url)         <a href>
Image           ![alt](src)         <img>
Horizontal rule ---                 <hr>
Line break      spaces + Enter      <br>

実践してみよう

Markdownの基本構文要素をすべて学んだので、実際に使ってみましょう。次のステップは以下の通りです：

1. 書いて練習する：notes.mdファイルを作成し、各構文要素を試してみてください。書けば書くほど自然に身につきます。

2. プレビューツールを使う：VS Code内蔵のMarkdownプレビュー（Ctrl+Shift+V / Cmd+Shift+V）を使えば、入力しながらリアルタイムでレンダリング結果を確認できます。

3. 変換して共有する：Markdownドキュメントが完成したら、洗練された出力に変換しましょう — Markdown→HTML変換ツールでウェブ公開、Markdown→PDF変換ツールで印刷用ドキュメント、Markdown→Word変換ツールで共同編集が可能です。

4. さらに探求する：基本構文に慣れたら、Markdown拡張構文ガイドでテーブル、脚注、定義リストなどに挑戦しましょう。Markdownが全く初めてですか？Markdownとはで全体像を把握してください。

Markdownの素晴らしさは、これらの基本要素だけで、書く必要のあるほとんどすべてのことをカバーできる点です。一度マスターすれば、GitHubからNotionまで、ドキュメントからこのようなブログ記事まで、あらゆる場面で活用できます。