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

本ガイドはプロジェクト内のマークダウンドキュメントの書式を統一するためのルールを定める．
基本方針として [Google Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) および [markdownlint](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) のルールに準拠し，本ガイドで上書きする項目のみ以下に記載する．

## 基本フォーマット (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)`

### 見出しレベルの対応表

| レベル | 記法 | 用途 |
| --- | --- | --- |
| H1 | `#` | ドキュメントタイトル（ファイルに 1 つ） |
| H2 | `##` | 大見出し（セクション） |
| H3 | `###` | 中見出し（サブセクション） |
| H4 | `####` | 小見出し（トピック） |

## リスト (Lists)

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

## 強調 (Emphasis)

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

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

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

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

- インラインコードにはバッククォート `` ` `` を使用する．
  - 例: `build_runner` コマンドを実行する．
- コマンド例にはシェル言語を指定する．

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

## リンク・画像 (Links & Images)

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

## テーブル (Tables)

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

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

## 空行・余白 (Spacing)

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

## その他 (Miscellaneous)

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

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