Converting Rulebooks

Converting Rulebooks

Tutorial. For builders. You have a legal copy of a tabletop RPG rulebook in PDF, HTML, or a web page. By the end, you'll have clean Markdown that the Build workflow can read.

What Convert is

Convert is the first workflow in the build pipeline. It turns a rulebook source into structurally sound Markdown: headings resolve, tables survive page breaks, and references trace. You ask your AI to run it; you do not run a separate app.

"Convert my Mothership books to Markdown."

The workflow records the source, the ruleset slug, and the output location before touching anything. It runs per source and validates each file's structure before handoff.

Source: spec §6.1 (Convert workflow), Appendix G (source conversion).

What you need

1. A legal copy of the game. You own the books you convert.
2. An MCP-capable AI client. Opencode, Zed, Claude Desktop, Continue, or Cursor.
3. The ruleset slug. A short name the server uses, such as mothership, dnd5e, or starfinder.

Plan the conversion

Decide which books you will actually play with. Core rules come first, then the modules and supplements you intend to run. For Mothership, that is the Player's Survival Guide, the Warden's Operations Manual, and the adventure module.

Tell the AI the source and the target slug:

"Convert my Mothership books to Markdown for the mothership ruleset."

Execute it

Switch to your client's build mode and start the workflow:

"Convert these PDFs to Markdown."

The AI asks its intake questions up front — source type, source paths, and the ruleset name — and records the answers before touching a file.

What Convert handles

• Columns. Column detection restores reading order in multi-column layouts.
• Tables. Multi-page table reassembly merges fragments split across page breaks.
• Scans. Scanned pages fall back to OCR (optical character recognition).
• Validation. Each converted file is checked for structure before handoff.

If a converter drops headings or tables, re-run it with a validated converter rather than hand-editing the output.

Source: spec Appendix G (source conversion), Appendix H (preparation checklist).

Where the files go

Converted Markdown is your working source. Keep it in a directory you control, and keep the books out of the server tree. The Build workflow reads this directory; your campaign data lives separately under .holonovel-state/.

Your converted files stay on your machine. Do not redistribute them — the books remain the publisher's work.

Next step

Build the ruleset from your converted Markdown. See Building a Server.

See also

• Building a Server — turn the Markdown into a running server
• Adventure Modules — convert and load a module into a Novel
• FAQ — common setup and build problems

Sources

• Holonovel spec §6.1 (Convert workflow)
• Holonovel spec Appendix G (source conversion)
• Holonovel spec Appendix H (preparation checklist)

Last updated: 2026-10-25.