# リポジトリ設定

自動検出だけでは足りない場合に .prosefly/config.yaml でコンテンツスペースを明示的に定義します。

Prosefly はリポジトリをスキャンするとき、対応するフレームワークの設定を自動検出します。多くの Astro、Starlight、Fumadocs、Lotus、Dahlia サイトでは追加の設定ファイルは必要ありません。

独自ローダー、モノレポの構成、生成された設定、静的ファイルから安全に特定できない構成を使っている場合は、`.prosefly/config.yaml` を使用できます。このファイルはリポジトリにコミットされ、記載したスペース設定の正規の定義になります。

## 設定ファイルを追加する場合

まず通常のスキャンを試してください。スキャンで正しいコンテンツディレクトリを見つけられない場合や、静的なスキーマに現れない情報を明示する必要がある場合に設定ファイルを追加します。たとえば次のような場合です。

- アプリケーションのサブディレクトリにあるスペース;
- 異なるプロファイルやファイル形式を使う複数の Markdown コレクション;
- 別々のディレクトリに保存された多言語コンテンツ;
- Prosefly で編集したい独自の frontmatter フィールド;
- 自動検出でコレクションと関連付けられない、対応済みの標準ナビゲーション設定。

エディターはリポジトリのコードを実行しません。そのため、サイトのビルドが成功していても、動的なローダーには明示的な定義が必要になることがあります。

## ファイルの場所と反映方法

リポジトリのルートに次のファイルを作成します。

```text
.prosefly/config.yaml
```

追加または変更したら、もう一度 **リポジトリをスキャン** してください。Prosefly はスペースを作成・更新する前にファイルを検証します。このファイルから読み込まれたスペースは設定管理になります。名前、パス、プロファイル、フレームワーク、公開方法は Git で変更してから再スキャンします。下書きとコンテンツの編集は、公開するまで Prosefly に保存されます。

## 最小構成

トップレベルには `version: 1` と、少なくとも 1 つのスペースが必要です。パスはリポジトリのルートからの相対パスです。ただしコレクションの `directory` は、そのスペースの `root` からの相対パスになります。

```yaml
version: 1
spaces:
  - name: Documentation
    root: apps/docs
    publicDir: public
    profile: starlight
    framework: astro
    publishMode: pull-request
    collections:
      - name: Docs
        directory: src/content/docs
        extensions: [md, mdx]
        fields:
          - name: title
            label: Title
            type: string
            required: true
```

### スペースの項目

`spaces` の各項目では次を指定できます。

- `name`: Prosefly に表示するスペース名;
- `root`: アプリケーションディレクトリ。リポジトリのルートは `.`;
- `publicDir`: 公開ファイルのディレクトリ。既定値は `public`;
- `publicImageDir`: `publicDir` 内の画像ディレクトリ。既定値は `images`;
- `profile`: `prosefly`、`fumadocs`、`starlight`、`generic` のいずれか;
- `framework`: `astro`、`nextjs`、`react-router`、`tanstack-start`、`waku`、`hugo`、`unknown` のいずれか;
- `publishMode`: `commit` または `pull-request`;
- `collections`: 1 つ以上のコンテンツ定義。

`framework` とスペースの `profile` は既定の編集動作を定義します。異なるディレクトリで異なるコンポーネント構文を使う場合は、コレクション単位で profile を上書きできます。

## コレクションの項目

各コレクションには `name`、`directory`、`extensions`、`fields` が必要です。

```yaml
collections:
  - name: Blog
    directory: src/content/blog
    extensions: [md, mdx]
    profile: prosefly
    fields:
      - { name: title, label: Title, type: string, required: true }
      - { name: date, label: Date, type: string, format: iso-date }
      - name: tags
        label: Tags
        type: array
        items:
          type: string
        widget: tags
```

対応する拡張子は `md`、`mdx`、`yaml`、`yml`、`json` です。Markdown コレクションとリソースコレクションは別々に定義してください。1 つのコレクションで文書形式とリソース形式を混在させることはできません。リソースファイルは `generic` profile を使い、文書ナビゲーションはありません。

多言語 Markdown では、言語ディレクトリをコレクション内に置き、含めるディレクトリと言語コードを宣言します。

