docs: add pages-as-files feature documentation

Author: klikli-dev

versioned_docs/version-26.1.2/basics/page-types/page-types.md

@@ -11,7 +11,11 @@ The following attributes are available for all page types
 ### **type** (String, _mandatory_)
 
 The type of page, it determines which loader is used to load the json data and how the page will be displayed.
-Needs to be fully qualified `domain:name`, e.g. `modonomicon:text`. 
+Needs to be fully qualified `domain:name`, e.g. `modonomicon:text`.
+
+### **id** (String, _optional_)
+
+A string to uniquely identify the page within the entry it belongs to. Used when pages are defined as separate files to match the page to its entry. Also allows linking to specific pages and is more robust than using the page's array index when pages are reordered or removed.
 
 ### **anchor** (String, _optional_)
 

versioned_docs/version-26.1.2/basics/structure/entries.md

@@ -142,6 +142,39 @@ A parent connection does not imply an unlock condition or any logical dependency
 
 Pages are JSON Objects that define the actual book content. See [Page Types](../page-types/page-types.md) for the available types of pages.
 
+#### Pages as Files
+
+By default, pages are generated as separate JSON files instead of being inline in the entry JSON. This makes it easier to manage large entries with many pages.
+
+**File structure:**
+
+The entry JSON lives alongside a `pages/` subdirectory that shares the entry's name:
+```
+data/<mod_id>/modonomicon/books/<book_id>/entries/
+  <category_id>/
+    <entry_name>.json          ← entry definition (no inline pages)
+    <entry_name>/
+      pages/
+        <page_id>.json         ← individual page files
+```
+
+For example, the entry `data/modonomicon/modonomicon/books/demo/entries/features/custom_icon.json` 
+has its pages in `data/modonomicon/modonomicon/books/demo/entries/features/custom_icon/pages/`.
+
+Each page file contains a single page JSON object:
+```json
+{
+  "id": "intro",
+  "type": "modonomicon:text",
+  "title": "book.modonomicon.demo.features.custom_icon.intro.title",
+  "text": "book.modonomicon.demo.features.custom_icon.intro.text"
+}
+```
+
+The `id` attribute uniquely identifies the page within the entry and is used to match page files to the entry during loading. The `type` attribute determines how the page renders (e.g., `modonomicon:text`, `modonomicon:spotlight`).
+
+**Datagen:** Pages-as-files is the default behavior. Use `BookEntryModel#withGeneratePagesAsFiles(false)` to generate pages inline in the entry JSON instead.
+
 ### **category_to_open** (ResourceLocation, _optional_)
 
 The resource location to the category that should be opened when this entry is clicked.