feat: document Index Fields feature

content/docs/collection-folder.md

@@ -75,6 +75,43 @@ collections:
       - {label: "Contenido", name: "body", widget: "markdown"}
 ```
 
+### Index Files
+
+Folder collections can also include the `index_file` configuration, letting you define separate fields and editor settings for entries matching a given pattern that differs from the regular entries in a collection.
+
+This is particularly helpful when you want to mix regular content and shared information about the entire collection. For example, a list of blog posts and their shared category name and description.
+
+The `index_file` option accepts an object with the following properties:
+
+* `pattern` (**required**): A regular expression string used to identify the index files by their slug.
+* `fields`: An optional list of fields to use for entries that match the pattern. When omitted, index file entries use the same fields as regular entries.
+* `editor`: An optional editor configuration object. Supports a `preview` boolean to enable or disable the preview pane for index file entries independently from the rest of the collection.
+
+Example:
+
+```yaml
+collections:
+  - name: "posts"
+    label: "Posts"
+    folder: "_posts"
+    create: true
+    index_file:
+      pattern: _index
+      editor:
+        preview: false
+      fields:
+        - {label: "Title", name: "title", widget: "string"}
+        - {label: "Body", name: "body", widget: "markdown"}
+    fields:
+      - {label: "Title", name: "title", widget: "string"}
+      - {label: "Draft", name: "draft", widget: "boolean", default: false}
+      - {label: "Publish Date", name: "date", widget: "datetime"}
+      - {label: "Body", name: "body", widget: "markdown"}
+```
+
+In this example, entries with a slug matching `_index` (e.g. `_index.md`) will use a simplified set of fields with just a title and body, and will have the editor preview disabled. All other entries in the collection use the regular fields list.
+
+**Limitation:** Currently, you cannot convert an index file into a content file or vice versa. To workaround this, remove the file and add a new one with the desired slug and contents.
 
 ### Folder Collections Path
 

content/docs/configuration-options.md

@@ -259,6 +259,7 @@ The `collections` setting is the heart of your Decap CMS configuration, as it de
 * `description`: optional text, displayed below the label when viewing a collection
 * `files` or `folder` (requires one of these): specifies the collection type and location; details in [File Collections](https://decapcms.org/docs/collection-file) and [Folder Collections](https://decapcms.org/docs/collection-folder)
 * `filter`: optional filter for `folder` collections; details in [Folder Collections](https://decapcms.org/docs/collection-folder)
+* `index_file`: optional configuration for `folder` collections to define separate fields and editor settings for entries matching a given pattern; details in [Folder Collections](https://decapcms.org/docs/collection-folder#index-files)
 * `create`: for `folder` collections only; `true` allows users to create new items in the collection; defaults to `false`
 * `publish`: for `publish_mode: editorial_workflow` only; `false` hides UI publishing controls for a collection; defaults to `true`
 * `hide`: `true` hides a collection in the CMS UI; defaults to `false`. Useful when using the relation widget to hide referenced collections.