ディレクトリの並べ方

a-git2docs の contents/ は任意の階層をサポートしています。ディレクトリの切り方 = サイトの構造そのものです。

フラットに書くか、階層化するか

小さな docs（記事数 20 本以下くらい）なら、トップレベルのセクションに平置きする フラット構成 が最もシンプルです。

contents/
├── getting-started/
│   ├── introduction.md
│   └── installation.md
└── guide/
    ├── writing-articles.md
    └── customization.md

記事が増えて特定セクションがごちゃついてきたら、サブディレクトリで章立て します。

contents/
└── guide/
    ├── writing-articles.md
    ├── basics/
    │   ├── directory-layout.md   ← このページ
    │   └── url-design.md
    └── advanced/
        └── customization.md

サブディレクトリの扱い

• URL はそのままディレクトリ階層になります: /guide/basics/directory-layout.html
• 左サイドバーにはサブディレクトリのラベルが表示され、その配下の記事が一覧されます
• サブディレクトリのラベルを日本語にしたい場合は config/categories.yaml に定義を書きます

categories:
  guide:
    label: "ガイド"
    categories:
      basics:
        label: "基本"
      advanced:
        label: "応用"

おすすめの切り方

• セクション (contents/guide/) = 読者の目的別の大分類
• サブセクション (contents/guide/basics/) = セクション内で 5 本以上になったら切る
• さらに深い階層 (contents/guide/basics/advanced/) = 可能だが、基本は 2 階層までに留めた方が迷いません