```yaml
collections:
  - name: Docs
    directory: content
    includeDirectories: [en, zh-cn, ja]
    locales:
      - { locale: en, directory: en }
      - { locale: zh-CN, directory: zh-cn }
      - { locale: ja, directory: ja }
    extensions: [md, mdx]
    fields: []
```

### fields の構文

`fields` の各項目は、frontmatter またはリソースの 1 つのプロパティを表します。`name` はソースファイルの key と一致させ、`label` はエディターに表示する名前です。既存の下書きやインデックス項目との対応を保つため、フィールド名は安定させてください。

| オプション    | 用途                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `name`        | ソース内のプロパティ key。名前付きフィールドでは必須です。                                                    |
| `type`        | 値の形状。`string`、`number`、`boolean`、`date`、`object`、`array`、`reference`、`enum`、`union` を使えます。 |
| `label`       | エディターに表示する任意のラベル。                                                                            |
| `required`    | key の存在を必須にします。空の文字列やリストを必須にするものではありません。                                  |
| `default`     | 新しいエントリの作成時に使う値。既存のソースファイルは書き換えません。                                        |
| `nullable`    | 明示的な `null` を許可します。                                                                                |
| `format`      | `iso-date`、`iso-datetime`、`url`、`email`、`uuid` などの文字列形式。                                         |
| `validations` | `min`、`max`、`integer`、日時オプションなど、型ごとの制限。                                                   |
| `widget`      | `textarea`、`tags`、`select`、`image-src` などの互換エディターコントロール。保存される型は変えません。        |

オブジェクトの名前付き子フィールドには `fields`、配列には `items`、enum には `values`、参照には `collection`、union には `variants` を使います。

```yaml
fields:
  - name: title
    label: Title
    type: string
    required: true
    validations:
      min: 1
  - name: publishedAt
    label: Published at
    type: string
    format: iso-datetime
  - name: tags
    label: Tags
    type: array
    items:
      type: string
    widget: tags
```

`required` は key の存在を確認します。文字列やリストを空にできないようにするには `validations.min` を使います。default は定義に一致する必要があり、新しいエントリにだけ適用されます。`widget` は編集コントロールだけを変え、ソースで受け入れる値は変えません。

## ナビゲーションを宣言する

書き込み可能な標準ナビゲーションがない場合や、コンテンツだけを公開する場合は `navigation` を省略できます。この関連付けは Space の最上位ではなく、対象の Collection に記述します。JSON ナビゲーションではファイルとオブジェクトの key をその Collection に関連付けます。

```yaml
collections:
  - name: Docs
    directory: src/content/docs
    extensions: [md, mdx]
    fields: []
    navigation:
      provider: json
      configPath: theme.config.json
      key: docsNav
```

対応する標準インテグレーションでは、provider、設定ファイルのパス、サイトで使用するバージョンを指定します。パスは Space の `root` を基準に解決されるため、新しい Space でアプリケーションルートを別途指定する必要はありません。Starlight では、上で宣言した Astro 設定と Collection ディレクトリを使用します。

```yaml
collections:
  - name: Docs
    directory: src/content/docs
    extensions: [md, mdx]
    fields: []
    navigation:
      provider: starlight
      configPath: astro.config.mjs
      version: 0.37.0
```

provider は実際のサイト設定と一致させてください。Prosefly はナビゲーションの変更を文書の変更と一緒にレビューします。スキャン中にフレームワーク設定を書き換えることはありません。

## スキャンとトラブルシューティング

1. `.prosefly/config.yaml` を Prosefly がスキャンするブランチにコミットします。
2. **リポジトリをスキャン** を実行し、検出されたスペースとコレクションを確認します。
3. profile、パス、フィールド、ナビゲーションの関連付けを確認します。
4. 文書を開きます。既存のスペースを更新した場合は、インデックスを再構築してください。

検証に失敗した場合は、インデント、相対パス、スペース root の重複、対応する拡張子、必須の `publishMode` を確認してください。設定エラーでリポジトリのコードが実行されたり、Git ファイルが変更されたりすることはありません。

Prosefly が編集できないナビゲーション形式を使う場合でも、コレクション定義を残してコンテンツのみの公開を選べます。ナビゲーションの動作は[リポジトリとコンテンツスペース](/docs/ja/repositories-and-spaces/)で、最終 diff は[公開レビュー](/docs/ja/publishing/#review-content-and-navigation-together)で確認できます。