Configuration Comics

Configuration: comics

Part of the Configuration reference.

Generated from docs/configuration-comics-en.mdx (updated 2026-10-10). Read it on postext.dev, where it is also available in Spanish, Catalan, Portuguese, French, German, Italian, Chinese, Japanese and Arabic. To change this page, edit the MDX and run pnpm wiki in apps/web.

Comics

The comics property configures comic pages (:::page), strips (:::strip) and spreads: the frame and the gutters the panels are cut from, the panel styles, the lettering, the balloon styles and the cast. Only documents with comics read it; a document without them lays out exactly as before, and a document with comics and no comics section takes the defaults of its language. The markup and the way pages are lettered are explained in Comics.

const config: PostextConfig = {
  comics: {
    readingDirection: 'auto',
    gutter: { horizontal: { value: 5, unit: 'mm' }, vertical: { value: 2.5, unit: 'mm' } },
    panel: { borderWidth: { value: 0.8, unit: 'pt' }, borderStyle: 'rough' },
    panelStyles: [{ id: 'night', background: { hex: '#14142b', model: 'hex' }, borderColor: { hex: '#ffffff', model: 'hex' } }],
    lettering: { fontSize: { value: 8.5, unit: 'pt' }, textTransform: 'uppercase' },
    balloonStyles: [{ id: 'eerie', shape: 'wavy', italic: true }],
    cast: [{ id: 'maya', name: 'Maya' }, { id: 'tomas', name: 'Grandpa Tomás' }],
  },
};

Property	Type	Default	Description
readingDirection	'auto' | 'ltr' | 'rtl'	'auto'	The order of the panels in a tier. 'auto' reads right to left in a right-to-left document, in a vertical one and in Japanese and Traditional Chinese, and in the direction of artDirection otherwise (Simplified Chinese and Korean included). A page's direction attribute overrides it. With page.binding: 'auto', a book whose comics read right to left is bound on the right.
artDirection	'ltr' | 'rtl'	'ltr'	The reading direction the art was drawn for: 'rtl' for manga.
mirrorArt	boolean	false	Flip the pictures of a page read in the other direction than artDirection. A panel keeps its picture as drawn with mirror=false.
frame.margins	PageMargins	the page margins	Margins of their own for comic pages (top, bottom, left, right, mirror). The panels are cut from the box they leave; unset, from the page's text area.
gutter.horizontal	Dimension	4mm	The room between tiers. A page's gutter attribute overrides it.
gutter.vertical	Dimension	2mm	The room between panels side by side in a tier.
panel	PanelStyleConfig	see below	The default panel style.
panelStyles	NamedPanelStyleConfig[]	[]	Named panel styles, picked with :::page{style=…} or ::panel{style=…}. Each has an id, an optional name (editor UIs only) and the fields of a panel style; unset fields follow panel.
lettering	LetteringConfig	see below	The face, size and house rules of every balloon of the book.
balloonStyles	BalloonStyleConfig[]	the nine built-in styles	Balloon styles by kind. The built-in ones are always there; an entry with one of their ids changes it, an entry with a new id adds a style laid over speech.
cast	ComicCastMember[]	[]	The characters (see Cast).
runningHeads	boolean	false	Print the running heads and folios on comic pages. Off, a comic page is all panels and its number still counts.
viewerLeaf	ComicViewerLeafConfig	unset	For hosts whose pages are not leaves: lays comic pages out on a print leaf (width, height, margins) scaled to fitWidth px (and at most fitHeight px tall) at the top of the page. The Sandbox's HTML viewer sets it; it is never saved with a document.

Panel styles

comics.panel and each entry of comics.panelStyles:

Property	Type	Default	Description
borderWidth	Dimension	1pt	Border width; 0 draws none. The border is stroked on the panel's outline.
borderColor	ColorValue	black	Border colour (palette-linkable).
borderRadius	Dimension	0	Corner radius of a rectangular panel, clamped to half its shorter side. A panel cut by a slanted line keeps sharp corners.
borderStyle	'solid' | 'rough' | 'none'	'solid'	A clean line, a hand-drawn line that wobbles a little (seeded from the panel, so the same on every build), or none.
background	ColorValue	white	The fill under the picture: the colour of an empty panel and of the bands around a picture shown whole.
fit	'cover' | 'contain'	'cover'	cover crops the picture to fill the panel, never into its safe area; contain shows it whole.
bleed	boolean	false	Panels in this style run past the frame to the trim and the bleed on every side that touches the frame.

Lettering

comics.lettering sets every balloon of the book. There is one size: a balloon style can scale it (fontScale), and text is never shrunk to fit a balloon.

