Skip to main content
Recipe number 6

Cookbook · Chapter 5 · Book structure

Front matter in roman folios, then page 1

The cover and prelims are unnumbered headings counted in lower-case roman; :::numbering restarts the count at 1 on the recto where the novel opens.

On this page
Output
Canvas · PDF
Postext
Tested with Postext 1.65.0
Needs ≥ 1.34.0 · postext-pdf ≥ 1.34.0
Licence
Updated 16 Oct 2026
Code MIT · Text CC BY 4.0

p. i · 1 of 14

  • Trim 129 × 198 mm
  • 1 column
  • Fanwood Text 10.5/14
  • Cinzel
  • Playfair Display SC
  • 14 pages
  • Level
  • Postext 1.57.1
  • Laid out in 88 ms
  • 245 lines of code

In short

The opening pages of a pocket edition of Frankenstein. It shows how to number the pages before the story i, ii, iii, and start again at page 1 where the story begins.

What you'll build

The first leaves of Frankenstein as a pocket classic, 129 × 198 mm: a cover with lightning on Mont Blanc, its back left blank, a half title, a frontispiece of Walton’s ship beset in the ice facing the title page, the imprint low on its verso, the dedication to Godwin over Milton’s epigraph, a contents page and the Preface of 1818. Those ten pages are numbered i to x, but only the contents and the Preface print their numbers. Letter I starts the novel on a right-hand page, under the northern lights, and its folio reads 1 in the same place as the x on the facing page. The letter runs on to Walton’s signature. The ix beside the Preface in the contents and the 1 beside the letter come from the finished pages, and a PDF viewer labels the pages the same way. The cover, the frontispiece and the northern lights are paintings generated with diffusion models, loaded as JPEG bitmaps; the publisher’s mark and the ice crystal are drawn in code.

This recipe answers

  • How do I number the front matter in roman numerals and restart at 1 with chapter 1?
  • How do I make a cover, a half title, a title page and a colophon?
  • How do I add a table of contents that updates itself (leaders, page numbers, authors, part rows)?
  • How do I insert deliberate blank pages, or start a section on a fresh spread?
  • How do I set an epigraph, a dedication, a signature, or a pull quote with a big quote mark?

The short answer

script.js · lines 60–82in full code
// The page counter starts in lower-case roman: the cover is page i. After the Preface, two
// directives in the Markdown count again from 1 on the next recto:
//   :::pagebreak{parity="odd"}
//   :::numbering{format="decimal" startAt=1}
// :::numbering takes effect on the next page that starts (gotcha: numbering-next-page). Level 1
// breaks to 'odd', so here the pagebreak changes nothing; it finds the recto when a level breaks
// with parity 'any' or not at all. Never with 'always-odd': the blank pages would stack up.
const pageNumbering = { format: 'lower-roman', startAt: 1 }; // startAt spelled out: cover = i
// One folio design, centred under the text block. {pageNumber} prints the page's own label,
// so the same design sets "x" in the front matter and "1" on the first page of the novel.
const folio = (pages) => text(`folio-${pages}`, '{pageNumber}', 'Playfair Display SC', 8.5,
  at('top', 0, 9), { letterSpacing: pt(0.8), pages }); // lower case sets as small capitals
// The front matter is a heading style, unnumbered and left out of the contents (a heading
// can opt back in with {toc="true"}). It prints no running heads and puts a folio on every
// page of the section. Parity 'any', because the contents fall on a verso.
const front = {
  id: 'front', numbered: false, toc: false, breakBefore: { enabled: true, parity: 'any' },
  header: { elements: [] }, footer: { elements: [folio('all')] }, ...frontLook,
};
// The novel keeps the document's furniture: heads on its body pages, the folio on openers.
const footer = { elements: [folio('opener')] };
// Hook-up in config(): page: { pageNumbering }, headingStyles: [front] and footer at the top
// level. frontLook, set above, is the look of the prelims' openers.

Roman folios for the front matter and arabic from Letter I, in one design

Ingredients

Type
Fanwood Text, Playfair Display SC, Cinzel (SIL OFL 1.1)
Assets
  • band-1400.jpg
  • cover-1000.jpg
  • plate-1000.jpg
  • The cover: lightning over Mont Blanc and the lake of Geneva (Generated With Diffusion Models, original)
  • The frontispiece: a brig beset in pack ice, a dog sledge far off (Generated With Diffusion Models, original)
  • Letter I’s opener: northern lights over the frozen Neva (Generated With Diffusion Models, original)

Method

#1 · Each leaf is a heading with a design

