書式を覚えて満足してない？ Markdownをフル活用するための13テクニック：覚えるごとにドキュメント作成がレベルアップ

TechTargetは2024年12月18日、「『Markdown』を効果的に利用するためのヒントとテクニック」に関する記事を公開した。Markdownの基本を学び、適切なエディタを見つけるのはそれほど難しくない。しかし、ドキュメント作成においてMarkdownを最大限に活用するには、多少の“指針”が必要だ。

[Damon Garn，TechTarget]

　TechTargetは2024年12月18日（米国時間）、「『Markdown』を効果的に利用するためのヒントとテクニック」に関する記事を公開した。Markdownはドキュメント作成のワークフローを効率化したい執筆者にとって大きな助けとなるツールだが、使いこなすにはある程度の指針が必要になる。

Markdownについて知っておきたい13のヒントとテクニック（TechTarget）

　Markdownには幾つかの種類（フレーバー）が存在する。代表的なフレーバーには以下のようなものがある。

• CommonMark：仕様に一貫性を持たせるための詳細ルールと拡張機能を備えた標準的なMarkdown
• GitHub Flavored Markdown（GFM）：表、リスト、自動リンクなどの機能をサポートするGitHub向けに拡張されたMarkdown
• Markdown Extra：表、脚注、フェンスコードブロック（コードの囲み表示）などの追加機能を含むMarkdown

　本稿で紹介するテクニックは、フレーバーの違いを超えて適用できるものだが、独自の特徴を持つものもあるため、それぞれの仕様を理解しておくことで、最適な機能を活用できるようになるだろう。

Markdownのヒントとテクニック13選

　Markdownは、執筆者にとって非常に強力なツールの一つだ。まずは、良質なドキュメントを作成する習慣を身に付け、基本的なマークアップ指示を理解することから始めよう。プレビュー機能を備えた使いやすいエディタを見つけ、慣れておくことも重要だ。ただし、Markdownは全ての場面で万能というわけではない。例えば「Microsoft Word」などのワードプロセッサで作成したドキュメントとMarkdownを混ぜて使うのは避けた方がよい。それぞれのツールに適した用途があるため、適材適所で使い分けることが重要だ。

　もし、Markdownが適した場面なのであれば、以下のテクニックを活用することでスキルを向上させられるだろう。紹介するテクニックは以下の13個だ。

1. 基本を押さえる
2. 目次を作成する
3. 構造を組み立てる
4. 空行をうまく使う
5. リストを活用する
6. コードを仕切る
7. リンクを追加する
8. 優れたエディタを選ぶ
9. ショートカットを活用する
10. 全てプレビューする
11. 画像を利用する
12. Markdownの可搬性を維持する
13. チートシートを作成する

1．基本を押さえる

　どんなツールでも、まずは基本を習得することが重要だ。以下のMarkdownの基本的な書式をしっかり理解しておこう。

太字

　単語の前後に、**（アスタリスク2つ）または__（アンダースコア2つ）を追加する。

**太字**
__太字__

斜体

　単語の前後に、*（アスタリスク1つ）または_（アンダースコア1つ）を追加する。

*斜体*
_斜体_

太字＋斜体

　単語の前後に、***（アスタリスク3つ）または___（アンダースコア3つ）を追加する。

***太字＋斜体***
___太字＋斜体___

水平線（区切り線）

　単独の行に、***、---、___のいずれかを記述する。

***

番号付きリスト

　「1.」の後にスペースを入れると、自動的に番号が振られる。Markdownが自動で番号を増やしてくれるため、全て「1.」と記述しても問題ない。

1. 項目1  
1. 項目2  
1. 項目3  

番号なしリスト

　行の先頭に、-（ハイフン）を入力する。

- 項目A  
- 項目B  
- 項目C  

見出し

　行の先頭に、#（ナンバー記号）を入力する。「#」は見出しH1、「##」は見出しH2、「###」は見出しH3を表す。

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

　基本的なマークアップを覚えるだけで、Markdownでのドキュメント作成の効率と速度を大幅に向上させることができる。これは、Markdownを用いたドキュメント作成において非常に重要な部分だ。

2．目次を作成する

　ドキュメントが長くなる場合は、目次を作っておくと便利だ。読者が読みたい部分（セクション）にすぐに移動できるため、スクロールの手間を省くことができる。目次の各項目には、対応する見出しへのリンクを設定する。これによって、Markdownドキュメントがより読みやすく、扱いやすくなる。

　目次は、次の手順で作成する。

