Markdown完全ガイド:構文、ヒント、ベストプラクティス

· 12分で読む

目次

Markdownとは?

Markdownは、2004年にJohn GruberがAaron Swartzと共同で作成した軽量マークアップ言語です。レンダリングなしでも読みやすいプレーンテキスト構文を使用して、書式付きテキストを書くことができます。ワードプロセッサでボタンをクリックしたり、冗長なHTMLタグを書いたりする代わりに、見出しには#、太字テキストには**、リストには-のような、シンプルで直感的な文字を使用します。

Markdownの背後にある哲学はエレガントにシンプルです:ソーステキストはレンダリングされた出力と同じくらい読みやすくあるべきです。任意のテキストエディタでMarkdownファイルを開くと、特別なソフトウェアやレンダリングエンジンを必要とせずに、その構造と内容をすぐに理解できます。

Markdownは、ソフトウェア開発の世界全体で、技術文書、ドキュメント、READMEファイル、ブログ投稿、ノート作成のデファクトスタンダードになっています。GitHub、GitLab、Reddit、Stack Overflow、Discord、Slack、Notion、Obsidianなどの主要プラットフォームはすべてMarkdownをネイティブにサポートしており、開発者、技術ライター、コンテンツクリエイターにとって必須のスキルとなっています。

なぜMarkdownを使うのか?

プロのヒント: Markdownファイルを定期的に扱う場合は、ライブプレビューとシンタックスハイライトのためにMarkdownエディタを試すか、Markdown to HTMLコンバータを使用してドキュメントを即座に変換してください。

見出しと文書構造

見出しはMarkdownの文書構造の骨格です。#記号を使用し、ハッシュマークの数が1から6までの見出しレベルを決定します:

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

#記号の後には必ずスペースを入れてください。ほとんどのMarkdownプロセッサはこれを必要とし、可読性も向上します。レンダリングされた出力は適切なHTML見出しタグ(<h1>から<h6>)を作成し、これは文書構造、アクセシビリティ、SEOにとって重要です。

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

見出しレベルをスキップせずに順番に使用してください。H1からH3に飛ばないでください。これは文書階層を壊し、スクリーンリーダーユーザーのアクセシビリティの問題を引き起こします。見出しをアウトラインとして考えてください:各レベルは前のレベル内に論理的にネストする必要があります。

ほとんどの文書には1つのH1見出し(タイトル)のみがあり、主要なセクションにはH2見出し、サブセクションにはH3-H6があります。これにより、人間と検索エンジンの両方が理解できる明確な情報階層が作成されます。

クイックヒント: 多くのMarkdownプロセッサは見出しのアンカーリンクを自動的に生成し、特定のセクションに直接リンクできるようにします。たとえば、GitHubは「## Getting Started」を#getting-startedで参照できるアンカーに変換します。

代替見出し構文

Markdownは、下線を使用したH1とH2見出しの代替構文もサポートしています:

見出し1
=========

見出し2
---------

この構文は有効ですが、ハッシュマーク構文の方が一般的で、6つの見出しレベルすべてをサポートしているため、ほとんどのライターにとって好ましい選択です。

テキスト書式の基本

Markdownは、一般的なテキスト書式のニーズに対して、シンプルで直感的な構文を提供します。これらの書式オプションは段落内でインラインで機能し、より複雑なスタイリングのために組み合わせることができます。

書式 構文 代替 結果
太字 **太字** __太字__ 太字
斜体 *斜体* _斜体_ 斜体
太字+斜体 ***両方*** ___両方___ 両方
取り消し線 ~~削除~~ — 削除
インラインコード `コード` — コード
下付き文字 H~2~O — H2O
上付き文字 X^2^ — X2
ハイライト ==マーク== — マーク

強調構文の詳細

アスタリスク(*)とアンダースコア(_)の両方が強調に使用できますが、アスタリスクの方が一般的に使用され、推奨されています。主な違い:アスタリスクは単語の途中で機能します(un*frigging*believable)が、アンダースコアは単語の境界が必要です。

太字テキストには、二重アスタリスクまたはアンダースコアを使用します。斜体テキストには、単一のアスタリスクまたはアンダースコアを使用します。太字斜体テキストには3つを組み合わせます。この一貫性により、Markdownソースがより読みやすく予測可能になります。

プロのヒント: 技術文書を書くときは、インラインコード、関数名、ファイルパス、コマンドライン引数に`バッククォート`を使用してください。この視覚的な区別により、読者は文章内のコード要素を素早く識別できます。

特殊文字のエスケープ

リテラルのアスタリスク、アンダースコア、またはその他のMarkdown構文文字を表示する必要がある場合は、バックスラッシュでエスケープします:

これは\*斜体ではありません\*そして\*\*太字ではありません\*\*
見出しを作成せずにハッシュマークを表示するには\#を使用します

