レッスン 6
Markdown 執筆ワークフロー
公開前に見出し構造、リンク、表、よくある Markdown のミスをレビューします。
GitHub、ドキュメントリポジトリ、CMS フィールドに Markdown を公開する前に、短いレビューを実行します。
実践的なワークフロー
- Markdown でドキュメントを下書きする。
- レンダリング出力をプレビューする。
- スキップされたレベルや欠落セクションがないか見出しアウトラインを確認する。
- 壊れたまたはプレースホルダー URL のリンクリストをレビューする。
- 表、コードブロック、タスクリストが正しくレンダリングされるか確認する。
- Git ベースの宛先には Markdown を、CMS/メール経路には HTML をコピーする。
よくある Markdown のミス
- 見出しレベルのスキップ：
#から##を飛ばして###へ - 壊れたリスト：一部のレンダラーでリスト前の空行欠落
- 閉じていないフェンスコードブロック：閉じバッククォートの忘れ
- 表の整列ノイズ：列数が一致しない行の追加
- プレースホルダーリンク：最終ドキュメントに
https://example.comを残す - HTML の使いすぎ：Markdown 構文でより明確なのに生 HTML に依存
構造チェックがスタイリングより重要
Markdown の品質は主に次についてです。
- スキャンしやすい見出し
- 短い段落
- 明示的なリンク
- 動作するコードサンプル
- データ形状に一致する表
プレビューテーマの色はドキュメントと一緒に移動しません。構造は移動します。
要点
Markdown レビューを軽量なドキュメント QA ステップとして扱います。プレビュー、構造を検査、リンクを検証し、宛先に合ったエクスポート形式を選びます。
Markdown Preview / Markdown to HTML ツールは、ライブプレビュー、見出しアウトライン、リンクリスト、コピー操作を 1 つのワークスペースでこのワークフローをサポートします。