---
title: ページを書く
order: 2
---

## ページを書く

コンテンツはすべて `pages/<lang>/` の下に Markdown ファイルとして配置します。

### 対応する Markdown 記法

docs-gen は標準の [CommonMark](https://commonmark.org/) に加えて、以下の拡張をサポートしています:

- **テーブル** — パイプ区切りのテーブル（列の揃え指定可）
- **取り消し線** — `~~削除されたテキスト~~`
- **タスクリスト** — `- [ ] 未完了` と `- [x] 完了`

見出しにはアンカーリンク用の `id` 属性が自動で付与され、コードブロックはテーマに応じたシンタックスハイライトが適用されます。

### フロントマター

`.md` ファイルの先頭には必ず YAML フロントマターを書きます:

```yaml
---
title: "ページタイトル"
order: 1
---
```

| フィールド | 必須 | 説明                                           |
|-----------|------|-----------------------------------------------|
| `title`   | はい | ページタイトル（サイドバーとブラウザタブに表示）    |
| `order`   | いいえ | セクション内の並び順（デフォルト: `0`）          |
| `status`  | いいえ | `"draft"` にすると DRAFT バナーが表示される      |

### セクションとナビゲーション

言語ディレクトリ配下のサブディレクトリが**セクション**になり、サイドバーナビゲーションを持ちます:

```
pages/en/
├── index.md              # ホームページ（サイドバーなし）
└── guide/
    ├── index.md          # セクション見出し
    ├── 01-intro.md       # order → ファイル名の順にソート
    └── 02-deploy.md
```

- セクションの `index.md` の title がサイドバーの見出しになります。
- セクション内の他のページはその下に一覧表示されます。
- ルートの `index.md` はポータルレイアウト（サイドバーなし）で表示されます。

### 新しいページを追加する

1. `.md` ファイルを作ります（例: `pages/en/guide/03-tips.md`）。
2. フロントマターに `title` と `order` を書きます。
3. サイドバーに自動的に表示されます。

### ページ間の相対リンク

各ページはクリーンURLのために独自のディレクトリにレンダリングされます（例: `01-getting-started.md` → `01-getting-started/index.html`）。相対リンクの書き方に影響するので注意してください。

| リンク元                      | リンク先        | 書き方                                    |
|------------------------------|----------------|------------------------------------------|
| ページ（例: `01-intro.md`）   | 同階層のページ   | `../02-deploy/`（一階層上がってから指定）   |
| セクションの `index.md`       | 子ページ        | `01-intro/`（直接指定）                    |

**例 — 同階層リンク:**

```markdown
次へ: [ページを書く](../02-writing-pages/)
```

**例 — index から子ページ:**

```markdown
[はじめよう](01-getting-started/)
```

### 画像とファイル（コロケーション）

画像などのファイルをMarkdownページと同じディレクトリに置くと、ビルド時に自動的に正しい場所にコピーされます。

```text
pages/ja/guide/
├── index.md
├── 01-intro.md
├── diagram.png        ← このセクションに配置
└── screenshot.jpg
```

**セクションの `index.md` から参照する場合:**

```markdown
![Diagram](./diagram.png)
```

**通常のページ（例: `01-intro.md`）から参照する場合:**

各ページは独自のディレクトリにレンダリングされるため（`01-intro/index.html`）、`../` で一階層上がります:

```markdown
![Screenshot](../screenshot.jpg)
```

### `static/` ディレクトリ

プロジェクトルートの `static/` ディレクトリは、サイト全体で共有するファイル（favicon、ロゴなど）を置く場所です。`static/` 内のファイルはそのまま出力ルートにコピーされます。

```text
my-docs/
├── static/
│   ├── favicon.svg       → /favicon.svg
│   └── logo.png          → /logo.png
└── pages/
```

サイト全体で使うファイルには `static/` を、特定のページやセクションに属するファイルにはコロケーション（上記）を使います。

### 画像のサイズ指定

画像はデフォルトでコンテンツ幅に収まります（`max-width: 100%`）。表示サイズを変えたいときは、画像URLに `#fragment` を付けます:

```markdown
![Screenshot](./screenshot.png#small)
![Screenshot](./screenshot.png#half)
![Screenshot](./screenshot.png#large)
```

| Fragment | 最大幅 |
|----------|--------|
| *(なし)* | 100%   |
| `#small` | 300px  |
| `#half`  | 50%    |
| `#large` | 80%    |

画像を中央揃えにするには、fragmentに `-center` を付けます:

```markdown
![Screenshot](./screenshot.png#half-center)
```

`#center` だけでもフル幅の中央揃えになります。

### 多言語での画像共有

多言語サイトでは、デフォルト言語（`langs` の最初のエントリ）のディレクトリにある画像が他の言語でも自動的に使えます。言語固有の画像（ローカライズされたスクリーンショットなど）がある場合だけ、その言語のディレクトリに置いてください。

```text
pages/
├── en/
│   └── guide/
│       ├── index.md
│       └── screenshot.png   ← 全言語で共有される
└── ja/
    └── guide/
        └── index.md         ← コピーなしで screenshot.png を参照できる
```

同名のファイルがその言語のディレクトリにあれば、そちらが優先されます。

次へ: [設定](../03-configuration/)
