BookStack D&D 5e Statblock Guide
This guide documents how to use the BookStack D&D 5e statblock renderer with inline JSON and Tetra-cube .monster files.
Install the renderer once in BookStack custom HTML head content. After that, each page can include one or more hidden JSON wrappers. When the page loads, the renderer replaces those wrappers with styled D&D 5e statblocks.
Files
bookstack-custom-html-with-json-statblocks.html
The main BookStack custom HTML/CSS/JS bundle.bookstack-monster-paste-helper.html
A local helper page for loading, dropping, or pasting a.monsterfile and generating BookStack-ready wrapper HTML.bookstack-dnd-statblock-guide.html
The full HTML guide with rendered previews.bookstack-dnd-statblock-guide.md
This Markdown version.
Quick Start
- Open
bookstack-custom-html-with-json-statblocks.html. - Copy the statblock CSS and JavaScript into BookStack's Custom HTML Head Content.
- Open a BookStack page in source/HTML mode.
- Paste one of the wrapper snippets below.
- Put the JSON from a
.monsterfile inside the wrapper. - Save the page.
The renderer finds the wrapper, parses the JSON, hides the raw data, and replaces it with a styled statblock.
Correct .monster Wrapper
Use this first. It is the cleanest option because <template> content stays hidden before the renderer runs.
<template class="dnd-monster-data">
{
"...": "paste the full .monster JSON here"
}
</template>For a real .monster file, paste the entire file contents between the opening and closing tags:
<template class="dnd-monster-data">
{
"name": "Ancient Red Dragon",
"size": "gargantuan",
"type": "dragon",
"...": "the rest of the saved Tetra-cube .monster JSON"
}
</template>Important: when pasting into BookStack, paste only the HTML snippet. Do not paste the Markdown code fence lines.
Most Compatible Wrapper
If BookStack strips <template> tags, use a normal <div> instead.
<div class="dnd-monster-data">
{
"...": "paste the full .monster JSON here"
}
</div>This is slightly less clean before render, but the CSS hides it and the renderer still replaces it with the statblock.
Recommended .monster Wrapper With Useful Options
This is the pattern I would use for most BookStack pages while building/testing monsters:
<template
class="dnd-monster-data"
data-copy-buttons="true"
data-show-source="true"
data-source-label="Original .monster JSON">
{
"...": "paste the full .monster JSON here"
}
</template>What those attributes do:
After the monster is working, you can remove data-show-source="true" if you do not want the source/debug disclosure visible.
Layout Options
Add these attributes to the wrapper.
<template
class="dnd-monster-data"
data-layout="one-column">
{
"...": "paste the full .monster JSON here"
}
</template>Available layout values:
data-layout="one-column"
Forces one-column output. Good for narrow BookStack pages or long monster actions.data-layout="two-column"
Forces two-column output on desktop. Good for large monsters or boss statblocks.data-layout="wide"
Makes the block wider.data-layout="full"
Lets the block use the full available content width.
Compact example:
<template
class="dnd-monster-data"
data-layout="one-column"
data-compact="true">
{
"...": "paste the full .monster JSON here"
}
</template>Boss monster example:
<template
class="dnd-monster-data"
data-layout="two-column"
data-copy-buttons="true">
{
"...": "paste the full .monster JSON here"
}
</template>Tetra-cube .monster Workflow
- Build or edit the monster at Tetra-cube.
- Click Save Statblock.
- Open the downloaded
.monsterfile in a text editor. - Copy all of the JSON.
- Paste it inside a
dnd-monster-datawrapper. - Save the BookStack page.
Do not paste:
- The visible statblock text from Tetra-cube.
- A local file path to the
.monsterfile. - An attachment URL.
- A
<script type="application/json">block.
The renderer expects inline JSON inside:
<template class="dnd-monster-data">
...
</template>or:
<div class="dnd-monster-data">
...
</div>Full Example: .monster-Style Block
This is a shortened Tetra-cube-style example. A real .monster file will usually have more fields.
<template
class="dnd-monster-data"
data-copy-buttons="true"
data-show-source="true">
{
"name": "Emberglass Drake",
"size": "medium",
"type": "dragon",
"alignment": "chaotic neutral",
"armorClass": 15,
"hpText": "76 (9d8 + 36)",
"speed": 30,
"flySpeed": 60,
"strPoints": 18,
"dexPoints": 14,
"conPoints": 18,
"intPoints": 8,
"wisPoints": 12,
"chaPoints": 15,
"cr": "5",
"skills": [
{ "name": "Perception", "note": "ex" },
{ "name": "Stealth" }
],
"damagetypes": [
{ "name": "fire", "type": "i" }
],
"darkvision": 60,
"languages": [
{ "name": "Draconic", "speaks": true }
],
"abilities": [
{
"name": "Heated Scales",
"desc": "A creature that touches the drake or hits it with a melee attack while within 5 feet takes 3 (1d6) fire damage."
}
],
"actions": [
{
"name": "Bite",
"desc": "_Melee Weapon Attack:_ [STR ATK] to hit, reach 5 ft., one target. _Hit:_ [STR 1D10] piercing damage plus [2D6] fire damage."
},
{
"name": "Glassfire Breath (Recharge 5-6)",
"desc": "The drake exhales fire in a 30-foot cone. Each creature in that area must make a [CON SAVE] Dexterity saving throw, taking [8D6] fire damage on a failed save, or half as much damage on a successful one."
}
]
}
</template>Hand-authored JSON Wrapper
Use dnd-statblock-data when you are writing your own simplified JSON instead of using a Tetra-cube .monster file.
<div class="dnd-statblock-data">
{
"name": "Lantern-Haunt Wight",
"meta": "Medium undead, lawful evil",
"armorClass": "15 (ancient mail)",
"hitPoints": "67 (9d8 + 27)",
"speed": "30 ft.",
"abilities": {
"STR": "16 (+3)",
"DEX": "12 (+1)",
"CON": "16 (+3)",
"INT": "11 (+0)",
"WIS": "14 (+2)",
"CHA": "15 (+2)"
},
"properties": [
{ "label": "Skills", "value": "Perception +4, Stealth +3" },
{ "label": "Damage Resistances", "value": "necrotic; bludgeoning, piercing, and slashing from nonmagical attacks" },
{ "label": "Senses", "value": "darkvision 60 ft., passive Perception 14" },
{ "label": "Languages", "value": "Common plus one language it knew in life" },
{ "label": "Challenge", "value": "4 (1,100 XP)" }
],
"sections": [
{
"title": "Actions",
"features": [
{
"name": "Graveblade",
"text": "Melee Weapon Attack: +5 to hit, reach 5 ft., one target. Hit: 8 (1d10 + 3) slashing damage plus 7 (2d6) necrotic damage."
}
]
}
]
}
</div>Multiple Hand-authored Monsters
Use grid: true and a monsters array.
<div class="dnd-statblock-data">
{
"grid": true,
"monsters": [
{
"name": "Ash Rat",
"meta": "Tiny beast, unaligned",
"armorClass": "12",
"hitPoints": "7 (2d4 + 2)",
"speed": "30 ft.",
"abilities": {
"STR": "4 (-3)",
"DEX": "14 (+2)",
"CON": "12 (+1)",
"INT": "2 (-4)",
"WIS": "10 (+0)",
"CHA": "4 (-3)"
},
"properties": [
{ "label": "Senses", "value": "darkvision 30 ft., passive Perception 10" },
{ "label": "Challenge", "value": "1/8 (25 XP)" }
],
"sections": [
{
"title": "Actions",
"features": [
{
"name": "Bite",
"text": "Melee Weapon Attack: +4 to hit, reach 5 ft., one target. Hit: 4 (1d4 + 2) piercing damage."
}
]
}
]
},
{
"name": "Cinder Imp",
"meta": "Tiny fiend, chaotic evil",
"armorClass": "13",
"hitPoints": "10 (3d4 + 3)",
"speed": "20 ft., fly 30 ft.",
"abilities": {
"STR": "6 (-2)",
"DEX": "16 (+3)",
"CON": "12 (+1)",
"INT": "10 (+0)",
"WIS": "11 (+0)",
"CHA": "13 (+1)"
},
"properties": [
{ "label": "Damage Immunities", "value": "fire" },
{ "label": "Senses", "value": "darkvision 60 ft., passive Perception 10" },
{ "label": "Challenge", "value": "1/2 (100 XP)" }
],
"sections": [
{
"title": "Actions",
"features": [
{
"name": "Spark Claw",
"text": "Melee Weapon Attack: +5 to hit, reach 5 ft., one target. Hit: 5 (1d4 + 3) slashing damage plus 3 (1d6) fire damage."
}
]
}
]
}
]
}
</div>Supported Wrapper Attributes
Attribute | Values | Purpose |
|---|---|---|
|
,
,
,
| Changes statblock width/columns. |
|
| Slightly tightens long blocks. |
|
| Adds copy buttons for attacks, DCs, and dice. |
|
| Alias for
. |
|
| Adds a collapsed original-source/debug block. |
|
| Alias for
. |
| Any text | Changes the source disclosure label. |
Tetra-cube Token Support
The renderer resolves common Tetra-cube bracket tokens:
Token | Meaning |
|---|---|
| Short monster name. |
| Plural monster name. |
,
| Ability modifier, optionally adjusted. |
,
| Ability modifier plus proficiency. |
,
| Save DC using 8 + ability modifier + proficiency. |
,
| Average dice damage plus ability modifier. |
,
| Plain dice average and display formula. |
Example:
{
"name": "Bite",
"desc": "_Melee Weapon Attack:_ [STR ATK] to hit, reach 10 ft., one target. _Hit:_ [STR 2D10] piercing damage."
}Troubleshooting
The raw JSON appears on the page
The renderer CSS/JS is probably not installed in BookStack custom head content, or the wrapper class is wrong.
Check that you used one of these:
<template class="dnd-monster-data">
...
</template><div class="dnd-monster-data">
...
</div><div class="dnd-statblock-data">
...
</div>BookStack will not save the wrapper
Use source/HTML mode. If BookStack strips <template>, use the <div> wrapper.
The page shows Unexpected end of JSON input
The pasted JSON is incomplete. Check for a missing closing } or ].
The block is too wide
Use:
data-layout="one-column"The block is too long
Try:
data-layout="two-column"or:
data-compact="true"Best Default Snippet
Use this for most Tetra-cube .monster files:
<template
class="dnd-monster-data"
data-copy-buttons="true"
data-show-source="true"
data-source-label="Original .monster JSON">
{
"...": "paste the full .monster JSON here"
}
</template>If BookStack removes <template>, use this instead:
<div
class="dnd-monster-data"
data-copy-buttons="true"
data-show-source="true"
data-source-label="Original .monster JSON">
{
"...": "paste the full .monster JSON here"
}
</div>{ {"name":"Ancient Red Dragon","size":"gargantuan","type":"Dragon","tag":"","alignment":"chaotic evil","hitDice":"28","armorName":"natural armor","shieldBonus":0,"natArmorBonus":12,"otherArmorDesc":"22 (natural armor)","speed":"40","burrowSpeed":"0","climbSpeed":"40","flySpeed":"80","hover":false,"swimSpeed":"0","customHP":false,"customSpeed":false,"hpText":"546 (28d20 + 252)","speedDesc":"40 ft., climb 40 ft., fly 80 ft.","strPoints":"30","dexPoints":"10","conPoints":"29","intPoints":"18","wisPoints":"15","chaPoints":"23","blindsight":"60","blind":false,"darkvision":"120","tremorsense":"0","truesight":"0","telepathy":0,"cr":"24","customCr":"24 (62,000 XP)","customProf":7,"isLegendary":true,"legendariesDescription":"The dragon can take 3 legendary actions, choosing from the options below. Only one legendary action option can be used at a time and only at the end of another creature's turn. The dragon regains spent legendary actions at the start of its turn.","isLair":false,"lairDescription":"When fighting inside its lair, the ancient red dragon can invoke the ambient magic to take lair actions. On initiative count 20 (losing initiative ties), the ancient red dragon can take one lair action to cause one of the following effects:","lairDescriptionEnd":"The ancient red dragon can't repeat an effect until they have all been used, and it can't use the same effect two rounds in a row.","isMythic":false,"mythicDescription":"If the ancient red dragon's mythic trait is active, it can use the options below as legendary actions for 1 hour after using {Some Ability}.","isRegional":false,"regionalDescription":"The region containing the ancient red dragon's lair is warped by the creature's presence, which creates one or more of the following effects:","regionalDescriptionEnd":"If the ancient red dragon dies, the first two effects fade over the course of 3d10 days.","properties":[],"abilities":[{"name":"Legendary Resistance (3/Day)","desc":"If the dragon fails a saving throw, it can choose to succeed instead."}],"actions":[{"name":"Multiattack","desc":"The dragon can use its Frightful Presence. It then makes three attacks: one with its bite and two with its claws."},{"name":"Bite","desc":"_Melee Weapon Attack:_ +17 to hit, reach 15 ft., one target. _Hit:_ 21 (2d10 + 10) piercing damage plus 14 (4d6) fire damage."},{"name":"Claw","desc":"_Melee Weapon Attack:_ +17 to hit, reach 10 ft., one target. _Hit:_ 17 (2d6 + 10) slashing damage."},{"name":"Tail","desc":"_Melee Weapon Attack:_ +17 to hit, reach 20 ft., one target. _Hit:_ 19 (2d8 + 10) bludgeoning damage."},{"name":"Frightful Presence","desc":"Each creature of the dragon's choice that is within 120 feet of the dragon and aware of it must succeed on a DC 21 Wisdom saving throw or become frightened for 1 minute. A creature can repeat the saving throw at the end of each of its turns, ending the effect on itself on a success. If a creature's saving throw is successful or the effect ends for it, the creature is immune to the dragon's Frightful Presence for the next 24 hours."},{"name":"Fire Breath (Recharge 5-6)","desc":"The dragon exhales fire in a 90-foot cone. Each creature in that area must make a DC 24 Dexterity saving throw, taking 91 (26d6) fire damage on a failed save, or half as much damage on a successful one."}],"bonusActions":[],"reactions":[],"legendaries":[{"name":"Detect","desc":"The dragon makes a Wisdom (Perception) check."},{"name":"Tail Attack","desc":"The dragon makes a tail attack."},{"name":"Wing Attack (Costs 2 Actions)","desc":"The dragon beats its wings. Each creature within 15 ft. of the dragon must succeed on a DC 25 Dexterity saving throw or take 17 (2d6 + 10) bludgeoning damage and be knocked prone. The dragon can then fly up to half its flying speed."}],"mythics":[],"lairs":[],"regionals":[],"sthrows":[{"name":"dex","order":1},{"name":"con","order":2},{"name":"wis","order":4},{"name":"cha","order":5}],"skills":[{"name":"perception","stat":"wis","note":" (ex)"},{"name":"stealth","stat":"dex"}],"damagetypes":[{"name":"fire","note":" (Immune)","type":"i"}],"specialdamage":[],"conditions":[],"languages":[{"name":"Common","speaks":true},{"name":"Draconic","speaks":true}],"understandsBut":"","shortName":"","pluralName":"","doubleColumns":true,"separationPoint":3,"damage":[]} }