docs: add documentation version for 1.21.10

Author: klikli-dev

docs/advanced/item-properties.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 60
+---
+
+# Item Properties
+
+Item properties let item models change depending on runtime conditions. Modonomicon exposes a property you can use to change a book item's model depending on whether the Modonomicon UI is open for the player.
+
+## Open state
+
+### 1) Custom book item requirement
+
+This only works when using a custom book item (an item you register yourself). It does *not* work with the automatically generated book item.
+
+### 2) Java helper / Occultism example
+
+Occultism demonstrates a common approach: their [GuideBookItem](https://github.com/klikli-dev/occultism/blob/version/1.21.1/src/main/java/com/klikli_dev/occultism/common/item/tool/GuideBookItem.java) shows how to use `ModonomiconCustomItemBase` to obtain the same default Modonomicon behavior on your own item. `ModonomiconCustomItemBase` handles the DataComponents and registers the item property for you, which is why using it is recommended.
+
+:::tip
+Tip: extending `ModonomiconCustomItemBase` is the easiest route because it wires up the required DataComponents handling and property registration automatically.
+:::
+
+### 3) Registering the item
+
+Register your custom item as you would any other item. For reference see Occultism's item registration (their [OccultismItems](https://github.com/klikli-dev/occultism/blob/version/1.21.1/src/main/java/com/klikli_dev/occultism/registry/OccultismItems.java#L55) class) — the book item is just a normal item registration.
+
+### 4) Disable auto-generated book and datagen
+
+If you normally generate a book item from datagen, disable that generation and tell Modonomicon about your custom item. In `book.json` set:
+
+```json
+"generate_book_item": false,
+"custom_book_item": "<your_item_id>"
+```
+
+Or in datagen via the `BookModel` helpers:
+
+```java
+.withGenerateBookItem(false)
+.withCustomBookItem(this.modLoc("<your_item_id>"))
+```
+
+### 5) Client item: changing the model when open
+
+Modonomicon exposes the ConditionalItemModelProperty `modonomicon:is_book_open`. The value is `true` while the Modonomicon UI is open for the player and `false` otherwise. Use that in your client item to change model when the book is open. The following example shows a green book when closed and a purple book when open:
+
+```json
+{
+  "model": {
+    "type": "minecraft:condition",
+
+    "property": "modonomicon:is_book_open",
+
+    "on_true": {
+      "type": "minecraft:model",
+      "model": "modonomicon:item/modonomicon_purple"
+    },
+    "on_false": {
+      "type": "minecraft:model",
+      "model": "modonomicon:item/modonomicon_green"
+    }
+  }
+}
+```
+
+:::info
+See also https://docs.neoforged.net/docs/1.21.4/resources/client/models/items
+:::
+
+:::tip
+This example points at the `modonomicon:item/modonomicon_purple` and `modonomicon:item/modonomicon_green` models shipped by Modonomicon. If you want to use your own open-state model make sure the model JSON is present and loaded (register the model file or force-load it). A texture alone is not enough — Minecraft loads models, not raw textures.
+:::

versioned_docs/version-1.21.10/advanced/advanced.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 30
+---
+
+# Advanced

versioned_docs/version-1.21.10/advanced/custom-conditions.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 40
+---
+
+# Custom Conditions
+
+Mods can add custom conditions that can be used to lock entries or categories. To this end you need to:
+
+1. Create ResourceLocation for the new condition (e.g. "mymod:my_condition")
+2. Create a custom condition class
+3. Register the custom condition 
+4. For datagen: create a condition model class
+5. Finally use the condition in your book
+
+:::tip
+
+The ResourceLocation is what you will use in your entries and categories to gate them behind your custom condition. 
+
+:::
+
+## Condition Class
+
+Conditions need to extend `BookCondition` in the package `com.klikli_dev.modonomicon.book.conditions`.   
+In addition to implementing the interface methods that your IDE will suggest you need two static methods `fromJson` and `fromNetwork` which you will need when registering the condition.
+
+in `getType()` return your ResourceLocation.
+
+See https://github.com/klikli-dev/modonomicon/tree/version/1.21.1/common/src/main/java/com/klikli_dev/modonomicon/book/conditions/BookAdvancementCondition.java for an example condition.
+
+## Condition Registration
+
+To register the condition call LoaderRegistry.registerConditionLoader(...).   
+For the BookAdvancementCondition this call looks as follows: `registerConditionLoader(Condition.ADVANCEMENT, BookAdvancementCondition::fromJson, BookAdvancementCondition::fromNetwork);`
+
+This needs to be called from both the client and server side mod initialization.   
+In Fabric: Call in `onInitialize` in your `ModInitializer`.   
+In (Neo)Forge: Call in `onCommonSetup` (your `FMLCommonSetupEvent` handler).	
+
+## Condition Datagen Model
+
+The model class helps you to generate the condition json files via DataGen. 
+
+See https://github.com/klikli-dev/modonomicon/blob/2a067357bacaf3e15a5f490520a4headaf64807fe83e/common/src/main/java/com/klikli_dev/modonomicon/api/datagen/book/condition/BookAdvancementConditionModel.java for a reference model class.
+
+(On 1.20.1 it looks a bit more complicated: 
+https://github.com/klikli-dev/modonomicon/blob/bdf639c835908393198f695999c70f2ac53e154c/common/src/main/java/com/klikli_dev/modonomicon/api/datagen/book/condition/BookAdvancementConditionModel.java )
+
+:::tip 
+You need not register the model.
+::: 
+
+## Usage
+
+On your entry or category, add:
+
+```json
+{
+  ...
+  "condition": {
+      "type": "mymod:my_condition"
+  },
+  ...
+}
+```	
+
+See also [Unlock Conditions](../basics/unlock-conditions) for more information on how to use conditions.

versioned_docs/version-1.21.10/advanced/error-handling.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 20
+---
+
+# Error Handling
+
+Depending on the type of error there are different ways Modonomicon will handle them.
+Syntax errors in the JSON files representing your book will be caught by Minecraft's `SimpleJsonResourceReloadListener`, while any errors later in the loading process will be caught by the Modonomicon's own error handler.
+
+## JSON Syntax Errors 
+
+- will show up as `ERROR` in the log files.
+
+:::danger
+
+JSON Syntax Errors will in most cases not be shown in-game, only in the log, leading to "silent failures"!
+Make sure to check your log files for errors before releasing your book.
+
+:::
+
+Any errors in the json syntax will generally only show up in the log files, because they occur in Minecraft's loading logic, before Modonomicon receives the file content. In some cases they can cause follow-up errors (e.g. because an entry is missing) in Modonomicon's error handler and will be shown in-game.
+
+In Singleplayer you will find the error log in your `/logs/latest.log` file in your Minecraft installation directory. In Multiplayer that's in the `/logs/latest.log` file in your server's `/logs` directory.
+
+The log could be e.g. as follows for an extra comma where there shouldn't be one: 
+```
+[minecraft/SimpleJsonResourceReloadListener]: Couldn't parse data file modonomicon:test/entries/test_category/test_entry_child from modonomicon:modonomicon/books/test/entries/test_category/test_entry_child.json
+com.google.gson.JsonParseException: com.google.gson.stream.MalformedJsonException: Use JsonReader.setLenient(true) to accept malformed JSON at line 30 column 4 path $.pages[3]
+```
+
+:::caution
+
+If loading a JSON file fails server-side, there will not be any log on the client side (Minecraft loads the JSONs only server-side).
+Make sure to test your book in both SP and MP.
+
+:::
+
+### Finding JSON Syntax Errors in the Log
+
+Search log files for:
+
+- `minecraft/SimpleJsonResourceReloadListener`
+- `com.google.gson.JsonParseException`
+
+to find any errors handled by Minecraft that never reach Modonomicon.
+
+
+## Errors handled by Modonomicon
+
+- will show up as `WARN` in the log files.
+
+Modonomicon will attempt to handle errors gracefully - that means, the player will not crash, but instead will see a book screen with the error message, and a hint to check the log for further errors.
+
+Errors come with as much context as possible, that means the error handler will attempt to include the book, category, entry, page and potentially even page content element the error is associated with. 
+
+For example, an invalid link within a book page could produce the following error message:
+```
+[<time>] [Render thread/WARN] [co.kl.mo.Modonomicon/]: BookErrorManager.error() called for book: modonomicon:test with error: BookErrorInfo{ 
+errorMessage='Failed to render markdown for book 'modonomicon:test'', 
+context='Link: entry://modonomicon:test/test_category/test_entry@test_anchor, 
+Category: modonomicon:test_category, 
+Entry: modonomicon:test_category/test_entry_child, 
+Page: 2', 
+exception='java.lang.IllegalArgumentException: Invalid entry link, anchor not found in entry: modonomicon:test/test_category/test_entry@test_anchor'
+}
+```
+
+:::caution
+
+If you notice any issues such as crashes or log entries, but no Modonomicon error log in the above format or no Modonomicon error screen shown, please report this at https://github.com/klikli-dev/modonomicon/issues 
+
+:::
+
+### Finding Modonomicon Errors in the Log
+
+Search log files for `BookErrorManager.error() called for book` to find any errors handled by Modonomicon.
+
+### Error Screen
+
+The error screen for the above error message would look like this:
+
+![Error Screen](/img/docs/advanced/error-handling/error-window.png)

versioned_docs/version-1.21.10/advanced/integrations.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 30
+---
+
+# Integrations with other Mods
+
+## Patchouli
+
+Modonomicon can provide links to Patchouli Pages and open them on click.   
+
+See **[Patchouli Links](../basics/formatting#patchouli-links)**.

versioned_docs/version-1.21.10/advanced/item-properties.md

@@ -0,0 +1,72 @@
+---
+sidebar_position: 60
+---
+
+# Item Properties
+
+Item properties let item models change depending on runtime conditions. Modonomicon exposes a property you can use to change a book item's model depending on whether the Modonomicon UI is open for the player.
+
+## Open state
+
+### 1) Custom book item requirement
+
+This only works when using a custom book item (an item you register yourself). It does *not* work with the automatically generated book item.
+
+### 2) Java helper / Occultism example
+
+Occultism demonstrates a common approach: their [GuideBookItem](https://github.com/klikli-dev/occultism/blob/version/1.21.1/src/main/java/com/klikli_dev/occultism/common/item/tool/GuideBookItem.java) shows how to use `ModonomiconCustomItemBase` to obtain the same default Modonomicon behavior on your own item. `ModonomiconCustomItemBase` handles the DataComponents and registers the item property for you, which is why using it is recommended.
+
+:::tip
+Tip: extending `ModonomiconCustomItemBase` is the easiest route because it wires up the required DataComponents handling and property registration automatically.
+:::
+
+### 3) Registering the item
+
+Register your custom item as you would any other item. For reference see Occultism's item registration (their [OccultismItems](https://github.com/klikli-dev/occultism/blob/version/1.21.1/src/main/java/com/klikli_dev/occultism/registry/OccultismItems.java#L55) class) — the book item is just a normal item registration.
+
+### 4) Disable auto-generated book and datagen
+
+If you normally generate a book item from datagen, disable that generation and tell Modonomicon about your custom item. In `book.json` set:
+
+```json
+"generate_book_item": false,
+"custom_book_item": "<your_item_id>"
+```
+
+Or in datagen via the `BookModel` helpers:
+
+```java
+.withGenerateBookItem(false)
+.withCustomBookItem(this.modLoc("<your_item_id>"))
+```
+
+### 5) Client item: changing the model when open
+
+Modonomicon exposes the ConditionalItemModelProperty `modonomicon:is_book_open`. The value is `true` while the Modonomicon UI is open for the player and `false` otherwise. Use that in your client item to change model when the book is open. The following example shows a green book when closed and a purple book when open:
+
+```json
+{
+  "model": {
+    "type": "minecraft:condition",
+
+    "property": "modonomicon:is_book_open",
+
+    "on_true": {
+      "type": "minecraft:model",
+      "model": "modonomicon:item/modonomicon_purple"
+    },
+    "on_false": {
+      "type": "minecraft:model",
+      "model": "modonomicon:item/modonomicon_green"
+    }
+  }
+}
+```
+
+:::info
+See also https://docs.neoforged.net/docs/1.21.4/resources/client/models/items
+:::
+
+:::tip
+This example points at the `modonomicon:item/modonomicon_purple` and `modonomicon:item/modonomicon_green` models shipped by Modonomicon. If you want to use your own open-state model make sure the model JSON is present and loaded (register the model file or force-load it). A texture alone is not enough — Minecraft loads models, not raw textures.
+:::

versioned_docs/version-1.21.10/advanced/leaflets.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 50
+---
+
+# Leaflets
+
+Leaflets are single-entry books. That means there is no book overview, if you click the book you immediately see text.
+As a leaflet consists of an entry, it can still hold multiple pages, and within these pages use all features available to entries/pages in a normal book.
+
+The book will be treated as a book in index mode (that means, no big "node view" background will be shown behind the entry).
+
+## Creating a leaflet
+
+To create a leaflet book, you need a normal book structure including `book.json`, a single category, and within that category an entry.
+The book needs to have `leaflet_entry` set to the ResourceLocation of the single entry in the single category. 
+Additional content can be added to the book, but will not be displayed. 
+
+The best way to create a leaflet is to use the leaflet datagen. It is demonstrated in (and can be copied from) https://github.com/klikli-dev/modonomicon/tree/version/1.21/common/src/main/java/com/klikli_dev/modonomicon/datagen/book/DemoLeaflet.java

versioned_docs/version-1.21.10/advanced/localization.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 10
+---
+
+# Localization
+
+All in-game texts should be supplied as DescriptionIds (= Translation Keys) with a corresponding entry in the language file to provide the actual content and (markdown) formatting. Modonomicon adds some helper functionality to make providing book texts more easy.
+
+See for example https://github.com/klikli-dev/modonomicon/tree/version/1.21.1/common/src/main/java/com/klikli_dev/modonomicon/datagen/book/demo/formatting/AdvancedFormattingEntry.java 

versioned_docs/version-1.21.10/basics/basics.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 10
+---
+
+# Basics