From 16bd868442eea15f257884d3c2bbbb40b5ccf2ad Mon Sep 17 00:00:00 2001
From: Fellteros <aloisprochazka6@gmail.com>
Date: Fri, 25 Apr 2025 15:58:08 +0200
Subject: [PATCH 01/11] Added Block Models page

---
 .vitepress/sidebars/develop.ts |   6 +-
 develop/blocks/block-models.md | 244 +++++++++++++++++++++++++++++++++
 sidebar_translations.json      |   1 +
 3 files changed, 250 insertions(+), 1 deletion(-)
 create mode 100644 develop/blocks/block-models.md

diff --git a/.vitepress/sidebars/develop.ts b/.vitepress/sidebars/develop.ts
index a43128da1..2d5c8d96d 100644
--- a/.vitepress/sidebars/develop.ts
+++ b/.vitepress/sidebars/develop.ts
@@ -1,4 +1,4 @@
-import { Fabric } from "../types";
+import {Fabric} from "../types";
 
 export default [
   {
@@ -102,6 +102,10 @@ export default [
         text: "develop.blocks.first-block",
         link: "/develop/blocks/first-block",
       },
+      {
+        text: "develop.blocks.block-models",
+        link: "/develop/blocks/block-models",
+      },
       {
         text: "develop.blocks.blockstates",
         link: "/develop/blocks/blockstates",
diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
new file mode 100644
index 000000000..8d1e6d97f
--- /dev/null
+++ b/develop/blocks/block-models.md
@@ -0,0 +1,244 @@
+---
+title: Block Models
+description: A guide to writing and understanding block models.
+authors:
+  - Fellteros
+---
+
+This page will guide you through writing your own block models and understanding all their options and possibilities.
+
+## What Are Block Models? {#what-are-block-models}
+
+Block models are essentially the definition of a block's looks and visuals. They specify a texture, model translation, rotation, scale and other attributes.
+Models are stored as JSON files in your ``resources`` folder.
+
+## File Structure {#file-structure}
+
+Every block model file has a defined structure that has to be followed. It all starts with empty curly brackets = the **root tag** of the model. Here's a brief scheme of how block models are structured:
+
+```json
+{
+  "parent": "...",
+  "ambientocclusion": "true/false",
+  "display": {
+    "<position>": {
+      "rotation": [0, 0, 0],
+      "translation": [0, 0, 0],
+      "scale": [0, 0, 0]
+    }
+  },
+  "textures": {
+    "particle": "...",
+    "<texture_variable>": "..."
+  },
+  "elements": [
+    {
+      "from": [0, 0, 0],
+      "to": [0, 0, 0],
+      "rotation": {
+        "origin": [0, 0, 0],
+        "axis": "...",
+        "angle": "...",
+        "rescale": "true/false"
+      },
+      "shade": "true/false",
+      "light_emission": "...",
+      "faces": {
+        "<face>": {
+          "uv": [0, 0, 0, 0],
+          "texture": "...",
+          "cullface": "...",
+          "rotation": "...",
+          "tintindex": "..."
+        }
+      }
+    }
+  ]
+}
+```
+
+### Parent {#parent}
+
+```json
+{
+  "parent": "..."
+}
+```
+
+Loads a different model with all its attributes from the given path, as a resource location (`namespace:path`).
+
+Can be set to `builtin/generated` to use a model created out of the specified icon. Only the first layer is supported, and rotation can be achieved via [blockstates](./blockstates.md).
+
+### Ambient Occlusion {#ambient-occlusion}
+
+````json
+{
+  "ambientocclusion": "true/false"
+}
+````
+
+This tag specifies whether to use [ambient occlusion](https://en.wikipedia.org/wiki/Ambient_occlusion). Defaults to ``true``.
+
+### Display {#display}
+
+```json
+{
+  "display": {
+    "<position>": {
+      "rotation": [0, 0, 0],
+      "translation": [0, 0, 0],
+      "scale": [0, 0, 0]
+    }
+  }
+}
+```
+
+This tag is responsible for setting the model translation, rotation and scale in a specified position. The position object can be one of these eight strings and defines how the model looks in different positions:
+
+| \<position>               | Description                                     |
+|---------------------------|-------------------------------------------------|
+| ``firstperson_righthand`` | Right hand when looking from first-person view. |
+| ``firstperson_lefthand``  | Left hand when looking from first-person view.  |
+| ``thirdperson_righthand`` | Right hand when looking from third-person view. |
+| ``thirdperson_lefthand``  | Left hand when looking from third-person view.  |
+| ``gui``                   | GUI, inventory.                                 |
+| ``head``                  | When put above player's head (e.g., banner).    |
+| ``ground``                | On the ground.                                  |
+| ``fixed``                 | When put in block frame.                        |
+
+Furthermore, each position can contain these three values, each in the form of an array of floats:
+
+```json
+{
+  "rotation": [0, 0, 0],
+  "translation": [0, 0, 0],
+  "scale": [0, 0, 0]
+}
+```
+
+1. ``rotation``: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
+2. ``translation``: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values are limited to **-80** and **80**, anything exceeding these limits is displayed as them.
+3. ``scale``: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is **4**, anything bigger is displayed as 4.
+
+### Textures {#textures}
+
+```json
+{
+  "textures": {
+    "particle": "...",
+    "<texture_variable>": "..."
+  }
+}
+```
+
+The ``textures`` tag holds the textures of the model, in the form of a resource location or a texture variable. It contains three additional objects:
+
+1. ``particle``: _String_. Defines the texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. Is also considered a texture variable that can be referenced as ``#particle``
+2. ``<texture_variable>``: _String_. It creates a variable and assigns a texture. Can be further referenced with the ``#`` prefix (e.g., `"top": "namespace:path"` ⇒ ``#top``)
+
+### Elements {#elements}
+
+```json
+{
+  "elements": [
+    {
+      "from": [0, 0, 0],
+      "to": [0, 0, 0],
+      "rotation": {
+        "origin": [0, 0, 0],
+        "axis": "...",
+        "angle": "...",
+        "rescale": "true/false"
+      },
+      "shade": "true/false",
+      "light_emission": "...",
+      "faces": {
+        "<face>": {
+          "uv": [0, 0, 0, 0],
+          "texture": "...",
+          "cullface": "...",
+          "rotation": "...",
+          "tintindex": "..."
+        }
+      }
+    }
+  ]
+}
+```
+
+Contains all the elements of the model, which can only be cubic. If both `parent` and `elements` tags are set, this file's `elements` tag overrides the parent's one.
+
+```json
+{
+  "from": [0, 0, 0],
+  "to": [0, 0, 0]
+}
+```
+
+``from`` specifies the starting point of the cuboid according to the scheme `[x, y, z]` relative to the lower left corner. `to` specifies the ending point. A cuboid starting at `[0, 0, 0]` and ending at `[16, 16, 16]` is as big as a standard block.
+The values of both must be between **-16** and **32**, which means that every block model can be at most 3x3 blocks big.
+
+```json
+{
+  "rotation": {
+    "origin": [0, 0, 0],
+    "axis": "...",
+    "angle": "...",
+    "rescale": "true/false"
+  }
+}
+```
+
+`rotation` defines the rotation of an element. It furthermore contains four more values:
+
+1. ``origin``: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
+2. ``axis``: _String_. Specifies the direction of rotation, and may be one of these: `x`, `y` and `z`.
+3. ``angle``: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45** in 22.5 degree increments.
+4. ``rescale``: _Boolean_. Specifies whether to scale the faces across the whole block by scaling the non-rotated faces by ``1 + 1 / (cos(angle) - 1 )``
+
+```json
+{
+  "shade": "true/false"
+}
+```
+
+``shade`` defines if shadows are rendered (``true`` - default) or not (``false``).
+
+````json
+{
+  "light_emission": "..."
+}
+````
+
+``light_emission`` defines the minimum light level that the element can receive. It can be in range from **0** to **15** and default to 0.
+
+````json
+{
+  "faces": {
+    "<face>": {
+      "uv": [0, 0, 0, 0],
+      "texture": "...",
+      "cullface": "...",
+      "rotation": 0,
+      "tintindex": 0
+    }
+  }
+}
+````
+
+``faces`` holds all the faces of the cuboid. If a face is left out, it does not render. Takes the form of a _string_, with these six options: ``down``, ``up``, ``north``, ``south``, ``west`` or ``east``. Each contains the properties of the specified face.
+Additionally, it contains these five values:
+
+1. ``uv``: _Four integers_. Defines the area of the texture to use according to the scheme ``[x1, y1, x2, y2]``. If unset, it defaults to values equal to xyz position of the element.
+If the numbers of ``x1`` and ``x2`` are swapped (e.g., from ``0, 0, 16, 16`` to ``16, 0, 0, 16``), the texture flips. UV is optional, and if not supplied, it automatically generates based on the element's position.
+2. ``texture``: _String_. Specifies the texture of the face in the form of a [texture variable](#textures) prepended with `#`.
+3. ``cullface``: _String_. Can be: ``down``, ``up``, ``north``, ``south``, ``west``, or ``east``. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
+It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
+4. ``rotation``: _Integer_. Rotates the texture by the specified number of degrees in 90 degree increments. Rotation does not affect which part of the texture is used.
+Instead, it amounts to permutation of the selected texture vertices (selected implicitly, or explicitly though ``uv``).
+5. ``tintidex``: _Integer_. Determines whether to tint the texture. The default value, ``-1``, indicates not to use the tint.
+Any other number is provided to ``BlockColors`` to get the tint value corresponding to that index (returns white when the block doesn't have a tint index defined).
+
+## Sources and Links {#sources-and-links}
+
+You can visit Minecraft wiki's [block model page](https://minecraft.wiki/w/Model#Block_models) for more detailed walkthrough. The majority of information is from this page.
diff --git a/sidebar_translations.json b/sidebar_translations.json
index a4ca4e92c..86c8b27db 100644
--- a/sidebar_translations.json
+++ b/sidebar_translations.json
@@ -32,6 +32,7 @@
   "develop.items.custom-data-components": "Custom Data Components",
   "develop.blocks": "Blocks",
   "develop.blocks.first-block": "Creating Your First Block",
+  "develop.blocks.block-models": "Block Models",
   "develop.blocks.blockstates": "Block States",
   "develop.blocks.block-entities": "Block Entities",
   "develop.blocks.block-entity-renderer": "Block Entity Renderers",

From 6a216309d927af4792a79e34044879add24e25f4 Mon Sep 17 00:00:00 2001
From: Fellteros <aloisprochazka6@gmail.com>
Date: Fri, 25 Apr 2025 16:00:54 +0200
Subject: [PATCH 02/11] Markdown lint changes

---
 develop/blocks/block-models.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index 8d1e6d97f..ebf8224be 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -67,7 +67,7 @@ Every block model file has a defined structure that has to be followed. It all s
 
 Loads a different model with all its attributes from the given path, as a resource location (`namespace:path`).
 
-Can be set to `builtin/generated` to use a model created out of the specified icon. Only the first layer is supported, and rotation can be achieved via [blockstates](./blockstates.md).
+Can be set to `builtin/generated` to use a model created out of the specified icon. Only the first layer is supported, and rotation can be achieved via [blockstates](./blockstates).
 
 ### Ambient Occlusion {#ambient-occlusion}
 

From fe360313797090b8cef933c9b2db99775e4af85a Mon Sep 17 00:00:00 2001
From: Fellteros <aloisprochazka6@gmail.com>
Date: Fri, 25 Apr 2025 17:36:44 +0200
Subject: [PATCH 03/11] Minor tweaks

---
 develop/blocks/block-models.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index ebf8224be..c2134a2ef 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -104,7 +104,7 @@ This tag is responsible for setting the model translation, rotation and scale in
 | ``gui``                   | GUI, inventory.                                 |
 | ``head``                  | When put above player's head (e.g., banner).    |
 | ``ground``                | On the ground.                                  |
-| ``fixed``                 | When put in block frame.                        |
+| ``fixed``                 | When put in item frame.                         |
 
 Furthermore, each position can contain these three values, each in the form of an array of floats:
 

From b442bf552642151884625d4ee9342c1e869b5323 Mon Sep 17 00:00:00 2001
From: Fellteros <144528463+Fellteros@users.noreply.github.com>
Date: Sun, 21 Sep 2025 11:33:17 +0200
Subject: [PATCH 04/11] update block-models.md to 1.21.8, style changes, lint

Signed-off-by: Fellteros <144528463+Fellteros@users.noreply.github.com>
---
 develop/blocks/block-models.md | 124 +++++++++++++++++----------------
 1 file changed, 63 insertions(+), 61 deletions(-)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index c2134a2ef..436ad7c78 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -10,11 +10,12 @@ This page will guide you through writing your own block models and understanding
 ## What Are Block Models? {#what-are-block-models}
 
 Block models are essentially the definition of a block's looks and visuals. They specify a texture, model translation, rotation, scale and other attributes.
-Models are stored as JSON files in your ``resources`` folder.
+
+Models are stored as JSON files in your `resources` folder.
 
 ## File Structure {#file-structure}
 
-Every block model file has a defined structure that has to be followed. It all starts with empty curly brackets = the **root tag** of the model. Here's a brief scheme of how block models are structured:
+Every block model file has a defined structure that has to be followed. It starts with empty curly brackets, which represent the **root tag** of the model. Here's a brief scheme of how block models are structured:
 
 ```json
 {
@@ -22,9 +23,9 @@ Every block model file has a defined structure that has to be followed. It all s
   "ambientocclusion": "true/false",
   "display": {
     "<position>": {
-      "rotation": [0, 0, 0],
-      "translation": [0, 0, 0],
-      "scale": [0, 0, 0]
+      "rotation": [0.0, 0.0, 0.0],
+      "translation": [0.0, 0.0, 0.0],
+      "scale": [0.0, 0.0, 0.0]
     }
   },
   "textures": {
@@ -33,10 +34,10 @@ Every block model file has a defined structure that has to be followed. It all s
   },
   "elements": [
     {
-      "from": [0, 0, 0],
-      "to": [0, 0, 0],
+      "from": [0.0, 0.0, 0.0],
+      "to": [0.0, 0.0, 0.0],
       "rotation": {
-        "origin": [0, 0, 0],
+        "origin": [0.0, 0.0, 0.0],
         "axis": "...",
         "angle": "...",
         "rescale": "true/false"
@@ -65,9 +66,9 @@ Every block model file has a defined structure that has to be followed. It all s
 }
 ```
 
-Loads a different model with all its attributes from the given path, as a resource location (`namespace:path`).
+Loads a different model with all its attributes from the given path, as an identifier (`namespace:path`).
 
-Can be set to `builtin/generated` to use a model created out of the specified icon. Only the first layer is supported, and rotation can be achieved via [blockstates](./blockstates).
+Set this tag to `builtin/generated` to use a model created from the specified icon. Rotation can be achieved via [blockstates](./blockstates).
 
 ### Ambient Occlusion {#ambient-occlusion}
 
@@ -77,7 +78,7 @@ Can be set to `builtin/generated` to use a model created out of the specified ic
 }
 ````
 
-This tag specifies whether to use [ambient occlusion](https://en.wikipedia.org/wiki/Ambient_occlusion). Defaults to ``true``.
+This tag specifies whether to use [ambient occlusion](https://en.wikipedia.org/wiki/Ambient_occlusion). Defaults to `true`.
 
 ### Display {#display}
 
@@ -93,32 +94,34 @@ This tag specifies whether to use [ambient occlusion](https://en.wikipedia.org/w
 }
 ```
 
-This tag is responsible for setting the model translation, rotation and scale in a specified position. The position object can be one of these eight strings and defines how the model looks in different positions:
+This tag is responsible for setting the model translation, rotation and scale in a specified position.
 
-| \<position>               | Description                                     |
-|---------------------------|-------------------------------------------------|
-| ``firstperson_righthand`` | Right hand when looking from first-person view. |
-| ``firstperson_lefthand``  | Left hand when looking from first-person view.  |
-| ``thirdperson_righthand`` | Right hand when looking from third-person view. |
-| ``thirdperson_lefthand``  | Left hand when looking from third-person view.  |
-| ``gui``                   | GUI, inventory.                                 |
-| ``head``                  | When put above player's head (e.g., banner).    |
-| ``ground``                | On the ground.                                  |
-| ``fixed``                 | When put in item frame.                         |
+ The position object can be one of the following strings, which define what the model will look like in different positions:
 
-Furthermore, each position can contain these three values, each in the form of an array of floats:
+| Value                   | Description                                         |
+|-------------------------|-----------------------------------------------------|
+| `firstperson_righthand` | Right hand, as seen in first-person                 |
+| `firstperson_lefthand`  | Left hand, as seen in first-person                  |
+| `thirdperson_righthand` | Right hand, as seen in third-person (<kbd>F5</kbd>) |
+| `thirdperson_lefthand`  | Left hand, as seen in third-person (<kbd>F5</kbd>)  |
+| `gui`                   | When in a GUI, for example the inventory            |
+| `head`                  | When put on the player's head, for example a banner |
+| `ground`                | When on the ground                                  |
+| `fixed`                 | When put in an item frame                           |
+
+Furthermore, each position can contain these three values, in the form of an array of floats:
 
 ```json
 {
-  "rotation": [0, 0, 0],
-  "translation": [0, 0, 0],
-  "scale": [0, 0, 0]
+  "rotation": [0.0, 0.0, 0.0],
+  "translation": [0.0, 0.0, 0.0],
+  "scale": [0.0, 0.0, 0.0]
 }
 ```
 
-1. ``rotation``: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
-2. ``translation``: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values are limited to **-80** and **80**, anything exceeding these limits is displayed as them.
-3. ``scale``: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is **4**, anything bigger is displayed as 4.
+1. `rotation`: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
+2. `translation`: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values must be between `-80` and `80`; anything outside of this range is set to the closest extremum.
+3. `scale`: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is `4`, bigger values are treated as `4`.
 
 ### Textures {#textures}
 
@@ -131,10 +134,10 @@ Furthermore, each position can contain these three values, each in the form of a
 }
 ```
 
-The ``textures`` tag holds the textures of the model, in the form of a resource location or a texture variable. It contains three additional objects:
+The `textures` tag holds the textures of the model, in the form of an identifier or a texture variable. It contains three additional objects:
 
-1. ``particle``: _String_. Defines the texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. Is also considered a texture variable that can be referenced as ``#particle``
-2. ``<texture_variable>``: _String_. It creates a variable and assigns a texture. Can be further referenced with the ``#`` prefix (e.g., `"top": "namespace:path"` ⇒ ``#top``)
+1. `particle`: _String_. Defines the texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. Is also considered a texture variable that can be referenced as `#particle`
+2. `<texture_variable>`: _String_. It creates a variable and assigns a texture. Can be further referenced with the `#` prefix (e.g., `"top": "namespace:path"` ⇒ `#top`)
 
 ### Elements {#elements}
 
@@ -142,10 +145,10 @@ The ``textures`` tag holds the textures of the model, in the form of a resource
 {
   "elements": [
     {
-      "from": [0, 0, 0],
-      "to": [0, 0, 0],
+      "from": [0.0, 0.0, 0.0],
+      "to": [0.0, 0.0, 0.0],
       "rotation": {
-        "origin": [0, 0, 0],
+        "origin": [0.0, 0.0, 0.0],
         "axis": "...",
         "angle": "...",
         "rescale": "true/false"
@@ -170,18 +173,18 @@ Contains all the elements of the model, which can only be cubic. If both `parent
 
 ```json
 {
-  "from": [0, 0, 0],
-  "to": [0, 0, 0]
+  "from": [0.0, 0.0, 0.0],
+  "to": [0.0, 0.0, 0.0]
 }
 ```
 
-``from`` specifies the starting point of the cuboid according to the scheme `[x, y, z]` relative to the lower left corner. `to` specifies the ending point. A cuboid starting at `[0, 0, 0]` and ending at `[16, 16, 16]` is as big as a standard block.
+`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
 The values of both must be between **-16** and **32**, which means that every block model can be at most 3x3 blocks big.
 
 ```json
 {
   "rotation": {
-    "origin": [0, 0, 0],
+    "origin": [0.0, 0.0, 0.0],
     "axis": "...",
     "angle": "...",
     "rescale": "true/false"
@@ -189,12 +192,12 @@ The values of both must be between **-16** and **32**, which means that every bl
 }
 ```
 
-`rotation` defines the rotation of an element. It furthermore contains four more values:
+`rotation` defines the rotation of an element. It contains four more values:
 
-1. ``origin``: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
-2. ``axis``: _String_. Specifies the direction of rotation, and may be one of these: `x`, `y` and `z`.
-3. ``angle``: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45** in 22.5 degree increments.
-4. ``rescale``: _Boolean_. Specifies whether to scale the faces across the whole block by scaling the non-rotated faces by ``1 + 1 / (cos(angle) - 1 )``
+1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
+2. `axis`: _String_. Specifies the direction of rotation, and must be one of these: `x`, `y` and `z`.
+3. `angle`: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45**.
+4. `rescale`: _Boolean_. Specifies whether to scale the faces across the whole block. Defaults to `false`.
 
 ```json
 {
@@ -202,17 +205,17 @@ The values of both must be between **-16** and **32**, which means that every bl
 }
 ```
 
-``shade`` defines if shadows are rendered (``true`` - default) or not (``false``).
+`shade` defines if shadows are rendered. Defaults to `true`.
 
-````json
+```json
 {
   "light_emission": "..."
 }
-````
+```
 
-``light_emission`` defines the minimum light level that the element can receive. It can be in range from **0** to **15** and default to 0.
+`light_emission` defines the minimum light level that the element can receive. It can range between **0** and **15**. Defaults to 0.
 
-````json
+```json
 {
   "faces": {
     "<face>": {
@@ -224,21 +227,20 @@ The values of both must be between **-16** and **32**, which means that every bl
     }
   }
 }
-````
+```
 
-``faces`` holds all the faces of the cuboid. If a face is left out, it does not render. Takes the form of a _string_, with these six options: ``down``, ``up``, ``north``, ``south``, ``west`` or ``east``. Each contains the properties of the specified face.
-Additionally, it contains these five values:
+`faces` holds all the faces of the cuboid. If a face is not set, it will not be rendered. Its keys can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each key contains the properties for that face:
 
-1. ``uv``: _Four integers_. Defines the area of the texture to use according to the scheme ``[x1, y1, x2, y2]``. If unset, it defaults to values equal to xyz position of the element.
-If the numbers of ``x1`` and ``x2`` are swapped (e.g., from ``0, 0, 16, 16`` to ``16, 0, 0, 16``), the texture flips. UV is optional, and if not supplied, it automatically generates based on the element's position.
-2. ``texture``: _String_. Specifies the texture of the face in the form of a [texture variable](#textures) prepended with `#`.
-3. ``cullface``: _String_. Can be: ``down``, ``up``, ``north``, ``south``, ``west``, or ``east``. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
+1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
+  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
+2. `texture`: _String_. Specifies the texture of the face in the form of a [texture variable](#textures), prepended with `#`.
+3. `cullface`: _String_. Can be: `down`, `up`, `north`, `south`, `west`, or `east`. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
 It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
-4. ``rotation``: _Integer_. Rotates the texture by the specified number of degrees in 90 degree increments. Rotation does not affect which part of the texture is used.
-Instead, it amounts to permutation of the selected texture vertices (selected implicitly, or explicitly though ``uv``).
-5. ``tintidex``: _Integer_. Determines whether to tint the texture. The default value, ``-1``, indicates not to use the tint.
-Any other number is provided to ``BlockColors`` to get the tint value corresponding to that index (returns white when the block doesn't have a tint index defined).
+4. `rotation`: _Integer_. Rotates the texture by the specified number of degrees in 90 degree increments. Rotation does not affect which part of the texture is used.
+Instead, it amounts to permutation of the selected texture vertices (selected implicitly, or explicitly though `uv`).
+5. `tintidex`: _Integer_. Tints the texture on that face using a tint value. The default value, `-1`, indicates not to use the tint.
+Any other number is provided to `BlockColors` to get the tint value corresponding to that index (returns white when the block doesn't have a tint index defined).
 
 ## Sources and Links {#sources-and-links}
 
-You can visit Minecraft wiki's [block model page](https://minecraft.wiki/w/Model#Block_models) for more detailed walkthrough. The majority of information is from this page.
+You can visit Minecraft Wiki's [Item Models page](https://minecraft.wiki/w/Model#Item_models) for a more detailed walkthrough. A lot of information here is from that page.

From 189fadee8faa0aa912eb77d358de854e0bcc1e62 Mon Sep 17 00:00:00 2001
From: Fellteros <144528463+Fellteros@users.noreply.github.com>
Date: Sun, 21 Sep 2025 15:28:45 +0200
Subject: [PATCH 05/11] made changes according to miroma's suggestions

Co-authored-by: 136986257+its-miroma@users.noreply.github.com
Signed-off-by: Fellteros <144528463+Fellteros@users.noreply.github.com>
---
 develop/blocks/block-models.md | 143 +++------------------------------
 develop/items/item-models.md   |  27 ++++++-
 2 files changed, 37 insertions(+), 133 deletions(-)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index 436ad7c78..eeac985f9 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -3,6 +3,7 @@ title: Block Models
 description: A guide to writing and understanding block models.
 authors:
   - Fellteros
+  - its-miroma
 ---
 
 This page will guide you through writing your own block models and understanding all their options and possibilities.
@@ -58,15 +59,8 @@ Every block model file has a defined structure that has to be followed. It start
 }
 ```
 
-### Parent {#parent}
 
-```json
-{
-  "parent": "..."
-}
-```
-
-Loads a different model with all its attributes from the given path, as an identifier (`namespace:path`).
+<!--@include: ..\items\item-models.md#parent-->
 
 Set this tag to `builtin/generated` to use a model created from the specified icon. Rotation can be achieved via [blockstates](./blockstates).
 
@@ -80,48 +74,7 @@ Set this tag to `builtin/generated` to use a model created from the specified ic
 
 This tag specifies whether to use [ambient occlusion](https://en.wikipedia.org/wiki/Ambient_occlusion). Defaults to `true`.
 
-### Display {#display}
-
-```json
-{
-  "display": {
-    "<position>": {
-      "rotation": [0, 0, 0],
-      "translation": [0, 0, 0],
-      "scale": [0, 0, 0]
-    }
-  }
-}
-```
-
-This tag is responsible for setting the model translation, rotation and scale in a specified position.
-
- The position object can be one of the following strings, which define what the model will look like in different positions:
-
-| Value                   | Description                                         |
-|-------------------------|-----------------------------------------------------|
-| `firstperson_righthand` | Right hand, as seen in first-person                 |
-| `firstperson_lefthand`  | Left hand, as seen in first-person                  |
-| `thirdperson_righthand` | Right hand, as seen in third-person (<kbd>F5</kbd>) |
-| `thirdperson_lefthand`  | Left hand, as seen in third-person (<kbd>F5</kbd>)  |
-| `gui`                   | When in a GUI, for example the inventory            |
-| `head`                  | When put on the player's head, for example a banner |
-| `ground`                | When on the ground                                  |
-| `fixed`                 | When put in an item frame                           |
-
-Furthermore, each position can contain these three values, in the form of an array of floats:
-
-```json
-{
-  "rotation": [0.0, 0.0, 0.0],
-  "translation": [0.0, 0.0, 0.0],
-  "scale": [0.0, 0.0, 0.0]
-}
-```
-
-1. `rotation`: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
-2. `translation`: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values must be between `-80` and `80`; anything outside of this range is set to the closest extremum.
-3. `scale`: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is `4`, bigger values are treated as `4`.
+<!--@include: ..\items\item-models.md#display-->
 
 ### Textures {#textures}
 
@@ -136,61 +89,17 @@ Furthermore, each position can contain these three values, in the form of an arr
 
 The `textures` tag holds the textures of the model, in the form of an identifier or a texture variable. It contains three additional objects:
 
-1. `particle`: _String_. Defines the texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. Is also considered a texture variable that can be referenced as `#particle`
-2. `<texture_variable>`: _String_. It creates a variable and assigns a texture. Can be further referenced with the `#` prefix (e.g., `"top": "namespace:path"` ⇒ `#top`)
+1. `particle`: _String_. Defines the texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. Is also considered a texture variable that can be referenced as `#particle`.
+2. `<texture_variable>`: _String_. It creates a variable and assigns a texture. Can be later referenced with the `#` prefix (e.g., `"top": "namespace:path"` ⇒ `#top`)
 
-### Elements {#elements}
+<!--@include: ..\items\item-models.md#elements-->
 
-```json
-{
-  "elements": [
-    {
-      "from": [0.0, 0.0, 0.0],
-      "to": [0.0, 0.0, 0.0],
-      "rotation": {
-        "origin": [0.0, 0.0, 0.0],
-        "axis": "...",
-        "angle": "...",
-        "rescale": "true/false"
-      },
-      "shade": "true/false",
-      "light_emission": "...",
-      "faces": {
-        "<face>": {
-          "uv": [0, 0, 0, 0],
-          "texture": "...",
-          "cullface": "...",
-          "rotation": "...",
-          "tintindex": "..."
-        }
-      }
-    }
-  ]
-}
-```
-
-Contains all the elements of the model, which can only be cubic. If both `parent` and `elements` tags are set, this file's `elements` tag overrides the parent's one.
-
-```json
-{
-  "from": [0.0, 0.0, 0.0],
-  "to": [0.0, 0.0, 0.0]
-}
-```
+<!--@include: ..\items\item-models.md#from-->
 
 `from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
-The values of both must be between **-16** and **32**, which means that every block model can be at most 3x3 blocks big.
+The values of both must be between **-16** and **32**, which means that every block model can be at most 3×3 blocks big.
 
-```json
-{
-  "rotation": {
-    "origin": [0.0, 0.0, 0.0],
-    "axis": "...",
-    "angle": "...",
-    "rescale": "true/false"
-  }
-}
-```
+<!--@include: ..\items\item-models.md#rotation-->
 
 `rotation` defines the rotation of an element. It contains four more values:
 
@@ -199,37 +108,7 @@ The values of both must be between **-16** and **32**, which means that every bl
 3. `angle`: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45**.
 4. `rescale`: _Boolean_. Specifies whether to scale the faces across the whole block. Defaults to `false`.
 
-```json
-{
-  "shade": "true/false"
-}
-```
-
-`shade` defines if shadows are rendered. Defaults to `true`.
-
-```json
-{
-  "light_emission": "..."
-}
-```
-
-`light_emission` defines the minimum light level that the element can receive. It can range between **0** and **15**. Defaults to 0.
-
-```json
-{
-  "faces": {
-    "<face>": {
-      "uv": [0, 0, 0, 0],
-      "texture": "...",
-      "cullface": "...",
-      "rotation": 0,
-      "tintindex": 0
-    }
-  }
-}
-```
-
-`faces` holds all the faces of the cuboid. If a face is not set, it will not be rendered. Its keys can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each key contains the properties for that face:
+<!--@include: ..\items\item-models.md#shade-to-faces-->
 
 1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
   Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
@@ -243,4 +122,4 @@ Any other number is provided to `BlockColors` to get the tint value correspondin
 
 ## Sources and Links {#sources-and-links}
 
-You can visit Minecraft Wiki's [Item Models page](https://minecraft.wiki/w/Model#Item_models) for a more detailed walkthrough. A lot of information here is from that page.
+You can visit Minecraft Wiki's [Block Models page](https://minecraft.wiki/w/Model#Block_models) for a more detailed walkthrough. A lot of information here is from that page.
diff --git a/develop/items/item-models.md b/develop/items/item-models.md
index 4f1cd18f2..abbfdc7e0 100644
--- a/develop/items/item-models.md
+++ b/develop/items/item-models.md
@@ -3,6 +3,7 @@ title: Item Models
 description: A guide to writing and understanding item models.
 authors:
   - Fellteros
+  - its-miroma
   - VatinMc
 ---
 
@@ -60,6 +61,8 @@ Every item model file has a defined structure that has to be followed. It starts
 }
 ```
 
+<!-- #region parent -->
+
 ### Parent {#parent}
 
 ```json
@@ -70,8 +73,12 @@ Every item model file has a defined structure that has to be followed. It starts
 
 Loads a different model with all its attributes from the given path, as an identifier (`namespace:path`).
 
+<!-- #endregion parent -->
+
 Set this tag to `item/generated` to use a model created from the specified icon, or set it to `builtin/generated` to use the model without any translation, rotation, or scaling.
 
+<!-- #region display -->
+
 ### Display {#display}
 
 ```json
@@ -115,6 +122,8 @@ Furthermore, each position can contain these three values, in the form of an arr
 2. `translation`: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values must be between `-80` and `80`; anything outside of this range is set to the closest extremum.
 3. `scale`: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is `4`, bigger values are treated as `4`.
 
+<!-- #endregion display -->
+
 ### Textures {#textures}
 
 ```json
@@ -147,6 +156,8 @@ The `textures` tag holds the textures of the model, in the form of an identifier
 
 This tag defines the direction from which the item model is illuminated. Can be either `front` or `side`, with the latter being the default. If set to `front`, the model is rendered like a flat item, if set `side`, the item is rendered like a block.
 
+<!-- #region elements -->
+
 ### Elements {#elements}
 
 ```json
@@ -179,6 +190,10 @@ This tag defines the direction from which the item model is illuminated. Can be
 
 Contains all the elements of the model, which can only be cubic. If both `parent` and `elements` tags are set, this file's `elements` tag overrides the parent's one.
 
+<!-- #endregion elements -->
+
+<!-- #region from -->
+
 ```json
 {
   "from": [0.0, 0.0, 0.0],
@@ -186,9 +201,13 @@ Contains all the elements of the model, which can only be cubic. If both `parent
 }
 ```
 
+<!-- #endregion from -->
+
 `from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
 The values of both must be between **-16** and **32**, which means that every item model can be at most 3×3 blocks big.
 
+<!-- #region rotation -->
+
 ```json
 {
   "rotation": {
@@ -200,6 +219,8 @@ The values of both must be between **-16** and **32**, which means that every it
 }
 ```
 
+<!-- #endregion rotation -->
+
 `rotation` defines the rotation of an element. It contains four more values:
 
 1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
@@ -207,6 +228,8 @@ The values of both must be between **-16** and **32**, which means that every it
 3. `angle`: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45** in 22.5 degree increments.
 4. `rescale`: _Boolean_. Specifies whether to scale the faces across the whole block. Defaults to `false`.
 
+<!-- #region shade-to-faces -->
+
 ```json
 {
   "shade": "true/false"
@@ -237,7 +260,9 @@ The values of both must be between **-16** and **32**, which means that every it
 }
 ```
 
-`faces` holds all the faces of the cuboid. If a face is not set, it will not be rendered. Its keys can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each keys contains the properties for that face:
+`faces` holds all the faces of the cuboid. If a face is not set, it will not be rendered. Its keys can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each key contains the properties for that face:
+
+<!-- #endregion shade-to-faces -->
 
 1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
   Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.

From bc6208086d908333c065d0f2a0c94da0b9937be0 Mon Sep 17 00:00:00 2001
From: Fellteros <144528463+Fellteros@users.noreply.github.com>
Date: Sun, 21 Sep 2025 15:30:23 +0200
Subject: [PATCH 06/11] lint

Signed-off-by: Fellteros <144528463+Fellteros@users.noreply.github.com>
---
 develop/blocks/block-models.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index eeac985f9..9ed97e75c 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -59,7 +59,6 @@ Every block model file has a defined structure that has to be followed. It start
 }
 ```
 
-
 <!--@include: ..\items\item-models.md#parent-->
 
 Set this tag to `builtin/generated` to use a model created from the specified icon. Rotation can be achieved via [blockstates](./blockstates).

From dc7fbbccbf2ee2d51e815241262dc00d1b9739c8 Mon Sep 17 00:00:00 2001
From: Fellteros <144528463+Fellteros@users.noreply.github.com>
Date: Mon, 22 Sep 2025 16:19:55 +0200
Subject: [PATCH 07/11] Add nbsps where reasonable

---
 develop/blocks/block-models.md |  8 ++++----
 develop/items/item-models.md   | 14 +++++++-------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index 9ed97e75c..4b5889e20 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -95,22 +95,22 @@ The `textures` tag holds the textures of the model, in the form of an identifier
 
 <!--@include: ..\items\item-models.md#from-->
 
-`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
+`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
 The values of both must be between **-16** and **32**, which means that every block model can be at most 3×3 blocks big.
 
 <!--@include: ..\items\item-models.md#rotation-->
 
 `rotation` defines the rotation of an element. It contains four more values:
 
-1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
+1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
 2. `axis`: _String_. Specifies the direction of rotation, and must be one of these: `x`, `y` and `z`.
 3. `angle`: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45**.
 4. `rescale`: _Boolean_. Specifies whether to scale the faces across the whole block. Defaults to `false`.
 
 <!--@include: ..\items\item-models.md#shade-to-faces-->
 
-1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
-  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
+1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
+  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
 2. `texture`: _String_. Specifies the texture of the face in the form of a [texture variable](#textures), prepended with `#`.
 3. `cullface`: _String_. Can be: `down`, `up`, `north`, `south`, `west`, or `east`. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
 It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
diff --git a/develop/items/item-models.md b/develop/items/item-models.md
index abbfdc7e0..8304d1f42 100644
--- a/develop/items/item-models.md
+++ b/develop/items/item-models.md
@@ -118,9 +118,9 @@ Furthermore, each position can contain these three values, in the form of an arr
 }
 ```
 
-1. `rotation`: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
-2. `translation`: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values must be between `-80` and `80`; anything outside of this range is set to the closest extremum.
-3. `scale`: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is `4`, bigger values are treated as `4`.
+1. `rotation`: _Three floats_. Specifies the rotation of the model according to the scheme `[x, y, z]`.
+2. `translation`: _Three floats_. Specifies the translation of the model according to the scheme `[x, y, z]`. Values must be between `-80` and `80`; anything outside of this range is set to the closest extremum.
+3. `scale`: _Three floats_. Specifies the scale of the model according to the scheme `[x, y, z]`. The maximum value is `4`, bigger values are treated as `4`.
 
 <!-- #endregion display -->
 
@@ -203,7 +203,7 @@ Contains all the elements of the model, which can only be cubic. If both `parent
 
 <!-- #endregion from -->
 
-`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
+`from` specifies the starting point of the cuboid according to the scheme `[x, y, z]`, relative to the lower left corner. `to` specifies the ending point. A cuboid as big as a standard block would start at `[0, 0, 0]` and end at `[16, 16, 16]`.
 The values of both must be between **-16** and **32**, which means that every item model can be at most 3×3 blocks big.
 
 <!-- #region rotation -->
@@ -223,7 +223,7 @@ The values of both must be between **-16** and **32**, which means that every it
 
 `rotation` defines the rotation of an element. It contains four more values:
 
-1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y, z]`.
+1. `origin`: _Three floats_. Sets the center of the rotation according to the scheme `[x, y z]`.
 2. `axis`: _String_. Specifies the direction of rotation, and must be one of these: `x`, `y` and `z`.
 3. `angle`: _Float_. Specifies the angle of rotation. Ranges from **-45** to **45** in 22.5 degree increments.
 4. `rescale`: _Boolean_. Specifies whether to scale the faces across the whole block. Defaults to `false`.
@@ -264,8 +264,8 @@ The values of both must be between **-16** and **32**, which means that every it
 
 <!-- #endregion shade-to-faces -->
 
-1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
-  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
+1. `uv`: _Four integers_. Defines the area of the texture to use according to the scheme `[x1, y1, x2, y2]`. If unset, it defaults to values equal to xyz position of the element.
+  Flipping the values of `x1` and `x2` (for example from `0, 0, 16, 16` to `16, 0, 0, 16`) flips the texture. UV is optional, and if not supplied, it's automatically generated based on the element's position.
 2. `texture`: _String_. Specifies the texture of the face in the form of a [texture variable](#textures), prepended with `#`.
 3. `cullface`: _String_. Can be: `down`, `up`, `north`, `south`, `west`, or `east`. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
   It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.

From 6b2aa6c4447b64cad2772d495c40651a31093927 Mon Sep 17 00:00:00 2001
From: Miroma <136986257+its-miroma@users.noreply.github.com>
Date: Tue, 23 Sep 2025 08:49:14 +0200
Subject: [PATCH 08/11] Apply suggestion from @its-miroma

---
 .vitepress/sidebars/develop.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.vitepress/sidebars/develop.ts b/.vitepress/sidebars/develop.ts
index 8aeb08837..77dddfef5 100644
--- a/.vitepress/sidebars/develop.ts
+++ b/.vitepress/sidebars/develop.ts
@@ -1,4 +1,4 @@
-import {Fabric} from "../types";
+import { Fabric } from "../types";
 
 export default [
   {

From 9b4352108fefaf0913a122dbf245484e6af8b15b Mon Sep 17 00:00:00 2001
From: Miroma <136986257+its-miroma@users.noreply.github.com>
Date: Tue, 23 Sep 2025 08:55:26 +0200
Subject: [PATCH 09/11] Apply suggestion from @its-miroma

---
 develop/blocks/block-models.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index 4b5889e20..500cac433 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -6,6 +6,8 @@ authors:
   - its-miroma
 ---
 
+<!-- markdownlint-disable search-replace -->
+
 This page will guide you through writing your own block models and understanding all their options and possibilities.
 
 ## What Are Block Models? {#what-are-block-models}

From 42bc34bbaaaa6945586b195e83b69083cc5e6c66 Mon Sep 17 00:00:00 2001
From: Miroma <136986257+its-miroma@users.noreply.github.com>
Date: Tue, 23 Sep 2025 08:55:45 +0200
Subject: [PATCH 10/11] Apply suggestion from @its-miroma

---
 develop/items/item-models.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/develop/items/item-models.md b/develop/items/item-models.md
index 8304d1f42..8a8e9d249 100644
--- a/develop/items/item-models.md
+++ b/develop/items/item-models.md
@@ -7,6 +7,8 @@ authors:
   - VatinMc
 ---
 
+<!-- markdownlint-disable search-replace -->
+
 This page will guide you through writing your own item models and understanding all their options and possibilities.
 
 ## What Are Item Models? {#what-are-item-models}

From d06802589e65a2e2ebf572e548cb4e8416734c63 Mon Sep 17 00:00:00 2001
From: Fellteros <144528463+Fellteros@users.noreply.github.com>
Date: Sun, 28 Sep 2025 09:52:56 +0200
Subject: [PATCH 11/11] Small grammatical changes

---
 develop/blocks/block-models.md | 6 +++---
 develop/items/item-models.md   | 8 ++++----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/develop/blocks/block-models.md b/develop/blocks/block-models.md
index 4b5889e20..5ac75ac2f 100644
--- a/develop/blocks/block-models.md
+++ b/develop/blocks/block-models.md
@@ -46,7 +46,7 @@ Every block model file has a defined structure that has to be followed. It start
       "shade": "true/false",
       "light_emission": "...",
       "faces": {
-        "<face>": {
+        "<key>": {
           "uv": [0, 0, 0, 0],
           "texture": "...",
           "cullface": "...",
@@ -89,7 +89,7 @@ This tag specifies whether to use [ambient occlusion](https://en.wikipedia.org/w
 The `textures` tag holds the textures of the model, in the form of an identifier or a texture variable. It contains three additional objects:
 
 1. `particle`: _String_. Defines the texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. Is also considered a texture variable that can be referenced as `#particle`.
-2. `<texture_variable>`: _String_. It creates a variable and assigns a texture. Can be later referenced with the `#` prefix (e.g., `"top": "namespace:path"` ⇒ `#top`)
+2. `<texture_variable>`: _String_. Creates a variable and assigns a texture. Can be later referenced with the `#` prefix (e.g., `"top": "namespace:path"` ⇒ `#top`)
 
 <!--@include: ..\items\item-models.md#elements-->
 
@@ -114,7 +114,7 @@ The values of both must be between **-16** and **32**, which means that every bl
 2. `texture`: _String_. Specifies the texture of the face in the form of a [texture variable](#textures), prepended with `#`.
 3. `cullface`: _String_. Can be: `down`, `up`, `north`, `south`, `west`, or `east`. Specifies whether a face does not need to be rendered when there is a block touching it in the specified position.
 It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
-4. `rotation`: _Integer_. Rotates the texture by the specified number of degrees in 90 degree increments. Rotation does not affect which part of the texture is used.
+4. `rotation`: _Integer_. Rotates the texture clockwise by the specified number of degrees in 90 degree increments. Rotation does not affect which part of the texture is used.
 Instead, it amounts to permutation of the selected texture vertices (selected implicitly, or explicitly though `uv`).
 5. `tintidex`: _Integer_. Tints the texture on that face using a tint value. The default value, `-1`, indicates not to use the tint.
 Any other number is provided to `BlockColors` to get the tint value corresponding to that index (returns white when the block doesn't have a tint index defined).
diff --git a/develop/items/item-models.md b/develop/items/item-models.md
index 8304d1f42..fa2314de3 100644
--- a/develop/items/item-models.md
+++ b/develop/items/item-models.md
@@ -48,7 +48,7 @@ Every item model file has a defined structure that has to be followed. It starts
       "shade": "true/false",
       "light_emission": "...",
       "faces": {
-        "<face>": {
+        "<key>": {
           "uv": [0, 0, 0, 0],
           "texture": "...",
           "cullface": "...",
@@ -188,7 +188,7 @@ This tag defines the direction from which the item model is illuminated. Can be
 }
 ```
 
-Contains all the elements of the model, which can only be cubic. If both `parent` and `elements` tags are set, this file's `elements` tag overrides the parent's one.
+Contains all elements of a model, which can only be cubic. If both `parent` and `elements` tags are set, this file's `elements` tag overrides the parent's one.
 
 <!-- #endregion elements -->
 
@@ -249,7 +249,7 @@ The values of both must be between **-16** and **32**, which means that every it
 ```json
 {
   "faces": {
-    "<face>": {
+    "<key>": {
       "uv": [0, 0, 0, 0],
       "texture": "...",
       "cullface": "...",
@@ -260,7 +260,7 @@ The values of both must be between **-16** and **32**, which means that every it
 }
 ```
 
-`faces` holds all the faces of the cuboid. If a face is not set, it will not be rendered. Its keys can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each key contains the properties for that face:
+`faces` holds all faces of a cuboid. If a face is not set, it will not be rendered. Its keys (`<key>`) can be one of: `down`, `up`, `north`, `south`, `west` or `east`. Each key contains the properties for that face:
 
 <!-- #endregion shade-to-faces -->