Patchouli Wiki

Patchouli is a documentation library that renders in-game guidebooks from plain data files. It adds no blocks or items of its own - instead it provides a framework that turns JSON definitions into a clean, page-turning book you can open and read inside the game.

Because everything is data-driven, you can build a fully illustrated manual using only a resource or data pack: no Java code is required. Books support rich text, recipes, 3D previews, and more, making Patchouli one of the most flexible ways to document a modpack or teach players game mechanics.

A book is defined by a small JSON file plus a folder of entries:

• Book definition - a JSON file at data/<namespace>/patchouli_books/<book_id>/book.json sets the book's name, landing text, and options.
• Categories - JSON files under .../categories/ group related entries and give the book its table of contents.
• Entries - JSON files under .../en_us/entries/ contain the actual pages. Each entry lists a category, an icon, and an ordered array of pages.

When the book is opened, Patchouli reads these files, builds the category grid, and lets the player browse and turn pages.

Each entry is a list of pages. The built-in page types cover most documentation needs:

Pack makers can mix page types freely within a single entry to build rich, illustrated tutorials.

1. Make a data pack (or add to your mod's data) with the folder data/<namespace>/patchouli_books/<book_id>/.
2. Add book.json with at least a name and landing_text.
3. Set "use_resource_pack": true - since 1.20 this is required, and book content then lives under assets/<namespace>/patchouli_books/<book_id>/en_us/.
4. Create one or more category files, then entry files that reference those categories.
5. Load the pack and open the guidebook item to see your book.

Tip: Book content must live under a namespace your pack owns. Keep entry IDs stable so bookmarks and links keep working across updates.

Text pages support an inline macro syntax for styling:

These macros let you write readable, styled documentation without any HTML, and they render consistently on every page.

• Categories appear on the book's landing page as a grid of icons. Selecting one shows the entries it contains, so large books stay organized.
• Reading progress is tracked per player - entries you have visited are marked, which is useful for guided progression.
• Bookmarks let a player pin any entry for quick access from the landing page.

Books can also gate entries behind advancements, so content unlocks as the player progresses through a modpack.

My book does not appear in game.

• Confirm the folder path is exactly data/<namespace>/patchouli_books/<book_id>/book.json and the JSON is valid (a trailing comma breaks the whole file).
• Make sure the pack is enabled and reload with /reload or by rejoining the world.

A crafting/smelting page shows an empty grid.

• The recipe id referenced by the page must exist and be loaded. Check the id spelling and that the providing mod/pack is installed.

Content shows in the wrong language or falls back to English.

• Book text is loaded per language. Add localized files under the matching xx_yy folder, otherwise Patchouli falls back to en_us.

Formatting macros print as literal text.

• Verify the macro syntax (for example $(bold) ... $()), and that the file is saved as UTF-8.