コンテンツにスキップ

DevBlueprint

Markdown

03.Markdown コーディング規約

このドキュメントでは、DevBlueprint内でドキュメントを記述する際の、Markdownの基本的な記述スタイルと規約を定めます。一貫性のあるスタイルは、ドキュメントサイト全体の見た目を統一し、可読性を高めます。

ドキュメント規則との関係

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

1. 基本方針

自動フォーマット: Markdownファイルも、Prettierによる自動フォーマットの対象とします。これにより、インデントやリストの記号などが自動で統一されます。
方言: GitHub Flavored Markdown (GFM) を基本とします。

2. スタイルガイド

2.1. 見出し (Headings)

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

2.2. 強調 (Emphasis)

太字: アスタリスク2つで囲みます (**太字**)。
斜体: アスタリクス1つで囲みます (*斜体*)。
打ち消し線: チルダ2つで囲みます (~~打ち消し線~~)。

2.3. リスト (Lists)

順序なしリスト: ハイフン (-) を使用し、インデントには半角スペース2つまたは4つを使用します。（Prettierが自動で統一します）
順序付きリスト: 1. のように、数字とドットで記述します。

2.4. リンク (Links)

相対パス: ドキュメント内の他ページへのリンクは、必ず相対パスで記述します。
- 例: [01.共通コーディング原則](../../01_共通規則/01_共通コーディング原則.md)
リンクテキスト: 01.ドキュメント規則で定められた命名スタイルに従います。

2.5. コード (Code)

インラインコード: バッククォート (`) で囲みます。（例: const a = 1;）
コードブロック: トリプルバッククォート (```) で囲み、必ず言語指定を行ってシンタックスハイライトを有効にします。
```
```csharp
public class MyClass { }
```

2.6. テーブル (Tables)

Markdownの標準的なテーブル構文で記述します。Prettierがカラムの幅を自動で整形してくれます。

2.7. 注釈 (Admonition)

Material for MkDocsの注釈機能を積極的に活用し、読者の注意を引くべき箇所を明確にします。
種類: note, info, tip, success, warning, danger, example, quote などを適切に使い分けます。
```
!!! warning "注意"
    この操作は元に戻せません。
```

2.8. 図表 (Diagrams)

フローチャートやシーケンス図などを記述する場合は、Mermaid構文を利用します。
```
```mermaid
graph TD
    A --> B;
```

3. リンティング

markdownlintの利用を推奨します。
VSCode拡張機能を導入することで、見出しの階層が飛んでいる、リストのインデントが不適切である、といったスタイル違反をリアルタイムで検出できます。