リポジトリ設定

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

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

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

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

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

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

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

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

.prosefly/config.yaml

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

最小構成

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

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 が必要です。

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 では、言語ディレクトリをコレクション内に置き、含めるディレクトリと言語コードを宣言します。

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 はエディターに表示する名前です。既存の下書きやインデックス項目との対応を保つため、フィールド名は安定させてください。

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

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 に関連付けます。

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 ディレクトリを使用します。

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 が編集できないナビゲーション形式を使う場合でも、コレクション定義を残してコンテンツのみの公開を選べます。ナビゲーションの動作はリポジトリとコンテンツスペースで、最終 diff は公開レビューで確認できます。