なぜMarkdownで書くのか
Markdownは軽量マークアップ言語で、シンプルな記号で書式を表現します。マウスに触れることなく、内容に集中しながら書式が自動生成されます。
メリット：
- プレーンテキスト—どのエディタでも開ける
- バージョン管理に適している（Gitで差分表示可能）
- HTML、PDF、Wordなどに変換可能
- 学習コストが低く、10分で入門できる
基本記法
見出し
# 見出し1
## 見出し2
### 見出し3
#### 見出し4
1つの記事につき見出し1は1つだけにすることを推奨します。
段落
空行で段落を区切ります。空行がない内容は同じ段落として扱われます。
強調
**太字**
*斜体*
~~取り消し線~~
リスト
箇条書き：
- 項目
- 項目
- サブ項目（インデント）
番号付き：
1. 1番目の項目
2. 2番目の項目
リンクと画像
[リンクテキスト](https://example.com)
コード
インライン：code
コードブロック：
```javascript
const x = 1;
### 引用
引用内容 2行目
### 水平線
## 拡張記法
### テーブル
| 名前 | 年齢 |
|---|---|
| Tom | 25 |
### タスクリスト
- 完了
- 未完了
### 脚注
本文^1
### 取り消し線
削除
### 自動リンク
URLは自動的にリンクに変換されます。
## 執筆のコツ
### 見出し階層を明確に
- 見出し1：記事タイトル
- 見出し2：主要セクション
- 見出し3：サブセクション
- 階層を飛ばさない（見出し1から見出し3へ直接ジャンプしない）
### 段落を簡潔に
- 1段落1つのアイデア
- 段落を長くしすぎない（3〜5行が理想）
- 長い段落はリストで代用
### リストを活用
並列内容はリストを使うと、段落より明確です：
- ステップには番号付きリスト
- 並列項目には箇条書きリスト
- 比較項目にはテーブル
### コードに言語を明記
コードブロックに言語を明記すると、シンタックスハイライトが有効になります：
画像に説明を付ける
 の説明は重要です：
- 画像の読み込み失敗時に説明が表示される
- スクリーンリーダーが視覚障害のあるユーザーに説明を読み上げる
- SEOに有利
リンクを明確に
- リンクテキストはリンク先の内容を示す—"ここをクリック"は使わない
- 外部リンクには完全なURLを使用
- 内部リンクには相対パスを使用
文書の構成
先頭に目次を置く
長い文書の先頭には目次を置き、各セクションにリンクします。移動しやすくなります。
セクションは見出しで区切る
セクションは水平線ではなく見出しで区切ります。見出しには階層がありますが、水平線にはありません。
コードと文章を分ける
コードブロックの前後に空行を入れ、本文と分離します。読みやすくなります。
画像を適切な位置に置く
画像は末尾にまとめるのではなく、関連する文章の直後に置きます。読者が順序通りに読むとき、適切なタイミングで画像を見られます。
エディタの選択
VS Code
- 無料で強力
- Markdownプラグインをインストール（例：Markdown All in One）
- リアルタイムプレビュー
- 開発者向け
Typora
- WYSIWYG
- プレビューウィンドウなし—レンダリング結果を直接編集
- 有料だが手頃な価格
- 集中して執筆するのに適している
Obsidian
- ローカルのナレッジベース
- 双方向リンク
- 豊富なプラグイン
- ノートとナレッジ管理に適している
オンラインエディタ
- StackEdit：オンラインMarkdownエディタ
- 簡書：中国語の執筆プラットフォーム
- 一時的な執筆に適している
MarkdownをHTMLに変換
Markdownで書いた後、ウェブに表示するためにHTMLに変換します。Markdown to HTMLツールでワンクリック変換できます。
よくある間違い
見出しの後にスペースがない
#見出し は認識されません。# 見出し（#の後にスペース）を使用してください。
リストのインデントが間違っている
サブリストは2または4スペースでインデントします（パーサーによります）。インデントが間違っているとサブリストが表示されません。
コードブロックが閉じていない
開始と終了の ``` が両方必要です。終了を忘れると、その後のすべてがコードブロックになります。
特殊文字がエスケープされていない
などの記号を表示したい場合、バックスラッシュでエスケープします：* は * と表示されます。
テーブルの記法エラー
テーブルにはヘッダー区切り行（| --- |）が必要です。これがないとテーブルとして認識されません。
リンクの括弧が不一致
[リンク](url のように閉じ括弧がないと、リンクが認識されません。
ベストプラクティス
1つの文書に1つのテーマ
1つの記事で1つのテーマを扱います。複数のテーマがある場合は複数の記事に分割し、リンクで関連付けます。
まず内容を書き、後に書式を整える
まずプレーンテキストで内容を書き、その後Markdownマークアップを追加します。書きながら書式を整えると思考が途切れます。
スタイルを統一
チームで執筆する場合はスタイルを統一します：
- 見出しを何階層まで使うか
- リストには - か * を使うか
- コードブロックの言語明記
- リストの最大ネスト深度
ソースファイルを保管
Markdownはソースファイル、HTML/PDFは生成物です。編集しやすいようにMarkdownを保管し、出力フォーマットは毎回再生成します。
まとめ
Markdown執筆のポイント：見出し階層を明確に、段落を簡潔に、リストを活用、コードに言語を明記、画像に説明を付ける。適切なエディタを選び、スタイルを統一し、ソースファイルを保管します。表示にはDocsAll Markdown to HTMLツールを使用—ブラウザ上で動作します。