Patchouli — Guide

Page Types

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

Page type	Shows
`text`	Formatted paragraphs of text
`crafting`	A crafting recipe grid and its result
`smelting`	A furnace/smelting recipe
`image`	One or more full images with a caption
`spotlight`	A highlighted item with its name and description
`entity`	A live, rotating 3D entity model
`multiblock`	An interactive 3D preview of a multiblock structure
`link` / `relations`	Cross-links to other entries

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

Make a data pack (or add to your mod's data) with the folder data/<namespace>/patchouli_books/<book_id>/.
Add book.json with at least a name and landing_text.
Set "use_resource_pack": true - this is now required, and book content then lives under assets/<namespace>/patchouli_books/<book_id>/en_us/.
Create one or more category files, then entry files that reference those categories.
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:

Macro	Effect
`$(br)`	Line break
`$(bold)` ... `$()`	Bold text
`$(italic)` ... `$()`	Italic text
`$(4)` ... `$()`	Colored text (by index or hex)
`$(l:entry)` ... `$(/l)`	Clickable link to another entry
`$(item)` / `$(thing)`	Highlight an item or keyword

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.

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.