Property	Type	Default	Description
fontFamily	string	by language	The lettering face. Unset: Comic Neue; Zen Antique in Japanese, Noto Sans SC in Simplified Chinese, LXGW WenKai TC in Traditional Chinese, Playpen Sans Arabic in Arabic, Persian and Urdu (defaultComicFont(locale)).
fontSize	Dimension	7.5pt	The size of balloon text. Comics are usually lettered at 7 to 9 pt on the printed page.
lineHeight	number	1.15	Distance between lines, a multiple of the size. Left at the default, vertical, Chinese and Japanese balloons take 1.5 and Arabic ones 1.45.
color	ColorValue	black	Text colour.
bold, italic	boolean	false	Set all the lettering bold or italic. Chinese, Japanese and Arabic lettering is never slanted.
letterSpacing	Dimension	0	Extra room between letters; em is relative to the text size. Never applied to Arabic. It does not change the glyphs: ligatures stay.
writingMode	'auto' | 'horizontal' | 'vertical'	'auto'	'auto' letters Japanese and Traditional Chinese, and any document set in vertical writing, in vertical columns, and everything else horizontally. A script line's vertical or horizontal flag sets that line otherwise (see Comics › Lettering).
textTransform	'none' | 'uppercase'	'none'	All capitals, the classic look of American and European lettering. Scripts without case are left as they are.
dropFinalStop	'auto' | boolean	'auto'	Leave out the full stop that ends a balloon (。 in manga). 'auto': in Japanese and Chinese only.
doubleDash	boolean	false	Letter an em dash as --, a habit of American lettering.
inset	Dimension	1.5mm	Room kept between a balloon and its panel's border. A caption butted to the border ignores it.
joinSameSpeaker	'butt' | 'connector' | 'none'	'butt'	Two balloons in a row from the same speaker: bodies merged into one outline, linked by a narrow neck, or kept apart. A script line asks for its own with join or join=false.
maxColumnChars	number	8	Vertical lettering: the most characters in one column of a balloon. Sound effects break after five.
strictPlacement	boolean	true	A balloon reshaped to fit its panel does not part a Chinese word to do so: each word its new lines cut, which its preferred shape leaves whole, costs more than a balloon read out of order, so the placement moves the balloon or changes the order first. Japanese lettering, broken by phrases, is not touched. false letters as postext 1.27 did; a document stored before 1.28 that holds a comic is read with it.

Balloon styles

Each entry of comics.balloonStyles is laid over the built-in style of the same id (speech, thought, whisper, shout, radio, caption, inner, note, sfx), or over speech for a new id. The defaults below are those of speech; the Comics page lists what each built-in style changes. Lengths in em are relative to the balloon's text size.

Property	Type	Default	Description
id	string	required	The word a script line names the style with: ben{whisper}: … or style=whisper.
name	string	id	Human-readable name, for editor UIs only.
shape	'oval' | 'rounded' | 'rectangle' | 'cloud' | 'burst' | 'wavy' | 'electric' | 'none'	'oval'	The outline around the text. 'none' sets the text straight on the picture.
fill	ColorValue	white	Balloon fill.
stroke	ColorValue	black	Outline colour.
strokeWidth	Dimension	0.6pt	Outline width.
dash	boolean	false	A dashed outline (a whisper).
double	boolean	false	A double outline.
wobble	number	0	Hand-drawn wobble of the outline, 0 to 1, seeded from the balloon so it never changes between builds.
roundness	number	2.2	The superellipse exponent of an oval: 2 is an ellipse, higher values are squarer.
burstPoints	number	14	The spikes of a burst; 0 counts them from the perimeter.
burstDepth	number	0.22	The depth of a burst's spikes, a fraction of the body's radius.
padding	Dimension	0.55em	The air between the text and the outline.
aspect	number	1.6	The width over height the line breaking aims the text block at (horizontal lettering).
tail	'curved' | 'wedge' | 'bubbles' | 'zigzag' | 'none'	'curved'	The tail.
tailWidth	Dimension	0.9em	The width of the tail where it leaves the outline.
tailReach	number	0.55	How far the tail reaches toward its speaker, a fraction of the gap from the outline to the mouth.
target	'mouth' | 'head'	'mouth'	What the tail points at: the anchor's mouth, or its head (thought balloons).
position	'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'top' | 'bottom'	'auto'	Where the balloon goes when the line pins none: placed by the lettering, or at a corner or edge of the panel.
butt	boolean	false	Set a corner or edge balloon flush against the panel border (captions).
fontFamily	string	the lettering face	The face of this style. sfx defaults to the sound-effect face of the language: Bangers, Dela Gothic One in Japanese, ZCOOL KuaiLe in Simplified Chinese, LXGW WenKai TC in Traditional Chinese, Lalezar in Arabic (defaultComicSfxFont(locale)).
fontScale	number	1	The text size, a multiple of the lettering size.
bold, italic	boolean	the lettering's	Bold or italic text.
color	ColorValue	the lettering's	Text colour.
textTransform	'none' | 'uppercase'	the lettering's	All capitals for this style.
letterSpacing	Dimension	the lettering's	Extra room between letters.
align	'center' | 'start'	'center'	Line alignment inside the balloon.
halo	Dimension	none	An outline drawn around the letters, its width, so text reads over the picture (sound effects).
haloColor	ColorValue	white	The colour of the halo.
rotate	number	0	Rotation in degrees, clockwise. A line's rotate attribute wins.

Cast

Each entry of comics.cast describes a character:

Property	Type	Default	Description
id	string	required	The speaker key of the script and of the pictures' anchors.
name	string	id	The name the HTML output and the reflowable EPUB print before the character's lines, and editors show.
balloonStyle	string	speech	The style of the character's lines that name none.
color	ColorValue	the style's	Text colour of the character's balloons.
fill	ColorValue	the style's	Fill of the character's balloons.
fontFamily	string	the style's	The face of the character's balloons.

A line's own color and font win over the cast, and the cast over the balloon style. Every comic colour may be a palette entry, which follows the palette like any linked colour.

const resolved = resolveComicsConfig(config.comics, 'ja');
// => every field filled; Zen Antique and Dela Gothic One as the faces

const minimal = stripComicsDefaults(config.comics, 'ja');
// => undefined when everything is a default

const shout = pickBalloonStyle(resolved, 'shout'); // the built-in shout with the book's changes
const night = pickPanelStyle(resolved, 'night');   // a named panel style, else the default panel

---

← Configuration: callout boxes · Configuration: composed pages →