Sections & divisions

ScriptPub has two kinds of structure, and keeping them apart is the single most important thing to understand about the model. They never mix.

	Section	Division
What	A unique, named body-level element dividing the work.	A repeating, ranked heading derived from a block kind.
Examples	Title page, Contents, Foreword, Body, Notes, Bibliography.	Act, Sequence, Scene, Chapter.
How many	Each occurs at most once.	Repeats freely.
Declared by	The DOM structure itself — no configuration.	A block type’s `behavior.outline` + `rank`.
Nests?	Never.	Yes — by `rank`.

Sections are the singular, named parts of a work. Divisions are its anonymous, repeating skeleton. A screenplay has one Body section containing many Scene divisions; it does not have a “scene section.”

Sections are semantic elements

A section is a direct child of <body> — <header>, <nav>, <main>, <footer>, or <section>. There is no section configuration: the DOM structure IS the declaration. The rules:

Sections are direct children of <body>; they never nest.
Each section id occurs at most once (there are no two title pages).
A bare element implies its default id: <header> → titlepage, <nav> → toc, <main> → body, <footer> → notes. A class token overrides: <section class="appendix"> is the standard appendix section; <nav class="lot"> is lot.
A document whose only section element is <main> is unsectioned — <main> is just the content root. Any other section element present promotes <main> to the body section.
Blocks that are direct <body> children outside any section element are edge blocks (they belong to no section).
A custom section is <section class="x"> with any class-safe id. Custom sections default to body matter; data-spub-matter="front|back" overrides. A classless <section> is invalid as a section and is treated as a transparent container by the parser (its blocks join the surrounding stream), as is a duplicate section id.

The standard vocabulary

The fixed standard section vocabulary, in conventional publication order — each entry’s id (also the class token that names it on its element), its element, its DPUB-ARIA role (emitted on and recognized from the element), its publication matter, and its EPUB structural-semantics token for package export:

id	Element	Role	Matter	EPUB token	Label
`cover`	`section.cover`	`doc-cover`	front	`cover`	Cover
`titlepage`	`header`	—	front	`titlepage`	Title page
`copyright`	`section.copyright`	—	front	`copyright-page`	Copyright
`dedication`	`section.dedication`	`doc-dedication`	front	`dedication`	Dedication
`epigraph`	`section.epigraph`	`doc-epigraph`	front	`epigraph`	Epigraph
`toc`	`nav`	`doc-toc`	front	`toc`	Contents
`loi`	`nav.loi`	—	front	`loi`	List of illustrations
`lot`	`nav.lot`	—	front	`lot`	List of tables
`foreword`	`section.foreword`	`doc-foreword`	front	`foreword`	Foreword
`preface`	`section.preface`	`doc-preface`	front	`preface`	Preface
`acknowledgments`	`section.acknowledgments`	`doc-acknowledgments`	front	`acknowledgments`	Acknowledgments
`introduction`	`section.introduction`	`doc-introduction`	front	`introduction`	Introduction
`prologue`	`section.prologue`	`doc-prologue`	body	`prologue`	Prologue
`body`	`main`	—	body	`bodymatter`	Body
`epilogue`	`section.epilogue`	`doc-epilogue`	body	`epilogue`	Epilogue
`afterword`	`section.afterword`	`doc-afterword`	back	`afterword`	Afterword
`conclusion`	`section.conclusion`	`doc-conclusion`	back	`conclusion`	Conclusion
`appendix`	`section.appendix`	`doc-appendix`	back	`appendix`	Appendix
`notes`	`footer`	—	back	`endnotes`	Notes
`endnotes`	`section.endnotes`	`doc-endnotes`	back	`endnotes`	Endnotes
`bibliography`	`section.bibliography`	`doc-bibliography`	back	`bibliography`	Bibliography
`glossary`	`section.glossary`	`doc-glossary`	back	`glossary`	Glossary
`index`	`section.index`	`doc-index`	back	`index`	Index
`colophon`	`section.colophon`	`doc-colophon`	back	`colophon`	Colophon
`credits`	`section.credits`	`doc-credits`	back	—	Credits

The four bare elements (header, nav, main, footer) imply the ids titlepage, toc, body, and notes; every other standard section is a <section> (or <nav> for loi/lot) named by its class. The machine table is STANDARD_SECTIONS in the engine (sections.ts).

A <nav> table of contents is real content — authored entries with real links — not generated navigation data; there is no serialized toc projection.

Matter

Several sections may belong to the same publication matter — front, body, or back. Standard sections derive matter from the table; a custom section defaults to body and may state data-spub-matter="front" or "back". Matter groups sections for publication semantics without nesting them: it neither reorders the stream nor limits how many sections a partition holds.

Membership and edge blocks

Everything inside a section element belongs to that section; the resolved membership is stored on the parsed document as SectionSpan ranges — derived at parse, never stored as data.

Blocks that are direct <body> children outside any section element are edge blocks: real blocks, rendered and styled normally per their kind, but belonging to no section — exempt from editor.sections placement rules and skipped by section-scoped features. There are no implicit or unnamed sections; a Project Gutenberg boilerplate header and license footer are edge blocks without fake sections invented for them.

Example

<body>
  <header>…title page…</header>
  <nav>…authored contents, real links…</nav>
  <main>…the work…</main>
  <section class="appendix" role="doc-appendix">…</section>
  <section class="synopsis" data-spub-matter="front">…a custom section…</section>
  <footer>…notes…</footer>
</body>

A renderer embedding a work in a larger page keeps the standard roles but must not introduce a second <main>; the body section then renders as a generic sectioning element instead.

Divisions

A division is a repeating structural heading — Act, Sequence, Scene, Chapter — that forms the document’s outline. Divisions are not declared separately: a block type becomes a division by carrying behavior.outline and a rank. They are unchanged by the section model and remain a distinct concept.

rank sets nesting depth — 1 is the top level (Act), higher numbers nest under it (Sequence 2, Scene 3). The outline indents by rank.
numbered gives a division an automatic running number; restartNumbering resets that count under each coarser division (a play’s scenes reset per act, where a screenplay’s run continuously).
summary attaches an auto-blurb to a division’s outline entry.

The outline and the character/location indexes are derived views over the content — computed from the blocks, never stored as structure.