ドキュメント作成ガイドライン (Documentation Style Guide)

本ガイドはプロジェクト内のマークダウンドキュメントの書式を統一するためのルールを定める． 基本方針として Google Markdown Style Guide および markdownlint のルールに準拠し，本ガイドで上書きする項目のみ以下に記載する．

基本フォーマット (Basic Format)

• 文字コード: UTF-8
• 改行コード: LF（推奨）または CRLF
• ファイル拡張子: .md
• ファイル末尾: 空行を 1 行入れて終了する（MD047）

句読点・約物 (Punctuation)

• 句読点: 「，」（全角カンマ）と「．」（全角ピリオド）を使用する．
  • 「、」「。」は使用しない．
• コロン: 半角コロン＋半角スペース「: 」を使用する．
  • NG: 全角コロン「：」，スペースなし「:」
• 括弧: 原則として半角 ( ) を使用する．強調や補足には全角 （ ） や 「 」 も許容する．
• 注釈: 補足には「※」（全角米印）＋半角スペースを使用する．
  • 例: ※ shared は client/server 両方から import して使用する．

見出し (Headings)

ATX スタイル（#）を使用する．Setext スタイル（=== / --- の下線）は使用しない．

• # の後に半角スペースを 1 つ入れる（MD018）
• 見出しの前後に空行を 1 行入れる（MD022）
• 見出しレベルは飛ばさない（MD001）
  • NG: # の直下に ###
• ドキュメント内の #（H1）は 1 つだけにする（MD025）
• 見出しには番号を付けない．マークダウンの見出し構造で階層を表現する．
• 見出しの書式: タイトル (English Title)
  • 例: ## 基本設計 (Basic Design)

見出しレベルの対応表

リスト (Lists)

• 箇条書きには -（半角ハイフン＋半角スペース）を使用する（MD004）
  • * + ・ は使用しない．
• ネストは 2 スペースでインデントする（MD007）
• 順序付きリストは 1. の連番で記述する．
• リストの前後に空行を 1 行入れる（MD032）

強調 (Emphasis)

• 太字: **テキスト** を使用する．__テキスト__ は使用しない（MD050）
• 斜体: *テキスト* を使用する．_テキスト_ は使用しない（MD049）
• 太字斜体: ***テキスト*** を使用する．

コードブロック・インラインコード (Code)

• コードブロックにはフェンス（```）を使用し，言語名を明記する（MD040）

  ```dart
  final name = 'DxNavi';
  ```
  

• インラインコードにはバッククォート ` を使用する．

  • 例: build_runner コマンドを実行する．

• コマンド例にはシェル言語を指定する．

  ```bash
  dart run build_runner build --delete-conflicting-outputs
  ```
  

リンク・画像 (Links & Images)

• リンク: [テキスト](URL) 形式を使用する．
• 画像: ![代替テキスト](パス) 形式を使用し，代替テキストを必ず記述する（MD045）
• プロジェクト内リンクは相対パスを使用する．

テーブル (Tables)

• ヘッダー行とセパレータ行を必ず含める．
• セル内は簡潔に記述し，長い場合はリンクや脚注で補足する．

| 項目 | 説明 |
| --- | --- |
| 名前 | 値 |

空行・余白 (Spacing)

• 連続する空行は最大 1 行までとする（MD012）
• 見出し・リスト・コードブロックの前後に空行を 1 行入れる（MD022, MD031, MD032）
• 行末の不要な空白は削除する（MD009）

その他 (Miscellaneous)

• HTML タグは原則使用しない．マークダウン記法で表現できない場合のみ許容する．
• 1 行の長さに厳密な上限は設けないが，可読性のために適度に改行する．
• ディレクトリ構造の表現にはコードブロック内でツリー記号（├──，│，└──）を使用する．

project/
├── lib/
│   ├── core/
│   └── features/
└── test/