03.Markdown コーディング規約

このドキュメントでは、DevBlueprint内でドキュメントを記述する際の、基本的な記述スタイルと規約を定めます。本規約は、基本的なGFM (GitHub Flavored Markdown) 構文に加え、本プロジェクトで採用する MkDocs (Material for MkDocs) の拡張機能についても解説します。

Note

"ドキュメント規定との関係" このドキュメントは、03.ドキュメント規定/01_基本規定.mdで定められた、より包括的なルールのうち、記述スタイルに関する部分を抜粋・要約したものです。ファイル命名規則や機能IDの利用ルールなどの全体的な規定については、そちらを参照してください。

1. 基本方針 (Guiding Principles)

一貫性: ドキュメント全体で、統一された書式とスタイルを保ちます。
可読性: 人間が読みやすく、理解しやすい記述を心がけます。
表現力: MkDocsの拡張機能を活用し、情報を効果的に伝えます。

2. レイアウトと書式設定 (Layout and Formatting)

手作業でのスタイル遵守は非効率であり、レビューのノイズとなるため、本プロジェクトではツールによる規約の遵守を強制します。各ツールの設定は、リポジトリのルートに配置された .markdownlint.json ファイル（リンター設定）、.prettierrc.json ファイル（フォーマッター設定）、および package.json ファイル（依存関係・スクリプト管理）で一元管理します。また、エディタレベルでの基本的な設定は .editorconfig ファイルで統一します。

フォーマッター: Prettier
- 役割: インデント、リストマーカー、テーブルの整形など、コードの見た目を自動で統一します。
- 運用上の注意: Prettierは日本語のような、単語がスペースで区切られていない文章の自動折り返しを苦手とします。そのため、本プロジェクトでは .prettierrc.json で proseWrap: "preserve" を設定し、文章部分の改行は手動で行うことを推奨します。Prettierはコードブロックやリストなどの構文のみを整形し、手動での改行は維持します。

リンター: markdownlint

役割: フォーマット以外のスタイル違反（例: 見出しレベルの飛び）を検出し、一貫性を保ちます。

推奨設定 (.markdownlint.json): 手動での改行を補助するため、一行の長さをチェックするルール(MD013)を有効にします。ただし、Prettierが整形するコードブロックやテーブルはチェック対象外とします。また、ドキュメント内で使用が許可されているHTMLタグも定義します。

{
    "default": true,
    "MD013": {
        "line_length": 120,
        "code_blocks": false,
        "tables": false
    },
    "MD033": {
        "allowed_elements": [
            "details",
            "summary",
            "br",
            "kbd",
            "mark",
            "abbr",
            "sub",
            "sup",
            "div",
            "span",
            "img",
            "a"
        ]
    }
}

!!! success "CI/CDによる自動チェック" - GitHub Actionsのワークフローにprettier --check **/*.mdおよびmarkdownlint **/*.mdを組み込むことで、Markdownファイルのフォーマットとスタイルが規約に違反しているコードのマージを自動的にブロックします。- VSCode拡張機能を導入し、ファイル保存時に自動でフォーマットとリント修正が適用されるよう設定することを必須とします。

3. 基本的な構文 (Basic Syntax)

3.1. 見出し (Headings)

H1 (#): 各ファイルのタイトルとして、ファイルの先頭に1つだけ使用します。
H2 (##)以降: 本文中のセクションは##から始め、見出しレベルを飛ばさずに、###、####と階層を正しく使用してください。

3.2. 強調 (Emphasis)

太字: **太字** または __太字__
斜体: *斜体* または _斜体_
打ち消し線 (GFM): ~~打ち消し線~~
ハイライト (MkDocs): ==ハイライト==

3.3. リスト (Lists)

順序なしリスト: - 項目A
順序付きリスト: 1. 項目1
タスクリスト (GFM / MkDocs): - [x] 完了、- [ ] 未完了 の形式で、チェックボックス付きのリストを作成します。GitHub上でクリック可能なほか、MkDocsでもpymdownx.tasklist拡張機能により美しく表示可能です。

3.4. リンク、画像、脚注

リンク: [リンクテキスト](https://example.com)
画像: ![代替テキスト](image.png)
脚注 (GFM / MkDocs): テキスト[^1] と [^1]: 脚注内容 の形式で記述します。MkDocsでもfootnotes拡張機能により利用可能です。

3.5. その他

引用: > 引用したいテキスト
水平線: --- または ***
キーボードキー (MkDocs): ++ctrl+alt+del++

4. コードとデータの表現 (Code & Data)

4.1. コードブロック (Code Blocks)

インラインコード: 文中に `const a = 1;` のように記述します。
複数行コードブロック: ```で囲み、言語指定でシンタックスハイライトを有効にします。
コードブロック強化 (MkDocs):
- titleでタイトルを、linenumsで行番号を、hl_linesで特定の行をハイライトできます。
```
```csharp title="Program.cs" linenums="1" hl_lines="3"
using System;

Console.WriteLine("Hello, World!");
```
```

4.2. テーブル (Tables - GFM)

|と-を使って表を作成します。ヘッダー行の区切りにあるコロン(:)で、列のテキスト揃えを指定できます。

| 左揃え | 中央揃え | 右揃え |
| :----- | :------: | -----: |
| cell   |   cell   |   cell |

5. MkDocs拡張構文によるリッチ表現

5.1. 注釈 (Admonitions)

補足情報や警告などを、!!! note "タイトル" の形式で、目立つブロックとして表示します。
note, warning, danger, tip, success, example などを文脈に応じて使い分けます。

5.2. タブ (Content Tabs)

関連する複数の情報を、=== "タブのタイトル" で定義し、タブで切り替えて表示します。OSごとの手順や多言語コードの提示に有効です。
タブ内で他のMarkdown要素（コードブロック、注釈など）も利用可能です。

=== "C#"
!!! note "C#の例"
`csharp
    Console.WriteLine("Hello, World!");
    `

=== "Python"
!!! note "Pythonの例"
`python
    print("Hello, World!")
    `

5.3. 詳細・折りたたみ (Details)

??? note "タイトル" の形式で、クリックすると展開されるコンテンツを作成できます。長いコードや補足情報の格納に便利です。???+ で最初から開いた状態にもできます。

5.4. 図表 (Diagrams with Mermaid)

```mermaid ブロック内にテキストで記述することで、フローチャートやシーケンス図などを描画できます。

5.5. アイコンとボタン (Icons & Buttons)

アイコン: :icon-name: (例: :fontawesome-brands-github:)
ボタン: [ボタンテキスト](リンク){ .md-button }

5.6. 属性リストと機能ID (Attribute Lists & Requirement IDs)

見出しなどの要素に、{ #my-id .my-class } の形式でIDやCSSクラスを直接付与できます。
これを利用し、要求仕様書でIDを定義する際は、見出しに{ #REQ-XXX-X.X }形式でIDを付与し、直接リンク可能なアンカーを作成します。