エスケープが必要な一般的な文字には次のものがあります:\ ` * _ { } [ ] ( ) # + - . !

リスト:順序付き、順序なし、ネスト

リストはMarkdownで情報を整理するための基本です。作成が簡単で、階層的なコンテンツのネストをサポートしています。

順序なしリスト

-、*、または+の後にスペースを使用して、順序なし(箇条書き)リストを作成します。3つのマーカーはすべて同じように機能しますが、文書内での一貫性により可読性が向上します:

- 最初の項目
- 2番目の項目
- 3番目の項目
  - ネストされた項目(2つのスペースでインデント)
  - 別のネストされた項目
- 4番目の項目

ネストされたリストの標準的なインデントは2つのスペースですが、一部のパーサーは4つを受け入れます。最大の互換性のために2つのスペースを使用してください。

順序付きリスト

順序付き(番号付き)リストは、数字の後にピリオドとスペースを使用します:

1. 最初のステップ
2. 2番目のステップ
3. 3番目のステップ
   1. サブステップA
   2. サブステップB
4. 4番目のステップ

便利な機能があります:使用する実際の数字は重要ではありません。Markdownはレンダリング時にリストを自動的に順番に番号付けします。すべての項目に1.を使用でき、番号を振り直すことなく項目を並べ替えやすくなります:

1. 最初の項目
1. 2番目の項目
1. 3番目の項目

これは適切に番号付けされた1、2、3のリストとしてレンダリングされます。この手法は、長いリストを維持したり、項目を頻繁に並べ替えたりする場合に特に役立ちます。

タスクリスト

多くのMarkdownフレーバー(GitHub Flavored Markdownを含む)は、チェックボックス付きのタスクリストをサポートしています:

- [x] 完了したタスク
- [ ] 未完了のタスク
- [ ] 別の未完了のタスク

タスクリストは、プロジェクト管理、問題追跡、ドキュメント内のToDoリストに非常に役立ちます。

クイックヒント: リスト項目内に複数の段落やコードブロックを含めるには、後続のコンテンツをリスト項目テキストの最初の文字に揃えるようにインデントします(通常、順序なしリストでは3-4スペース、順序付きリストでは4スペース)。

定義リスト

一部の拡張Markdown構文は、用語集と用語定義のための定義リストをサポートしています:

用語1
: 用語1の定義

用語2
: 用語2の最初の定義
: 用語2の2番目の定義

普遍的にサポートされているわけではありませんが、定義リストは技術文書や用語集に役立ちます。

Markdownを使用すると、ソーステキストを読みやすく保ちながら、ハイパーリンクや画像を簡単に追加できます。

インラインリンク

最も一般的なリンク構文は、リンクテキストに角括弧、URLに丸括弧を使用します:

[リンクテキスト](https://example.com)
[タイトル付きリンク](https://example.com "ホバーテキスト")

オプションのタイトルテキストは、ユーザーがリンクにカーソルを合わせたときにツールチップとして表示されます。これは、表示されるリンクテキストを乱雑にすることなく、追加のコンテキストを提供するのに役立ちます。

参照スタイルのリンク

多くのリンクや繰り返されるURLを含む文書の場合、参照スタイルのリンクは可読性を向上させます:

これは[リンク][1]で、こちらは[別のリンク][2]です。

[1]: https://example.com
[2]: https://example.com/page "オプションのタイトル"

数字の代わりに説明的な参照を使用することもできます:

[Google][google]と[GitHub][gh]をチェックしてください。

[google]: https://google.com
[gh]: https://github.com

参照定義は文書内のどこにでも配置でき、出力にはレンダリングされません。多くのライターは、セクションの最後または文書の最後に配置します。

自動リンク

URLまたはメールアドレスを山括弧で囲んで、自動リンクを作成します:

<https://example.com>
<[email protected]>

ほとんどの最新のMarkdownパーサーは、裸のURLもクリック可能なリンクに自動的に変換しますが、この動作はすべてのプラットフォームで保証されているわけではありません。

画像

画像構文は、感嘆符のプレフィックスを除いて、リンク構文とほぼ同じです:

![代替テキスト](image.jpg)
![代替テキスト](image.jpg "画像タイトル")

代替テキストはアクセシビリティにとって重要です。スクリーンリーダーユーザーのために画像を説明し、画像の読み込みに失敗したときに表示されます。常に画像の内容と目的を伝える意味のある代替テキストを提供してください。

参照スタイルの構文は画像にも機能します:

![ロゴ][logo]

[logo]: /images/logo.png "会社のロゴ"

プロのヒント: 標準のMarkdownは画像のサイズ変更や配置をサポートしていません。これらの機能には、HTMLを直接使用する必要があります:<img src="image.jpg" width="300" alt="説明">または、プラットフォーム固有の拡張Markdown構文に依存します。

画像のリンク

画像をクリック可能にするには、画像構文をリンク構文で囲みます:

[![代替テキスト](thumbnail.jpg)](full-size.jpg)

この手法は、画像ギャラリーやサムネイルをフル解像度バージョンにリンクするために一般的に使用されます。

コードブロックとシンタックスハイライト

Markdownはコードの表示に優れており、技術文書やプログラミングチュートリアルに好まれる形式となっています。

インラインコード

テキスト内の短いコードスニペットには、単一のバッククォートを使用します:

出力を表示するには`print()`関数を使用します。
`config.json`ファイルには設定が含まれています。

コードにバッククォートが含まれている場合は、二重バッククォートで囲みます:

``コードで`バッククォート`を使用``

フェンスコードブロック

複数行のコードブロックには、コードの前後に三重バッククォート(```)または三重チルダ(~~~)を使用します:

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

これにより、等幅フォントと保持された空白を持つ適切にフォーマットされたコードブロックが作成されます。

シンタックスハイライト

シンタックスハイライトを有効にするには、開始バッククォートの直後にプログラミング言語を指定します:

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

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
#!/bin/bash
echo "Hello, World!"
```