Text Rulebooks
There are two kinds of rulebook here, and a page is one or the other for its whole life.
- An image rulebook is a stack of page pictures you turn on the table. That is what a PDF import builds, what a Tabletop Simulator mod's rulebook becomes, and what you get if you place page art by hand.
- A text rulebook is written in Markdown and rendered live. It is searchable, you can edit it at the table without leaving the room, and because there is nothing to rasterise it costs no storage.
This article is about the second kind. If your rules already exist as a finished PDF, the other one is the right door.
Getting one
Drop a .md file on the table
In a playtest room, drag a folder containing a .md file onto the table, or the .md on its
own. You are asked which folder in your files to use, the same question a PDF drop asks, and the
book is placed where you dropped it.
- If the folder holds several Markdown files, a README at the top level wins; otherwise the one nearest the top of the tree.
- Only the pictures the file actually links to are uploaded. Dropping a whole code repository does not pour it into your storage.
- The
.mditself is kept in your files too, so the source of the book is a file you own rather than something that only exists as rows in a database.
Dropping files on the table is host-only.
From the Component Wizard
Start a new component, choose Rulebook, and use Build it from a markdown file on the pages step. It follows the same contract as the PDF option beside it: same naming, same replace question.
Start empty and write it
In a room, open the components panel and pick Text Rulebook from the generic objects. (The one next to it, Image Rulebook, is the picture kind.) You get a one-page book you can start typing into straight away.
Where the pages come from
Markdown has no pages, so you say where they are: a thematic break on its own line starts a new
page. Any of ---, *** or ___ works.
- A file with no breaks in it is one page.
- Anything longer than its page scrolls. Text is expected to scroll, and silently cutting a rule in half at a page boundary would be worse than a scrollbar.
- A break directly under a line of text is a heading, not a page break (that is how Markdown writes an underlined heading), so it is left alone.
Pages are named after the book and their number, like "rules.md page 3". That is deliberately not taken from the page's own first heading: a README that opens with a logo and five build badges would otherwise call page one after an image URL. Rename any page you like in the editor.
Pages are US Letter (8.5 x 11 inches), the same as a sheet of paper.
Editing at the table
Right-click the book and open Pages ▸ Edit Rulebook Text…. The editor is a floating panel you can move and resize, and it does not close the room behind it.
- Write, Split and Preview across the top. Split shows the text and the rendered page side by side, and drops to one column when the panel is too narrow for two.
- A formatting bar with H1, H2, B, I, bulleted and numbered lists, Quote, Table, Image (picks from My Files) and New page.
- Page tabs down the side, + Page to add one, and a bin to delete one.
- The status bar counts the words on this page, the words in the whole book, and roughly how long it takes to read.
Two saves, and they are not the same thing
This is worth being precise about, because there are two copies of a rulebook and they are separate.
- Save to Components writes the text back to the component records in your project. That is the master copy, and it is what a new table gets when you place the book again.
- The copy on this table is refreshed at the same time, so what you are looking at updates too.
The panel tells you which state you are in: it shows Components written HH:MM · table copy refreshed once saved, and "N pages are not in the components yet" while there is unsaved work. An unsaved page is also marked in its tab.
Adding and removing pages
From Pages on the right-click menu:
- Add Text Page puts a new empty page at the end.
- Remove Current Page deletes the one you are on. A rulebook always keeps at least one page, so the last one cannot be removed.
Renaming, resizing and reordering
The two menus split by what the thing is. Pages is the pages: turning to one, adding, removing, and writing the words on it. Component is the book itself.
So everything about the book lives in Component ▸ Rulebook Details, which is the same panel an image rulebook uses with the artwork controls taken out:
- The rulebook's name.
- The page size in inches, for one page or for every page at once.
- A description.
- What each page is called, and what order the pages are in. Each row shows the page's first line, so you can tell them apart while you move them.
- Add Page and delete, the same as the text editor's own.
Saving here does not touch the text of any page, so renaming a book is safe while somebody is partway through writing it.
Reading it during a game
Search it
A book of words can be searched, which a book of pictures cannot.
- Press Ctrl+F with the book open in the preview, or selected on the table, and you get a find box that jumps to the page a phrase is on.
- The same thing is on the right-click menu as Pages ▸ Find in Rulebook…, because nobody standing at the table ever found the magnifier on the preview's own toolbar.
- With no rulebook open or selected, Ctrl+F stays your browser's own find, everywhere else in the room.
Put it in the left panel
Reading a rulebook by picking it up and zooming in is the thing people actually complain about. A host can right-click the book and choose Add to Left Panel, and it appears as its own collapsible section under Game Info, sized to the height of the window so a big screen shows a big screen's worth.
Everyone at the table sees it, not just the host, and it is saved with the table setup, so loading that setup opens the rules beside the game again. Remove from Left Panel on the same menu takes it back out.
Links
Links in a rendered page open in a new tab, so following one never navigates the room out from under you and loses the game in progress.
Pictures
A Markdown file that links to images works, and those pictures are copied into your storage so the book does not depend on someone else's server staying up.
While that copying is happening you see a placeholder where the book will go: the book's name, how many pictures are being fetched, and a clock counting up. The book itself appears when the pictures are in, so you never get a page full of broken images.
If it takes much longer than it should, the placeholder says so and offers Put it down anyway. That means the background picture fetcher is not running, which on a self-hosted install is a queue worker that needs starting.
Replacing a book you already have
Importing Markdown again under the same name matches pages positionally, exactly as re-importing a PDF does: page five of the rewrite overwrites page five of the book. Pages past the end of the new file are deleted.
Limits and costs
- No storage is used by the text. Pages are stored as text and rendered live, so a text rulebook does not count against your quota the way page images do.
- Pictures do count, like any other artwork, in the folder you chose. Manage them from My Files.