| name | bloom-format |
| description | Use when you need to understand or verify the Bloom book file format — what a valid Bloom book is, its HTML structure, the data div, pages, translation groups, xMatter, origami (split-pane layout), canvas (images/overlays), the appearance system, how styles are defined, and the rule that text carries no inline styling. Points at the spec under docs/bloom-format/ and the `validate` CLI command. Consult it before changing anything that generates or inspects Bloom HTML. |
| argument-hint | what you need, e.g. 'how does origami work', 'is this book valid', 'where are styles defined' |
| user-invocable | true |
The Bloom book format
What this is
docs/bloom-format/ is the authoritative, cross-linked specification of the Bloom
book format. The source of truth is the Bloom editor's source — a separate
project, cited in the docs as <bloom-root>/… (checked out at d:/bloom on the
original author's machine). The spec describes what the format allows and
requires, in the present tense — it deliberately does not describe what
BloomBridge happens to emit. When you edit the spec, keep that framing (see the
governing principle in the index).
Start at docs/bloom-format/README.md —
it has the map of all pages and a document graph.
Use it to answer "what is a valid book / how does X work"
| Question | Page |
|---|
| Folder layout, required vs optional files | book-folder.md |
Top-level HTML, <head>, body = data div + pages | html-structure.md |
#bloomDataDiv, data-book/data-derived | data-div.md |
The .bloom-page element, page-size classes, .marginBox | pages.md |
Multilingual text: translation groups, editables, lang/z | translation-groups.md |
| Front/back matter (Bloom regenerates it) | xmatter.md |
| Origami split-pane page layout | origami.md |
| Canvas: images, backgrounds, text overlays | canvas.md |
appearance.json / appearance.css, themes, CSS variables | appearance.md |
The CSS cascade, named styles, userModifiedStyles | styles.md |
| No custom styling on elements (and the allowed exceptions) | styling-rule.md |
meta.json fields | meta-json.md |
| The machine-checkable rule set | validation.md |
Use it to verify a book
The spec is backed by a validator. Build first (pnpm build), then:
pnpm cli validate "<path to a book folder or its .htm>"
It reports errors / warnings / info, exits non-zero on any error, and works on
any Bloom book (Bloom-authored or converted). The validator code is
packages/lib/src/validate/; every rule traces back to a page in
docs/bloom-format/validation.md.
A book Bloom itself produced must pass with no errors — if it doesn't, the spec or
the validator is wrong (Bloom is the source of truth), so fix those rather than the
book.
