Markdown ドキュメンテーション

目次

• 概要
• 使用場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

標準 Markdown および GitHub Flavored Markdown (GFM) を使用して、よくフォーマットされた読みやすいドキュメンテーションを作成するための Markdown 構文とベストプラクティスをマスターします。

使用場面

• README ファイル
• ドキュメンテーションページ
• GitHub/GitLab wiki
• ブログ投稿
• テクニカルライティング
• プロジェクトドキュメンテーション
• コメントのフォーマッティング

クイックスタート

• コメントのフォーマッティング

# H1 Header

## H2 Header

### H3 Header

#### H4 Header

##### H5 Header

###### H6 Header

# Alternative H1

## Alternative H2

リファレンスガイド

references/ ディレクトリに詳細な実装例があります：

ガイド	内容
Text Formatting	テキストフォーマッティング
Lists	リスト
Links and Images	リンクと画像、コードブロック、テーブル
Extended Syntax (GitHub Flavored Markdown)	拡張構文 (GitHub Flavored Markdown)
Collapsible Sections	折りたたみセクション、シンタックスハイライト、バッジ
Alerts and Callouts	アラートとコールアウト
Mermaid Diagrams	Mermaid ダイアグラム

ベストプラクティス

✅ すべきこと

• 説明的なリンクテキストを使用する
• 長いドキュメントに目次を含める
• 画像に alt テキストを追加する
• 言語指定付きのコードブロックを使用する
• 行を 80～100 文字以下に保つ
• 内部ドキュメントに相対リンクを使用する
• ビルドステータス、カバレッジなどのバッジを追加する
• 例とスクリーンショットを含める
• セマンティックな改行を使用する
• すべてのリンクを定期的にテストする

❌ してはいけないこと

• "クリック" をリンクテキストとして使用する
• 画像に alt テキストを忘れる
• HTML と Markdown を不必要に混在させる
• ローカルファイルに絶対パスを使用する
• 改行なしでテキストの塊を作成する
• コードブロックの言語指定をスキップする
• テキストコンテンツに画像を使用する (アクセシビリティの問題)