コンテンツにスキップ

02.YAML コーディング規約

このドキュメントでは、YAML (YAML Ain't Markup Language) 形式のデータを記述する際のスタイルと規約を定めます。 主に、mkdocs.ymlやGitHub Actionsのワークフローファイル (.yml) などでの利用を想定しています。

インデントが構文そのものである

YAMLにおいて、インデントは単なる見た目ではなく、データの階層構造を定義するための構文そのものです。 インデントの誤りは、アプリケーションの予期せぬ動作や、設定の読み込みエラーに直結します。

1. 基本フォーマット

  • ファイル拡張子: .yml を推奨します。（.yamlでも可だが、プロジェクト内で統一）
  • 文字エンコーディング: UTF-8を標準とします。

2. スタイルガイド

一貫性と可読性、そしてエラーの防止のため、以下のスタイルを厳格に守ってください。

  • インデント:
    • 半角スペース2つを標準とします。
    • タブ文字は絶対に使用しないでください。 タブとスペースの混在は、見た目では分からない致命的なエラーの最大の原因です。
  • ブロックシーケンス (リスト/配列):
    • ハイフン (-) の後には、必ず半角スペースを1つ入れます。
    • 良い例: 
      - item1
- item2
    • 悪い例: 
      -item1 # ハイフンの後にスペースがない
  • 文字列 (Strings):
    • 通常、文字列をクォーテーションで囲む必要はありません。
    • ただし、:、{}、[]などの特殊文字を含む場合や、意図しない解釈（例: noがブーリアン値のfalseになる）を防ぎたい場合は、シングルクォーテーション (') で囲むことを推奨します。
  • ブーリアン値 (Booleans):
    • true / false を使用します。（True, False, yes, noなどは避ける）
  • 空の値:
    • nullまたはチルダ (~) を使用します。

3. 自動フォーマットとリンティング

  • PrettierはYAMLのフォーマットにも対応しており、利用を強く推奨します。インデントやスペースのスタイルを自動で統一してくれます。
  • yamllintのようなリンターを導入し、文法エラーやスタイル違反をCI/CDでチェックすることも有効です。

4. ドキュメントの構成

  • ドキュメントの開始と終了:
    • YAMLドキュメントの開始は---で、終了は...で明示することができます。必須ではありませんが、ドキュメントの境界を明確にしたい場合に利用します。

  • コメント:

    • # から行末までがコメントとなります。設定値の意味や、変更する際の注意点などを記述するために活用してください。
    # サイト全体の情報
site_name: 'DevBlueprint' # ここにはサイトのタイトルを記述