script.js · lines 86–148in full code
// Each leaf is a heading, so it opens its page, gets a PDF bookmark and takes a design. The
// leaves are unnumbered, left out of the contents and print no heads or folio (blind folios).
// Parity 'any', or each would inherit level 1's odd break (gotcha: style-inherits-break).
const blind = { numbered: false, toc: false, breakBefore: { enabled: true, parity: 'any' },
  header: { elements: [] }, footer: { elements: [] } };
const PLATE_H = 126; // mm: the frontispiece, as wide as the text block; its caption hangs below
// mm from the trim: the imprint's eleven lines end on the text block's last baseline.
const IMPRINT_TOP = 126.4; // re-tune it whenever the imprint changes
const leaves = [
  // i: bled to the trim. The painting is as tall as the page, so the cover takes it whole.
  { id: 'cover', ...blind, advancedDesign: design([
    image('cover', at('top-left', 0, 0, { width: 'fill', to: 'bleed' })),
    label('author', '{author}', 9, onPage(22), 'bone', 2.6),
    text('title', '{title}', 'Fanwood Text', 56, onPage(31), { color: col('bone'), lineHeight: 1 }),
    text('subtitle', '{subtitle}', 'Fanwood Text', 13, onPage(53), { ...on('ice'), italic: true }),
    label('series', '{attr.publisher}', 7, onPage(168), 'ice', 2),
  ]) },
  // iii: the half title waits for a recto, so the back of the cover, ii, is left blank.
  { id: 'half', ...blind, breakBefore: { enabled: true, parity: 'odd' }, advancedDesign: design([
    text('title', '{title}', 'Playfair Display SC', 17, at('top', 0, 34), { letterSpacing: pt(3) }),
    image('crystal', at('top', 0, 45, { width: 6 })),
  ]) },
  { id: 'plate', ...blind, advancedDesign: design([ // iv: faces the title page
    image('plate', at('top-left', 0, 0, { width: 'fill' })),
    text('caption', '{attr.caption}', 'Fanwood Text', 8.8,
      at('top', 0, PLATE_H + 5, { width: 80 }), { italic: true, lineHeight: 1.3 }),
    label('source', '{attr.source}', 7.5, at('top', 0, PLATE_H + 16), 'muted', 1.3),
  ]) },
  { id: 'title', ...blind, advancedDesign: design([ // v: four frontmatter fields, one attribute
    label('edition', 'The text of {publishDate}', 7.5, at('top', 0, 22), 'accent', 1.8),
    text('title', '{title}', 'Playfair Display SC', 33, at('top', 0, 30),
      { fontWeight: 700, letterSpacing: pt(0.4), lineHeight: 1 }),
    text('subtitle', '{subtitle}', 'Fanwood Text', 14, at('top', 0, 44), { italic: true }),
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.8), color: col('accent'),
      placement: at('top', 0, 60, { width: 14 }) },
    label('author', '{author}', 10, at('top', 0, 66), 'ink', 2.4),
    image('mark', at('top', 0, 126, { width: 11 })),
    label('publisher', '{attr.publisher}', 7.5, at('top', 0, 140), 'muted', 1.5),
  ]) },
  // vi: the section's margins set the small print low, in a 70 mm measure against the outer
  // margin. hidden: the heading opens the page and names its bookmark, and prints nothing.
  { id: 'imprint', ...blind, hidden: true,
    margins: { top: mm(IMPRINT_TOP), left: mm(TRIM_W - OUTER - 70) } },
  // vii: dedication and epigraph, under a heading whose design is an ornament and no title.
  { id: 'quiet', ...blind,
    advancedDesign: design([image('crystal', at('top', 0, 24, { width: 6 }))], 34) },
];
// :::paragraphs blocks set the small print, the dedication, the epigraph and Walton's close;
// the dedication and the verse take one paragraph per line, so no line of them can reflow.
const VERSE_IN = 22; // mm: the indent that centres the verse as a block
const SOURCE_IN = 55; // mm: 'Paradise Lost' ends under the end of the longest line of verse
const prelimStyles = [
  { id: 'small-print', fontSize: pt(7.6), lineHeight: pt(10.4), textAlign: 'left',
    firstLineIndent: pt(0), spaceBetween: pt(5.2) },
  // Small capitals, with the italic lines of the 1818 page, leaded as one inscription.
  { id: 'dedication', fontFamily: 'Playfair Display SC', fontSize: pt(10), lineHeight: pt(15),
    textAlign: 'center', firstLineIndent: pt(0) },
  { id: 'verse', fontSize: pt(10), textAlign: 'left', firstLineIndent: mm(VERSE_IN),
    marginTop: pt(LEAD * 4) }, // on the body's 14 pt leading, which a style inherits
  { id: 'source', fontFamily: 'Cinzel', fontSize: pt(7.5), textAlign: 'left',
    firstLineIndent: mm(SOURCE_IN), marginTop: pt(4), color: col('muted') },
  { id: 'signature', textAlign: 'right', firstLineIndent: pt(0) }, // the letter's close
];