1. 見出しのリストを作成する（通常、H1またはH2レベルの見出しにする）
2. 各見出しにリンクを設定する

構文は以下のようになる。

[見出しのテキスト](#セクションタイトル)

　“#セクションタイトル”の部分は、対応する見出しのテキストを小文字に変換する。空白文字を含める場合は、-（ハイフン）で代用する。例えば、見出しH2の名前が「Markdown 例」ならば、目次のリンクは次のように指定する。

[Markdownの例](#markdownの例)

　読者がこのリンクをクリックすると、ドキュメントの該当セクションに即座に移動できる。Markdownでの目次の詳しい例を図1に示す。

図1　リンク構文と見出し構文（左側）と作成された目次（右側）

3．構造を組み立てる

　Markdownドキュメントは、適切な構造を持たせることが重要だ。まず、主要ポイントを整理し、次に副次的な内容（補足情報）を特定するためのアウトラインを作成する。その上で、それに沿った見出し構造を設計することで、ドキュメント全体が分かりやすくなる。

　Markdownで見出しを作成するには、#（ハッシュ）を1つ以上記述し、その後に半角スペースを入れて見出しのテキストを書けばよい。Markdownは複数の見出しレベルを利用できるが、一般的なドキュメントではH1（#）、H2（##）、H3（###）の3つがあれば十分なことが多い。定期的に作成するドキュメントについては、あらかじめテンプレートを作成しておくとよいだろう。

4．空行をうまく使う

　空行を適切に使おう。Markdownは一部の書式指示に空行を利用する。例えば見出しの後、段落の間、箇条書き項目の間に空行を設けるとよい。こうした空行は、エクスパンダブルテキストなどの高度な機能において重要になる。

5．リストを活用する

　Markdownはリストを使うことで、視認性を向上させることができる。リストには、番号付きリストと番号なしリストがある。番号付きリストを作成するには、各項目の前に「1.」を記述する。番号なしリストを作成するには、各項目の前に-（ハイフン）を記述する。

　以下のコードによって、番号付きリストが作成される。

　1. First item
　1. Second item
　1. Third item

　以下のコードによって、番号なしリストが作成される。

　- First item
　- Second item
　- Third item

　リストの項目をインデント（字下げ）することで、階層的なサブポイントを作成できる。

- メイン項目  
  - サブ項目1  
  - サブ項目2  

　これらのリストを、インタラクティブなチェックリストにすることも可能だ。リストの記号の後に[ ]（半角の角括弧の中にスペース）を追加すると、チェックボックスが表示され、読者がクリックしてオン、オフを切り替えられる。ただし、Markdownの全てのフレーバーがチェックボックスに対応しているわけではないことには注意が必要だ。GFMなど、特定の環境でのみ動作する。

　以下のコードによって、チェックボックス付きの箇条書きが作成される。

　- [ ] Checkbox

　Markdownエディタは、通常、左側のペインに記述されたMarkdownコードが表示され、右側のペインにリストのレンダリング結果が表示される。図2は、番号付きリスト、番号なしリスト、チェックリストのそれぞれの記法と表示例を示している。

図2　3種類の箇条書き（番号付き、番号なし、チェックボックス付き）の構文（左側）と対応する出力（右側）

6．コードを仕切る

　コーディングが必要なプロジェクトでMarkdownを利用する技術系ライターは多い。このような場合、例示や説明のためにコードブロックを明確に区別する必要がある。Markdownでは、コードを「インラインコード」と「コードブロック」に分けて表記できる。短いコードを文章内に埋め込む場合は、3つのバッククオート（```）で囲む。

　例えば、

```print('Hello World')```

は、Python環境では

Hello World

と出力される。

　ただし、複数行のコードを表示する場合はコードブロックの方が適している。複数行のコードの初めと終わりに3つのバッククオートを追加することで、仕切り付きコードブロックを作成できる。

　例えば、シンプルな2行のコードブロックは、Markdownでは次のように記述する。

```
# Print "Hello World" using Python（Pythonを使って"Hello World"を出力）
print('Hello World')
```

　図3は、Markdownエディタで一般的に使われる仕切り付きコードブロックの例だ。

図3　複数行コードブロックの構文（左側）と対応する出力（右側）

7．リンクを追加する

　Markdownは、外部のサイトやドキュメント内へのリンクを簡単に追加できる。「http://www.techtarget.com」のように単なるURLの貼り付けは避け、テキストにリンクを埋め込むのが望ましい。

　テキストを[]（角括弧）で囲み、その直後にURLと説明文を含む()（丸括弧）を追加する。説明文を入れることで、検索エンジン最適化（SEO）にも役立つ。

　図4は、この例がMarkdownエディタでどのように表示されるかを示している。

図4　リンク構文（左側）とプレビューペインに表示される結果（右側）

　目次セクションで紹介したように、リンクはドキュメント内の他の部分を指すこともできる。

8．優れたエディタを選ぶ

　Markdownを効率的に扱うためには、自分に合ったエディタを見つけることが重要だ。エディタにはさまざまな種類があり、必要な機能に応じて選択するとよい。

　「StackEdit」や「Minimalist Online Markdown Editor」などのオンラインエディタを好むユーザーもいれば、「Typora」や「Ghostwriter」などのローカルテキストエディタを好むユーザーもいる。「Visual Studio Code」（VS Code）をMarkdownエディタとして利用するユーザーもいる。このエディタは拡張機能や便利なプレビューオプションを利用できる。

　筆者はテキストエディタ「Vim」を愛用している。VimにはMarkdownの諸機能や拡張機能をサポートするさまざまなバージョンがある。例えば、人気の高い「NeoVim」アプリケーションには「markdown-preview.nvim」プラグインがある。これを使えば、ユーザーは近代的なブラウザでMarkdownをリアルタイムプレビューできる。

9．ショートカットを活用する

　Markdownエディタを選んだら、そのエディタが持つ機能やショートカットを習得することが重要だ。これらを活用することで、フォーマットの適用やリアルタイムプレビューの更新がスムーズになり、Markdownでの作業が格段に効率化される。

　さらに、エディタの拡張機能も活用しよう。多くのテキストエディタやコードエディタは、カスタマイズ、プラグイン、拡張機能をサポートしており、Markdownの作業をより簡単にしてくれる。

10．全てプレビューする

　Markdownで作業する際は、エディタのプレビュー機能を活用しよう。プレビューを確認しながら作業することで、誤りを即座に修正でき、文書の構造が正しく整理されているかどうかを確認できる。プレビュー機能は、多くのエディタに搭載されている最も便利な機能の一つだ。

図5　レンダリングされるMarkdownを簡単に確認できるプレビューモード。コーディングペイン（左側）とコードがレンダリングされる状態を表示するプレビューペイン（右側）

11．画像を利用する

　「百聞は一見にしかず」と言うが、Markdownで画像を追加するのは実際にやってみるとその簡単さがよく分かる。

　画像は

「![alt-text](URLまたはファイルパス)」

で追加できる。画像の参照方法としてはローカルファイル、画像リポジトリ、オンラインサイトなどさまざまな選択肢がある。alt-textはスクリーンリーダー（画面読み上げソフトウェア）向けの説明としても有用で、SEOにも寄与する可能性がある。

　例えば、PCのローカルフォルダ「~/articles/images/guitar.jpg」に保存されているお気に入りのギターの画像をMarkdown文書に追加するには、以下のように記述する。

![butterscotch-blonde-esquire](~/articles/images/guitar.jpg)

　図6は、Markdownの画像挿入コードを使った場合に、ブラウザでどのようにレンダリングされるかを示している。

図6　Markdownファイルで画像を挿入するコード（上）とブラウザにレンダリングされる画像（下）

12．Markdownの可搬性を維持する

　Markdown文書はプレーンテキスト（.mdファイル）として保存し、ワードプロセッサなどには取り込まないようにしよう。Microsoft Wordのようなアプリケーションでは、Markdownのレンダリングを妨げる余分なフォーマット情報が自動的に追加される可能性がある。

　著者はシンプルなテキストエディタでの執筆を推奨しているが、Markdownでは特に重要となる。Markdownの最大の利点の一つは「可搬性の高さ」だ。気付かないうちに非標準の書式設定が追加されることでMarkdownの強みが失われないように注意しなければならない。

13．チートシートを作成する

　Markdownをより効率的に使うために、よく使う機能や覚えにくい構文をまとめたチートシートを作成しよう。特に、使用しているフレーバーの独自仕様をメモしておくと役立つ。必要に応じてMarkdownの機能を拡張するHTMLタグについても追加するといいだろう。

　筆者は現在、Markdownを使ってラボの教材を作成しており、日常的にMarkdownを使用している。しかし、プロジェクトの合間には数カ月間Markdownを使わないこともある。そんなとき、チートシートはMarkdownの書き方を思い出すための優れたレファレンスとなる。