Markdownはソースと表示を分離する
Markdownファイルは通常のテキストで、通常は.md拡張子で保存されます。特別なアプリケーションがなくてもソースを理解できます。一方、GitHub、ドキュメントツール、静的サイトジェネレーター、エディターは、タイポグラフィやナビゲーションを備えた形でレンダリングできます。
この分離こそが中心的な考え方です。作成者は小さな語彙で意味を記述し、出力先が結果の見た目を決めます。同じREADMEが、ターミナルでもコードレビューでも、洗練されたドキュメントサイトでも快適に読めるのです。
# Deploying the API Run the **smoke tests** before release. - Verify health checks - Review error rates - Tag the build
技術文書作成にMarkdownが優れている理由
Markdownは執筆とレビューの距離を最小化します。ソースに視覚的なノイズが少なく、変更が行単位の有用な差分になります。また、ファイルは説明対象のコードや設定の隣に置くことができます。
- 移植性：プレーンテキストは特定のベンダーやエディターに依存しません。
- 差分のしやすさ：バージョン管理で変更を容易に確認できます。
- 組み立てやすさ：ドキュメントツールがHTML、PDF、またはヘルプコンテンツに変換できます。
- 可読性：レンダリング前でもソース自体が役立ちます。
- 自動化しやすさ：スクリプトでリンク、見出し、例、スタイル規則を検査できます。
Markdownにはコア構文と複数のフレーバーがある
共通のコアは、段落、見出し、強調、リンク、画像、引用、リスト、コードをカバーしています。プラットフォームが拡張機能を追加することもよくあります。たとえば、GitHub Flavored Markdownは開発者のワークフローでテーブル、タスクリスト、取り消し線を広めました。
拡張機能は便利ですが、移植性も依然として重要です。単純な見出しはほぼどこでも動作しますが、プラットフォーム固有の図表ブロックは動作しない可能性があります。ドキュメントをツール間で移動する必要がある場合は、出力先で構文をテストし、重要な意味は通常のテキストで保持してください。
Markdownが使われる場面
Markdownは、コンテンツをソフトウェアに近づけておきたい場面や、テキストベースのワークフローでやり取りする場面で広く使われています。エンジニアリング以外でも、精密なページレイアウトよりも耐久性があり負担の少ないソースが重要である場合に役立ちます。
- README、コントリビューションガイド、変更履歴、リリースノート
- APIリファレンス、チュートリアル、ランブック、アーキテクチャ決定記録
- Issueの説明、プルリクエスト、コメント、チームのナレッジベース
- 静的ウェブサイト、ブログ、製品ドキュメント、社内ハンドブック
- 公開前に整理が必要なメモや変換済みドキュメント
Markdownが想定していない用途
Markdownはページレイアウト形式ではありません。正確なフォント、段組み、フローティングオブジェクト、印刷用ページ送り、複雑なインタラクティブコンポーネントは、他のシステムの領域です。変換されたPDFやプレゼンテーションは、視覚的な構成よりも有用なテキストの方が残りやすいです。
また、プレーンテキストであるからといって自動的に安全というわけではありません。レンダラーはリンクや任意の生HTMLを信頼できないものとして扱う必要があります。優れたエディターはプレビュー出力をサニタイズし、公開パイプラインは独自のセキュリティポリシーを適用します。