A heading opens a page of its own and becomes a PDF bookmark; the design in its style places the leaf’s type and pictures. With numbered: false and toc: false the leaves stay out of the chapter count and the contents. An empty header and footer give them what printers call blind folios: the title page prints no number but is still page v, which is why the Preface can be ix. Only the half title keeps an odd break, and that leaves the back of the cover blank. The imprint, the dedication, the epigraph and Walton’s close are :::paragraphs blocks set in the styles at the end of the excerpt.

#2 · The contents take their numbers from the layout

script.js · lines 152–161in full code
// Entries take the body's face and ink, and start on the Preface's first baseline, facing it.
const contents = {
  levels: [{ level: 1, fontSize: pt(12), lineHeight: pt(PREFACE.lead) }],
  // The folio's face: "ix" in small capitals, then a plain 1. The leader takes it too.
  pageNumber: { fontFamily: 'Playfair Display SC', fontSize: pt(10), color: col('accent'),
    width: mm(8) },
  leader: { char: '. ', gap: mm(2.5) },
  // A second line from the heading's to="…" attribute: whom each letter is written to.
  subtitle: { enabled: true, attr: 'to', fontSize: pt(9.5), color: col('muted') },
};

:::toc lists every heading its style lets in, with the label of the page it lands on (table of contents). The Contents and the Preface share the front style, which sets toc: false, and the Preface overrides it with {toc="true"}. Neither the Preface nor Letter I is numbered, so their entries print no chapter number. The second line of the letter’s entry is its to="…" attribute. The page numbers are set in the folio face. The entries start on the same baseline as the Preface’s first line, so the two facing pages line up.

#3 · The novel opens on a recto, under the northern lights

script.js · lines 165–180in full code
const BAND = 104; // mm from the trim to the foot of the drawing, which fades into the paper
// minHeight ends AIR mm below it and the first line takes the next grid line. to: 'bleed' is the
// trim until page.cutLines adds a bleed; 3 mm drop the foot 1.8 mm, still above that line.
const AIR = 2;
const opener = design([
  image('band', at('top-left', 0, 0, { width: 'fill', to: 'bleed' })),
  label('to', '{attr.to}', 7.5, onPage(19), 'ice', 2),
  text('title', '{titleText}', 'Playfair Display SC', 46, onPage(25),
    { color: col('bone'), lineHeight: 1 }),
  text('dateline', '{attr.dateline}', 'Fanwood Text', 10.5, onPage(44),
    { italic: true, color: col('bone') }),
  // The drawing reserves down to its foot. minHeight, counted from the text block (TOP below
  // the trim), is a floor AIR mm lower, which sends the first line one grid line further down.
], BAND - TOP + AIR);
// Walton's letters come before Chapter I: they take the novel's opener but no number.
const letter = { id: 'letter', numbered: false };

The painting bleeds off the head of the page and fades into the paper at its foot, where the letter begins. The opener reserves the page down to the painting's foot, 104 mm from the top of the page, and minHeight sets a floor 2 mm lower, which starts the letter one grid line further down, clear of the fade (span and advanced design). The kicker and the dateline come from the heading’s to and dateline attributes. Letter I also carries {style="letter"}, a style whose only setting is numbered: false, because Walton’s letters come before Chapter I and have no chapter number.

#4 · The running heads come back with the novel

script.js · lines 184–196in full code
const HEAD_Y = 12.5; // mm from the trim to the heads' line
const HEAD_GAP = 8; // mm from the outer margin, where the folio hangs, to the words beside it
const head = (id, content, parity, edge, x, extra = {}) => ({ ...label(id, content, 7.5,
  at(edge, x, HEAD_Y, { to: 'page' }), 'muted', 1.4), align: 'left', parity, pages: 'body',
  ...extra }); // pages: 'body' keeps them off the opener
const numeral = { fontFamily: 'Playfair Display SC', fontSize: pt(8.5), fontWeight: 400,
  letterSpacing: pt(0.6), color: col('ink') }; // folios in the folio face, as on the openers
