Skip to main content

Text Formatting 101

Across the book specification, you'll find objects that specify they can be "formatted". Patchouli comes with a text formatting system that allows you to write rich text using a few formatting codes.

Formatting codes can be tested out in real time using the ingame editor (the pencil in the main page). Read on for what you can use.

Default Formatting Codes​

  • $() - Clears any formatting currently applied
  • $(br) - Adds a line break
  • $(br2) - Adds two line breaks (or a new paragraph, if you will)
  • $(li) - Makes a list element for a bullet point list
    • You can also use $(li2), $(li3), etc, for nested lists
  • $(#rrggbb) - Hex code color (e.g. $(#ff0000) makes the text red)
    • $(#rgb) is also allowed (e.g. $(#f00) also makes the text red)
  • $(0-f) - Color code (e.g. $(6) makes the text gold color)
  • $(k/l/m/n/o) - Formatting code (e.g. $(o) makes the text italic)
  • $(l:ID) - Internal Link. ID can be an entry ID or a category ID, renders a clickable link opening the given entry or category. If both an entry or category have the same ID, then the entry wins.
  • $(l:entryid#anchorname) - Internal Link, same as above, but refers to a specific page. The target page must have the "anchor" field set to the specified anchor name. Anchors cannot be used with category ID's.
  • $(l:https://...) - External Link, similar to previous, but when clicked, opens the website
  • $(/l) - End Link, ends the current link but maintains formatting ($() also ends links)
  • $(playername) - Inserts the name of the player
  • $(k:...) - Inserts the key value of the keybind you place after "k:". Read below for how get the keybind name
  • $(t:...) - Makes any text after this one show the text you place after "t:" as a tooltip when hovered
  • $(/t) - End Link, ends the current tooltip but maintains formatting ($() also ends tooltips)
  • $(c:/command here) - Makes the player send this command to the server when clicked. Use with the vanilla /trigger command, scoreboard objectives, and mcfunctions. The leading slash must be present.
  • $(/c) - End Command, ends the current command but maintains formatting ($() also ends commands)

Using $(k:...):

To find the name of a keybind, open your options.txt file in your instance folder (next to /mods, /config, etc) with a text editor, and browse the values that start with "key_", until you find one that looks like the one you want (these are internal names the mods use).

Say you want to show the F5 (Toggle Perspective) key. You'd look for key_key.togglePerspective:63. You then grab that line of text and do the following:

  • Remove the "key_" at the start, and the ":N" at the end (N being whatever number is there).
  • If the name you have now starts with "key.", you can remove that too.
  • You now have the name to put inside $(k:...). In this case, you'd write $(k:togglePerspective), and it would replace in the book to F5, or whatever the player has that keybind set to.

Default Macros​

A bunch of macros are provided by default. If you write what's on the left, it'll automatically alias to what's on the right.

  • $(obf) -> $(k)
  • $(bold) -> $(l)
  • $(strike) -> $(m)
  • $(italic) -> $(o)
  • $(italics) -> $(o)
  • $(list -> $(li
    • (the lack of closing parenthesis is intended to allow you to do $(list2), $(list3), etc)
  • $(reset) -> $()
  • $(clear) -> $()
  • $(2br) -> $(br2)
  • $(p) -> $(br2)
  • /$ -> $()
  • <br> -> $(br)
  • $(nocolor) -> $(0)
  • $(item) -> $(#b0b)
  • $(thing) -> $(#490)

You are recommended to use $(item) and $(thing) as generic colors to highlight items and concepts, respectively.

Custom Macros​

Individual books are allowed to create their own macros. These macros will work for the book they're defined for only. Macros defined by books override the default ones, so you can rebind $(item) to some other color if you want to, for example.

To create custom macros, simply add a "macros" key to your book.json (see Book JSON Format for more info), and fill it in as follows:

"macros": {
    "key1": "value1",
    "key2": "value2"
}

where key is what you want to replace, and value is what you want to replace it with. For example:

"macros": {
    "$(potato)": "$(#F00)POTATO SALAD$()"
}

should you do this, whenever you write $(potato), it would replace it with "POTATO SALAD" in red text.

There's no restriction that the left side has to contain the standard $(...) format either, so you can also rewrite the formatting if you want, like as follows:

"macros": {
    "<b>": "$(l)",
    "<i>": "$(o)",
    "</>": "$()"
}