エディタ・プレビュー・Lint｜Markdown執筆を効率化するツール

結論：VS Code＋プレビュー＋markdownlintが最もコスパの良い基本セット

Markdownはプレーンテキストなので高価な専用ソフトは不要です。実務ではVS Code（無料）で書き、プレビューで見た目を確認し、markdownlintで体裁のルール違反を検出する構成が最も普及しています。結論として、まずこの3点を揃え、必要になったらPrettierや静的サイトジェネレーターを足す段階的な導入がおすすめです。

VS Codeでの基本操作

• プレビュー：Ctrl+Shift+V（Mac: Cmd+Shift+V）
• 横並びプレビュー：Ctrl+K のあと V
• アウトライン：見出し一覧からジャンプ（長文執筆に便利）
• スニペット：よく使う表やコードブロックを短縮入力

拡張機能「Markdown All in One」は、目次自動生成・リストの続き入力・ショートカット補強などで人気があります。必須ではありませんが、READMEが長い場合は導入価値があります。

失敗例：プレビューとGitHub表示の差を見ない

VS Codeのプレビューは概ねGitHubに近いですが、表やHTML埋め込み、数式などは差が出ます。重要なREADMEはGitHub上でも最終確認する習慣を残してください。

markdownlint

見出しの飛ばし、行末スペース、リストのインデントなどを静的にチェックするLintです。VS Code拡張「markdownlint」を入れると、保存時や編集中に警告が出ます。

// .markdownlint.json の例（プロジェクトルート）
{
  "MD013": false,
  "MD033": false,
  "MD041": false
}

MD013 は1行の長さ制限、MD033 はインラインHTML禁止、MD041 はファイル先頭をH1にするルールです。日本語READMEでは1行長制限が厳しすぎるため、チームでOFFにすることが多いです。ルールを無効化する理由をREADMEかコメントに残すと、後からの混乱が減ります。

失敗例：Lintを全部無効にして意味がなくなる

すべてのルールをOFFにすると、見出しレベルの乱れやリンクの空括弧など、本当に直したい問題も見逃します。よく引っかかるルールだけ調整し、残りは守るバランスが現実的です。

Prettier

PrettierはMarkdownにも対応し、リストや折り返しを一定のスタイルに揃えます。チームで「保存時にPrettier」にすると、PRのdiffが記号の有無ではなく内容の変更に集中できます。

// .prettierrc の例
{
  "proseWrap": "preserve",
  "printWidth": 80
}

日本語文書で proseWrap: always にすると、意図しない位置で改行が入ることがあるため、preserve を選ぶチームが多いです。

WYSIWYGエディタ（Typoraなど）

Typora、MarkText、Obsidianなどは、編集とプレビューが一体化した体験を提供します。ブログや個人メモには向きますが、チームのGit運用ではVS Code＋Lintの方が再現性が高いことが多いです。好みのツールで下書きし、最終版をVS CodeでLintする、という併用もあります。

静的サイトジェネレーター（SSG）

複数のMarkdownから検索可能なドキュメントサイトを作るときはSSGを使います。

• MkDocs：Python系プロジェクトと相性が良く、設定がシンプル
• Docusaurus：Reactエコシステム、バージョン分岐が強い
• VitePress：Vue系、高速ビルド

いずれも docs/ 内のMarkdownからHTMLサイトを生成し、GitHub PagesやNetlifyにデプロイできます。READMEはリポジトリ入口、SSGは製品マニュアル本体、という住み分けが一般的です。

CIでのドキュメントチェック

GitHub Actionsで markdownlint やリンク切れチェック（markdown-link-check）を走らせる例があります。

# 概念例: PR時に docs 内の Markdown を lint
- run: npx markdownlint-cli2 "docs/**/*.md"

リンク切れは、ファイル移動や見出し変更のたびに起きます。CIで検出すると、利用者が404に遭遇する前に直せます。

拡張機能の選び方（VS Code）

最低限は標準のMarkdownプレビューと markdownlint です。加えて、Markdown All in One（目次生成・リスト補完）、Paste Image（画像の保存とパス挿入）などがよく使われます。拡張を入れすぎると設定が競合することがあるため、チームでは推奨リストをCONTRIBUTINGに5行程度で書いておくとトラブルが減ります。

執筆効率の小技

1. スニペットに「新規How-toテンプレート」を登録する
2. コマンドはターミナルで実行し、出力をそのまま貼らず要約する
3. スクリーンショットは同じ幅に揃え、altを必ず書く
4. 大きな変更は「何を」「なぜ」がわかるコミットメッセージにする

設定ファイルをリポジトリに置く

.markdownlint.json と .prettierrc をコミットすると、全員が同じルールで執筆できます。READMEに「ドキュメントの書き方」セクションを3行足し、Lintの実行方法（npx markdownlint-cli2 "**/*.md"）を書いておくと、新メンバーのオンボーディングが速くなります。

ローカルでMkDocsを試す（任意）

Pythonが入っている環境なら、pip install mkdocs のあと mkdocs new . で雛形ができます。docs/index.md を編集し mkdocs serve でブラウザプレビューすると、複数ページ構成の感覚がつかめます。本講座では必須ではありませんが、docs/設計を学んだあとの次の一歩として試す価値があります。

まとめ

ツール選びは、VS Code＋プレビュー＋markdownlintを土台に、チーム規模に応じてPrettierとCI、公開範囲に応じてSSGを追加する形が扱いやすいです。次回は、これまでの総合としてプロジェクトREADMEを一から作る実践に入ります。