const header = { elements: [
  head('verso-folio', '{pageNumber}', 'even', 'top-left', OUTER, numeral),
  head('verso-title', '{title}', 'even', 'top-left', OUTER + HEAD_GAP),
  head('recto-title', '{chapterTitle}', 'odd', 'top-right', -(OUTER + HEAD_GAP)),
  head('recto-folio', '{pageNumber}', 'odd', 'top-right', -OUTER, numeral),
] };

A section keeps the document’s header and footer unless its style replaces them. The front matter replaces both and the letter style does not, so from page 1 the novel prints these heads on its body pages and, on its opener, the drop folio defined in the short answer. {pageNumber} prints the label of the page it sits on, so the folio() helper sets x on one side of the spine and 1 on the other with the same design.

#5 · The PDF carries the same page numbers

script.js · lines 398–404in full code
// :::toc lists each heading with the label of the page it lands on; buildDocument lays the
// document out again until those labels stop moving (ix for the Preface, 1 for Letter I).
const doc = await buildDocumentWithFonts({ markdown, resources }, config(), kitFonts(FONTS));
showPages(doc, { title: 'Frankenstein · the opening leaves' });
// The PDF gets /PageLabels from the same labels: a viewer numbers its pages i–x, then 1, 2.
offerPdf(() => renderToPdf(doc, { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),
  `${RECIPE}.pdf`);

buildDocument repeats the layout until the page labels in the contents stop changing, so one call is enough. renderToPdf writes those labels into the PDF: in a viewer that reads page labels, the page-number field runs from i to x and then from 1, and “go to page 1” opens Letter I. Each heading becomes a bookmark named after its text, which is why the leaves have plain titles: Cover, Half title, Frontispiece, Title page, Imprint, Dedication.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 006 · Front matter: roman folios, then page 1 ═══════════
// https://postext.dev/en/cookbook/front-matter-roman-to-arabic
// Code: MIT · Text: M. & P. B. Shelley, 1818 (PD) · Pictures: diffusion models; marks drawn in code
// Fonts: Fanwood Text, Playfair Display SC, Cinzel (SIL OFL 1.1) · Needs postext ≥ 1.34.0
import {
  buildDocumentWithFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'front-matter-roman-to-arabic';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { // every colour in the config links to one of these
  ink: '#1c1d21', // text: a cold near-black
  accent: '#3d5a70', // steel blue, the one accent on paper: contents folios, the rule, the marks
  muted: '#6a665f', // running heads, sources, the second lines of the contents
  paper: '#fbf8f2', // the page
  night: '#131a24', ice: '#a9c6d6', bone: '#efe9dc', // the drawings' inks, and the type on them
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
const TRIM_W = 129, TRIM_H = 198; // mm: a pocket classic
const TOP = 21, BOTTOM = 23, INNER = 17, OUTER = 15; // margins, mm; heads align to OUTER
const MEASURE = TRIM_W - INNER - OUTER; // 97 mm: the text block, and the frontispiece's width
const LEAD = 14; // body leading in pt: 31 lines fill the text block
const PREFACE = { size: 9.8, lead: 13.3 }; // pt: the preface, a size under the novel's 10.5/14

// Design-slot shorthands. at(): a placement from an anchor's edge; edge 'top' centres it.
const wide = (width) => (width === 'fill' ? 'fill' : mm(width));
const at = (edge, x, y, { width, to = 'container' } = {}) => ({ anchor: { to, edge },
  offset: { x: mm(x), y: mm(y) }, ...(width !== undefined && { size: { width: wide(width) } }) });
const onPage = (y) => at('top', 0, y, { to: 'page' }); // centred on the page, y mm from the trim
const on = (id) => ({ color: col(id) }); // a design text's ink
// overflow 'wrap' for the running heads too, where a text too wide would end in '…'.
const text = (id, content, font, size, placement, extra = {}) => ({ kind: 'text', id, content,
  fontFamily: font, fontSize: pt(size), color: col('ink'), align: 'center', overflow: 'wrap',
  placement, ...extra });
const label = (id, content, size, placement, ink, tracking) => text(id, content, 'Cinzel', size,
  placement, { fontWeight: 600, letterSpacing: pt(tracking), textTransform: 'uppercase',
    ...on(ink) }); // the label voice: Cinzel capitals, tracked
const image = (id, placement) => ({ kind: 'image', id, resourceId: id, placement });
// A heading's design. minHeight (mm) where the text must start lower than the elements reach.
const design = (elements, minHeight) => ({ enabled: true, slot: { elements },

The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗ (opens in a new tab)

Variations

#Count the prelims in capitals

Upper-case numerals print as full capitals in the folio face, taller than the small capitals that lower-case numerals give.

-const pageNumbering = { format: 'lower-roman', startAt: 1 }; // startAt spelled out: cover = i
+const pageNumbering = { format: 'upper-roman', startAt: 1 }; // startAt spelled out: cover = I

#Number the book straight through

Leave out startAt and the count carries on in arabic figures, so Letter I becomes page 11, as in books that count their prelims with the text.

-:::numbering{format="decimal" startAt=1}
+:::numbering{format="decimal"}

#Leave out the frontispiece

Delete the # Frontispiece heading and send the title page to a recto: page iv stays blank, the Preface is still ix and Letter I is still 1.

-  { id: 'title', ...blind, advancedDesign: design([ // v: four frontmatter fields, one attribute
+  { id: 'title', ...blind, breakBefore: { enabled: true, parity: 'odd' },
+    advancedDesign: design([ // v: four frontmatter fields, one attribute

#Add a bleed and crop marks for press

With cutLines the cover and the opener, both anchored to the bleed, run 3 mm past the trim; the folios and the page count do not change (cut lines).

     backgroundColor: col('paper'), pageNumbering,
+    cutLines: { enabled: true }, // a 3 mm bleed and crop marks

Pitfalls

Pitfall

:::numbering takes effect at the next page

:::numbering changes the count from the next page that starts, not the current one. Put it right after a :::pagebreak (parity odd before chapter one) so the new numbering begins where you mean. Roman front matter →

Pitfall

A heading style inherits its level's page break

A headingStyles entry takes every field it leaves out from its heading level, breakBefore included. A contents page or a colophon styled on an H1 after a :::pagebreak inherits parity 'odd' and lands behind a blank page. Give such a style breakBefore: { enabled: false }. Heading styles →

Pitfall

Page 1 is a recto: plan pages with physical numbers

Page 1 is a right-hand page and page 2 the first verso, so plan spreads with physical page numbers: an opener on an even page faces the odd page after it. Page and column breaks →

Pitfall

A page takes the header of the last section that starts on it

When two heading styles start on one page, the page takes the header, footer and palette of the last one. A separator blank belongs to the chapter before it, parity padding to the chapter after it. Running heads per section →

Sandbox check · parityCascade

Parity cascade

Why. Parity breaks stack up and produce more than two blank pages in a row.

Fix. Review always-odd breaks and breakBefore parities; for short chapters, parity any usually avoids the blanks. Docs →

Sandbox check · numberingInvalidFormat

Invalid numbering format

Why. A :::numbering format is not one of decimal, lower-roman, upper-roman, lower-alpha or upper-alpha.

Fix. Use one of the five page-number formats; lists and resources spell theirs differently. Docs →

  • The leaves inherit level 1’s 'odd' break. Left alone, each one waits for a right-hand page. The prelims then run to fourteen pages instead of ten, with four more blank versos, and the frontispiece faces a blank page instead of the title page. Restate the break with parity: 'any', as this recipe does, or switch it off with breakBefore: { enabled: false }; a page-span heading opens its own page either way.
  • Drop the :::pagebreak before :::numbering when level 1 breaks with 'always-odd', the engine’s own H1 default. If the text before it ends on a right-hand page, the pagebreak pads to the next recto, then the heading adds its separator page and pads again, which leaves three blank pages in a row instead of one. After an 'odd' break, as here, the pagebreak changes nothing; after 'any', it is what puts page 1 on a recto.
  • A Preface that grows by one page pushes Letter I two pages on, because the odd-page break adds a blank verso before it. Check the page count whenever you edit the prelims.
  • The contents’ leader dots are set in the page numbers’ face and colour, and toc.leader has no colour of its own, so here they print in steel blue.

Credits

Text
  • Frankenstein; or, The Modern Prometheus (1818): the dedication, Letter I, a line of Letter IV (the frontispiece caption) and one of volume I, chapter VI (quoted in a code comment) · Mary Shelley · public domain
  • The unsigned Preface of the 1818 edition (by common attribution) · Percy Bysshe Shelley · public domain
  • Paradise Lost (1667), book X, lines 743–745: the epigraph of the 1818 title leaves · John Milton · public domain
Images
  • The cover: lightning over Mont Blanc and the lake of Geneva · Generated With Diffusion Models · original
  • The frontispiece: a brig beset in pack ice, a dog sledge far off · Generated With Diffusion Models · original
  • Letter I’s opener: northern lights over the frozen Neva · Generated With Diffusion Models · original
Fonts
Fanwood Text (SIL OFL 1.1) · Playfair Display SC (SIL OFL 1.1) · Cinzel (SIL OFL 1.1)
SandboxPDF