Configuration Text

Configuration: body text

Part of the Configuration reference.

Generated from docs/configuration-text-en.mdx (updated 2026-10-16). 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.

Body text

The bodyText property controls the typography of all paragraph text.

Figure: Type scale Typographic hierarchy from H1 down to small body copy, showing relative sizes for headings, body text, and captions.

A consistent scale keeps hierarchy readable at a glance.

Figure: Spacing scale A step-based spacing scale showing increasing values used across margins, paddings, and gaps.

Spacing steps build up predictable rhythm through the layout.

Property	Type	Default	Description
fontFamily	string	'EB Garamond'	Font family for body text. Any Google Font, system font, or custom family declared in customFonts. One family, not a CSS font stack (see below).
fontSize	Dimension	8 pt	Base font size for body text.
lineHeight	Dimension	1.5 em	Vertical spacing between lines. Relative units (em, rem) scale with font size.
paragraphSpacing	boolean	false	When enabled, inserts a blank line (equal to lineHeight) between consecutive paragraphs for publisher-style separation.
color	ColorValue	#000000	Text color.
boldColor	ColorValue	Main Color (#295AA3)	Color applied to bold/strong spans. Resolved against the default palette's main-color entry, so changing the palette colour retints all bold runs across the document.
italicColor	ColorValue	Main Color (#295AA3)	Color applied to italic/emphasis spans. Same palette-linked default as boldColor.
referenceColor	ColorValue	Main Color (#295AA3)	Color applied to inline :ref labels (resource references). Same palette-linked default as boldColor. It follows the palette since postext 1.5; up to 1.4 it stayed #295AA3 whatever the Main Color was.
referenceBold	boolean	true	Render inline :ref labels with the bold font. A reference keeps the emphasis of the text around it (inside ***…*** it stays bold italic with either value); this option only adds bold on top.
referenceItalic	boolean	false	Render inline :ref labels in italics. A reference inside italic text stays italic with either value.
emphasis	'auto' | 'italic' | 'bold' | 'color' | 'overline'	'auto'	How *…* is set: in italics, in the bold face and boldColor, upright in italicColor, or upright with a rule over the words. 'auto' is 'bold' in a document written in Arabic script and 'italic' in any other. See Arabic text.
tashkil	'keep' | 'strip' | 'strip-vowels'	'keep'	Arabic vowel marks: set as written, all taken out, or taken out except the shadda. See Arabic text.
textAlign	'left' | 'justify' | 'start' | 'end'	'justify'	Text alignment. 'left' (or 'start') is the side a line starts on: the right of a right-to-left paragraph (see Text direction). Justified text distributes spacing across each line for even edges. Last lines of justified paragraphs render ragged at their natural width — except when Knuth-Plass accepted an overfull final line relying on glue shrink, in which case the inter-word spaces compress so the line fits the measure exactly (TeX glue-setting semantics, applied identically in the canvas, HTML, and PDF backends).
fontWeight	number	400	Weight for normal text (100–900).
boldFontWeight	number	700	Weight for bold/strong text (100–900).
hyphenation	HyphenationConfig	enabled, 'en-us'	Automatic hyphenation settings. See below.
firstLineIndent	Dimension	1.5em	Indent applied to the first line of each paragraph (or to all lines except the first when hanging indent is enabled).
hangingIndent	boolean	false	When enabled, the indent is applied to all lines except the first (French/hanging indent).
indentAfterHeading	boolean	true	When set to false, the first paragraph immediately following a heading is rendered without first-line indent — a typographic convention common in scientific publications and many book styles. The same applies to a paragraph right after a :::space line. A box set outside the text between them — in the side column (span: 'side'), floated to the head or foot of a page, or fixed — and a floated figure are looked past: in its column the paragraph still follows the heading, and is set flush. A box set in the text (placement: 'here') counts, and the paragraph after it is indented. Has no effect when hangingIndent is enabled.
maxWordSpacing	number	2	Upper bound for word spacing in justified text, expressed as a multiplier of the normal space width. Knuth-Plass keeps every line within it that the paragraph allows, hyphenating a word or spreading the slack over the neighbouring lines first; a line no set of breaks keeps within it stretches past it, and one past 3× the normal space is set ragged. Lines exceeding this ratio are considered "loose": see Lines the breaker cannot fill, and maxJustifyTracking to let them take a little tracking instead.
minWordSpacing	number	0.6	Lower bound for word spacing in justified text, as a multiplier of the normal space width. Both limits bound the change of each space from its own width, counted in spaces of the regular face: a line that holds an italic or a bold space, narrower or wider than the regular one, is painted a few hundredths of a space under or over the limit it was broken within. lineWordSpacing(line) gives the number the limits bound; see Justification.
maxJustifyTracking	number	0	Most tracking a justified line may take, in thousandths of an em either way (the InDesign unit: 10 = 0.01 em per character), when its word spaces alone would stretch past maxWordSpacing or shrink past minWordSpacing. The part of the adjustment beyond the limit goes into the letters, so a loose line's spaces come back to maxWordSpacing and a tight one fits at minWordSpacing. Knuth-Plass weighs it when it chooses the breaks, and only for the lines word spacing alone would take past the limits: the others, a paragraph's last line (unless it runs over), a line of one word and a line holding a chip take none. The line records it as letterSpacing, and the canvas, HTML and PDF paint it. Needs optimalLineBreaking. 0 turns it off. See Tracking as a last resort.
kashida	'auto' | 'none'	'auto' in an Arabic-script document, else 'none'	Kashida justification: a justified line of Arabic-script text takes its slack in its word spaces (up to a quarter of their width) and then in kashidas, whole tatweels (U+0640) inserted between two joined letters, never as letter-spacing. Knuth-Plass counts each word's elongation as stretch. Never in Latin words, digits, headings, ragged lines or a paragraph's last line. The tatweels are painted but left out of plain and copied text. See Kashida in Arabic text.
kashidaPatterns	'auto' | 'naskh' | 'simple' | 'nastaliq'	'auto'	Which joins take a kashida, and in what order: the classical Naskh rules, the Microsoft priorities, or the Naskh rules tailored for Nastaʿlīq (after raqim-kashida). 'auto' reads the body font: none in a Ruqʿa or Dīwānī face (Aref Ruqaa), Nastaʿlīq rules in a Nastaʿlīq face, Naskh otherwise.
kashidaPerWord	number	1	Most elongations in one word.
kashidaMaxLength	number	0.6	Longest elongation at one join, in ems; it takes as many whole tatweels as fit.
optimalLineBreaking	boolean	true	Use Knuth-Plass optimal line breaking instead of greedy first-fit. Produces more even word spacing across the paragraph. A Chinese, Japanese or Korean paragraph (see East Asian typography), or one with a word wider than the column, is still set line by line; a Latin paragraph that quotes a few CJK words keeps it. Ragged text takes it too with optimalRagged. See Hyphenation & Justification.
optimalRagged	boolean	true	Break ragged running text with Knuth-Plass too: body text, blockquotes and list items set left, right or centred, and ragged paragraph styles, box bodies and the bodies of parts and section styles. Word spaces keep their width. The breaker weighs how far each line falls short of the measure (a line 3 em short costs what a justified line at maxWordSpacing does), so it evens out the edge instead of filling each line before the next, and the runt rules (avoidRunts, tightenRunts) and hyphenateAcrossColumns work on ragged text as on justified text. With hyphenation.ragged the zone still decides which syllables may end a line (see Ragged text). Ragged headings, captions, notes, table cells and the contents are still set line by line. Needs optimalLineBreaking. false sets ragged text line by line, as up to postext 1.4; configurations stored earlier that set some running text ragged read with it (see Bundles written by postext 1.4 or earlier).
breakAfterDashes	boolean	true	Let a line end after an em or en dash set closed between words: say—that’s, riddles.—I, Hamburg–Berlin, also where the word after the dash is set in another style (see—*and*). Knuth-Plass takes it like a word space, and the line ends on the dash with nothing added. Never after a dash that opens an aside or a line of dialogue (—dijo, said "—Hola, sagte »—Ich: a space, or a space and a quotation mark, before the dash; after a quote that closes a word, as in "no"—and, German „nein“—und or French « non »—et, the line may end), before punctuation (él—,), before a quotation mark or a bracket (thinking—" and, says—“no”, says—(no): a quote after a dash often closes the speech the dash broke off), inside a run of dashes, or inside a range of numbers set with an en dash (1914–1918). false keeps the 1.4 breaks: Knuth-Plass never breaks after a dash, and the line-by-line breaker of formatted or hyphenated ragged text only between two letters; configurations stored earlier whose text sets such a dash read with it (see Bundles written by postext 1.4 or earlier). It applies to the running text, headings, lists, blockquotes and boxes. Captions, notes, table cells and the contents keep the 1.4 breaks, and a plain ragged paragraph set line by line follows pretext's own rules either way.
breakAfterHyphens	boolean	true	Let a line end after the hyphen of a compound, a hyphen between two letters (well- · known, vencer- · se), in every paragraph Knuth-Plass breaks. The line ends on the hyphen and nothing is added; the break is priced like a syllable. Never after a hyphen next to a digit or a sign (COVID-19, -5 °C). A justified paragraph without inline formatting breaks there only with two letters on each side of the hyphen, so no line ends on the e- of e-mail. false keeps the 1.4 breaks: a justified paragraph without inline formatting never breaks there, while the same paragraph with one italic word anywhere, a ragged paragraph and a paragraph set line by line do; configurations stored earlier whose text sets a compound read with it (see Bundles written by postext 1.4 or earlier). It applies to the running text, headings, lists, blockquotes and boxes. See Compound words.
repeatHyphen	boolean	false	Start the line after a break at a compound's hyphen with a hyphen too: vencer- · -se, as Portuguese spelling asks, and léxico- · -semántico, as the Spanish Academy's rules ask since 2010. The repeated hyphen is measured and painted with its line, which records it as repeatedHyphen; its plainStart and sourceStart point past it, so links, running heads and the Sandbox read the word as written. The PDF paints it under an /ActualText that leaves it out, so text copied or extracted from the PDF reads the word once. A web address never gets one. It applies to the running text, headings, lists, blockquotes and boxes; a paragraph without formatting that holds a compound is then broken by the breaker that sets formatted text.
hardLineBreaks	boolean	true	Read a backslash that ends a source line, and \\ before a space, as a forced line break inside a paragraph, a quotation or a list item (CommonMark's hard break): the next words start a new line of the same paragraph, and the line before is set at its natural width, as a last line is. A backslash ending the paragraph prints, and two spaces at the end of a line are no break (see Document format › Line breaks). false keeps the 1.22 reading: the backslashes print and the lines join with a space; configurations stored earlier whose text has such a backslash read with it (see Bundles written by postext 1.4 or earlier). Titles, captions, notes and table cells break at \\ either way.
scriptContext	boolean	true	Shape a word with no letter (46., 1367), ».: digits, punctuation or symbols alone) in the script of the text around it. A face may draw such marks by script (Amiri sets a Latin full stop and brackets in Latin text and Arabic ones otherwise, of other widths), and a shaper handed the word alone picks a script by a rule of its own, which differs between browser versions and the PDF. With this on, the word takes the script of the nearest letter before it in its isolate (else after it), of the nearest right-to-left letter when it is painted right to left, and of the document's language with no letter near; the layout measures it in that script, and the canvas, the HTML, the fixed-layout EPUB and the PDF paint those forms at that width. It acts in Latin, Greek, Cyrillic, Arabic and Hebrew contexts, and only in a face whose punctuation or digits change with the script; a word shaped in the Arabic script takes no letter-spacing. A piece with no letter of a word that has one (10.1006/ and .2001 of a DOI that ends a line at its joints) takes the script it has inside the word. In a Chinese or Japanese document a doubled ellipsis or dash (……, ——) cited in a sentence of another script keeps the forms of Han text. List markers, the labels of cross-references, design text, comic lettering and paragraphs set by the CJK composer are not touched. false shapes such a word alone, as up to postext 1.27; a configuration stored before configVersion 12 is read with it (pinLegacyScriptContext). See Words with no letter.
shapingLanguage	'document' | 'host'	'document'	The language the text is shaped in: measured, painted and embedded. A font answers with other glyphs under a language (OpenType locl): Noto Serif SC sets its digits otherwise in Chinese, a face with a Catalan form draws l·l otherwise, one with the Turkish rule keeps fi apart. 'document' (the default since postext 1.30): the document's own (locale, else the hyphenation language; a document that names none is English, en-US, and one whose locale is no language tag is shaped in no language), and a run's own where it names one (:ltr[…]{lang=en}). The layout sets it on every context it measures with, so a document breaks its lines the same on a page in any language and in a layout worker; the canvas paints in it, the HTML viewer and the EPUB declare it on the document and on each page, and the PDF shapes with the OpenType language system of the language. Since postext 1.30 the text is measured under it as it is painted. A string has one width whatever was measured before it: Chrome keeps the words it has shaped, and Noto Serif SC sets 2026 2.20 em wide in a string with no character past U+00FF and 2.23 em in one that has one, so the two kinds of string are measured on separate contexts. A right-to-left word is measured right to left in any face. A word the line breaker may cut (at a syllable or a hyphen) is measured whole and set whole where it stays on one line, on the canvas, in the HTML viewer and in the PDF, in any paragraph (since postext 1.31: up to 1.30.1 a paragraph without formatting measured each piece of such a word by itself, so what a face draws across a hyphenation point, the ff of of·fice in EB Garamond or the wide Catalan dot of Crimson Pro in l·l, showed in a word of a paragraph with an italic in it and not in the same word of a plain paragraph). Under 'host' a paragraph without formatting still measures each piece of such a word by itself. Of a word broken at a line end, each part is measured as the text painted: the part that opens the next line as a text of its own, and the first part of a Catalan col·lecció as col-. A design text (a running head, an opener, a heading design) is measured run by run, each run in the direction it is painted in. The PDF shapes word by word as the browser's canvas does (a word ends at a space, a tab, U+3000 or U+200B, and before a Han character), sets one by one the Chinese and Japanese characters the layout measured so, and takes each character from the font file the browser took it from when the font provider says which (see Chinese, Japanese and Korean fonts). 'host': as up to postext 1.28, the layout measures in the language of the page that hosts it (none in a worker) and the canvas paints in that same language; the HTML viewer declares the language of a Chinese, Japanese, Korean or right-to-left document. A document with 'host' keeps the widths and the PDF it had; in a paragraph with formatting its canvas and its HTML viewer also set whole a word that stays on one line (up to postext 1.29.2 they painted it piece by piece). Under it the part of a broken word that opens the next line is measured as the whole word less its first part, so a face whose form for the language needs the letters on both sides of the break (the Catalan l·l of Crimson Pro, a wide dot set only between two l) leaves a gap after the rest of the word, a third of an em in that face, on a page in that language. The default was 'document' in postext 1.29.0 alone, whose canvas and PDF did not follow the measure, 'host' in 1.29.1 and 1.29.2, and 'document' again from 1.30.0. A configuration stored before configVersion 14 that does not name the setting has 'host' written out (pinLegacyShapingLanguage), so a stored document keeps its lines; one that names a value keeps it. A browser whose canvas has no lang (Chrome before 136, and Firefox and Safari where it is missing) is given no language and keeps the forms it always measured, and the command line always lays out with 'host' (see Differences from the Sandbox).
tabStops	TabStop[]	unset	Tab stops of every paragraph, list item and quotation: where a tab (:tab, or a tab character in the text) sends the words after it. A paragraph style or a callout body that sets its own replaces them. Unset, a tab character is a word space, as it was before, and a :tab with no stop to go to is one too. See Tab stops. Since postext 1.23.
tabInterval	Dimension	unset	Default stops every interval from the start of the measure, past the last of tabStops. Unset, a tab past the last stop is a word space. Since postext 1.23.
blockquote	BlockquoteConfig	see below	How Markdown blockquotes (> …) are set: colour, italics and indents. See Blockquotes.

Blockquotes

A blockquote (lines that start with >) takes the body's family, size, leading, weights, alignment and hyphenation. bodyText.blockquote sets the rest; left unset, a blockquote looks as it did up to postext 1.4: grey, italic, with the body's first-line indent and no side indent.

Property	Type	Default	Description
color	ColorValue	#666666	Text colour. A colour linked to a palette entry (paletteId) follows that entry, as everywhere; the body's bold, italic and reference colours do not apply inside a blockquote.
italic	boolean	true	Set the text in italics. A *…* run inside turns back to upright; with false it is italic as in a paragraph.
indent	Dimension	0	Indent of every line from the left edge of the column or box. The measure narrows by it, so justified lines end at the right edge. em is the body's size.
firstLineIndent	Dimension	the body's	Indent of the first line of each quoted paragraph, counted from indent (with the body's hangingIndent, the indent of every line but the first). Unset: bodyText.firstLineIndent.

bodyText: {
  firstLineIndent: { value: 1.5, unit: 'em' },
  // Upright verse in the body colour, set in by 2 em, no first-line indent.
  blockquote: { color: { hex: '#241f26', model: 'hex' }, italic: false, indent: { value: 2, unit: 'em' }, firstLineIndent: { value: 0, unit: 'em' } },
}

In the Sandbox these are the Blockquotes group of the Body text section.

Verse

A :::verse poem whose lines carry no hemistich separator is set line by line (see Document format › :::verse). bodyText.verse gives the defaults of such poems; an attribute of the same name on a poem's fence sets it for that poem.

Property	Type	Default	Description
layout	'auto' | 'bayt'	'auto'	How a poem whose fence names no layout is set. 'auto': as bayts when a line carries a separator (||), line by line otherwise. 'bayt': as bayts always, a poem with no separator as centred single hemistichs, as up to postext 1.22.
indentStep	Dimension	0.5em	Width of one leading space of a line of verse (a tab counts four, an ideographic space two); em is the poem's size.
turnover	'hang' | 'right'	'hang'	How a line wider than the measure turns over: hanging on the next line, or flush with the end of the measure behind turnoverMark.
hang	Dimension	2em	Indent of a hanging turnover from its line's start, when the poem's paragraph style sets no hangingIndent.
turnoverMark	string	'['	The mark before a turnover set flush right.
stanzaSpace	number	1	Space between stanzas, in lines of the poem's leading. On the baseline grid it comes out whole grid lines; a paragraph style with snapToGrid: false keeps it exact.
keepStanzas	number	0	Keep any stanza of this many lines of verse or fewer whole in one column. 0 is off.
tighten	boolean	true	Tighten the word spaces of a line a little wider than the measure, down to bodyText.minWordSpacing of their natural width, and keep it on one line; only a line still too wide turns over. Letters are never tracked for it. false turns every line wider than the measure over, as postext 1.23 did. The reflowable EPUB, whose lines the reading system breaks, does not tighten.

bodyText: {
  // Turnovers flush right behind a bracket; tankas kept whole.
  verse: { turnover: 'right', keepStanzas: 5 },
}

A configuration stored before these settings (configVersion 8 or older) that lays out a poem with no separator is read with layout: 'bayt', so the poem keeps the centred lines postext 1.22 gave it. One stored by postext 1.23 (configVersion 9) that lays out a poem line by line is read with tighten: false, so its lines turn over where 1.23 turned them.

In the Sandbox these are the Verse group of the Body text section.

Tab stops

bodyText.tabStops lists the stops a tab goes to: :tab, or a tab character in a paragraph that has stops (see Document format › Tabs and tab stops for the markup and how a line is set). A paragraph style's tabStops replace them for its paragraphs and a callout style's body.tabStops inside its boxes; an empty list sets none. Each stop is a TabStop:

bodyText: {
  tabStops: [
    { position: { value: 30, unit: 'mm' } },
    { position: 'end', align: 'end', leader: '.', leaderGap: { value: 2, unit: 'pt' } },
  ],
  tabInterval: { value: 10, unit: 'mm' },
}

Property	Type	Default	Description
position	Dimension | 'end' | �0�	required	Where the stop stands, from the start edge of the paragraph's measure (after a paragraph style's indent; em is the paragraph's own size): a length, 'end' for the end edge of the measure, or a share of the measure ('50%'). In right-to-left text the start edge is the right one.
align	'start' | 'end' | 'center' | 'decimal'	'start'	How the text after the tab sits at the stop: it starts there, ends there (the text up to the next tab or the end of the paragraph), is centred on it, or has its decimal separator on it (a run with none ends there).
leader	string	none	Repeated over the room before the stop: '.', '. ', '·', '_', '-' or any short text, in the paragraph's face and colour; 'rule' draws a line a little under the baseline. The leader ends flush with the end of its room, so the leaders of several lines line up. It is measured as a whole run, as a contents row's is.
leaderGap	Dimension	0.5em	Room kept between the leader and the text on either side, as the contents' leader.gap. None before the leader when the tab opens its line, none after it when nothing follows.
decimalChar	string	the document language's	The separator a 'decimal' stop aligns on: . in English, Chinese, Japanese and Arabic, , in Spanish, Catalan, Portuguese, French, German and others.

tabInterval adds stops every interval from the start of the measure, past the last stop of the list; without it a tab past the last stop is a word space. A tab character typed in the text is a tab only in a paragraph whose style has stops or an interval, its own or the body's; everywhere else it stays the word space it always was, so a stored document lays out as before and needs no pin.

The stops are checked with the rest of the configuration (see Configuration warnings): an unknown key in a stop (leaders) is reported as unknownConfigKey with the key it is closest to; an align that is none of the four as unknownConfigValue, and the stop is set as 'start'; a position that is no length, 'end' or percentage as unknownConfigValue with used: 'none', and the stop is left out.

The leader colour and face are the paragraph's; there is no setting of their own yet.

Drop caps

A body paragraph can open with a drop cap: its first letter set large beside its first lines, which are shortened by the letter's width and a gap and set like any other lines (broken by Knuth–Plass, justified, hyphenated). A paragraph style gives one to the first paragraph of each :::paragraphs group in the style (every paragraph with each: true, for a catalogue of entries); a heading level or a heading style gives one to the first body paragraph after the heading (see the dropCap field of Per-level overrides, Paragraph styles and Heading styles). The paragraph after the heading is found past container fences, directives, boxes that left the flow and floated figures, as indentAfterHeading finds it; a paragraph inside a box, a list item, a quotation, a poem or a note never takes one. In the text, {dropcap}, {dropcap=false} and {dropcap=N} on a heading line or a :::paragraphs fence turn it on, off, or set its lines for that chapter or group (see Document format › Drop caps). Since postext 1.23.

headings: {
  levels: [
    { level: 1, dropCap: { lines: 3, fontFamily: 'Libre Bodoni', fontWeight: 700, color: { hex: '#8b2e2a', model: 'hex', paletteId: 'accent' }, leadIn: { words: 3 } } },
  ],
},

Property	Type	Default	Description
lines	number	3	Lines the initial spans, from the top of its capitals to its baseline. 1 with a larger fontSize is a raised initial standing on the first baseline.
sink	number	lines	Lines the initial drops into the text: it stands on the baseline of line sink, and those lines are shortened. Fewer than lines raises it above the first line.
characters	number	1	Grapheme clusters set large: É, a letter with a combining mark or a character outside the Basic Multilingual Plane counts as one. No further than the first word.
fontFamily, fontWeight, italic	string, number, boolean	the paragraph's; false	Face of the initial. It is loaded and embedded with the document's other faces.
fontSize	Dimension	see below	Size of the initial. Unset: the size that sets the top of its capitals level with the capitals of the first line while it stands lines lines down.
color	ColorValue	the paragraph's	A palette-linked colour follows part and section palettes.
gap	Dimension	0.15em	Space between the initial and the shortened lines, em being the text size.
punctuation	'with-cap' | 'hang' | 'text'	'with-cap'	An opening quote, ¿, ¡ or bracket before the letter: set large as part of the initial, hung at text size outside the measure before it, or set at text size at the start of the first line, after the initial.
leadIn	{ words, smallCaps, uppercase }	none	The first words words after the initial in small capitals (the default) or in capitals (uppercase: true); words: 'line' takes the words of the first line. A lead-in of the first line is counted on a first setting and set on a second: in small capitals the line may then hold a word more, set as written.
shortParagraph	'reserve' | 'shrink' | 'skip'	'reserve'	A paragraph of fewer lines than sink: keep the block sink lines tall so the next block clears the initial, set the initial over the paragraph's own lines, or set the paragraph without one. Each case raises a dropCap content warning.
each	boolean	false	Paragraph styles only: every paragraph of the group opens with the drop cap, not the first only.

How the letter is set:

• Size. Both cap heights, the text's and the initial's, are measured from their faces (the ink of an H; of the initial itself in Chinese or Japanese text), and a face that gives no ink metrics counts its capitals as 0.72 of its size. The default size suits any pair of faces, so a per-face correction is not needed. A design text's dropCap keeps its fixed 0.72 (see Text elements).
• The letter and its word. The initial takes whole grapheme clusters. The rest of the first word goes on after it with no space; a one-letter word (A, Y) keeps its word space at the start of the first line. The paragraph's own first-line indent is dropped. Copying, search, the source map and the Sandbox's caret read the paragraph as written: the block's plain text includes the letter, the first line's plainStart counts past it, and VDTBlock.dropCap holds its range and geometry on the fragment with the first line.
• A raised initial (lines: 1 with a larger fontSize, or sink under lines) rises above the first line, and the paragraph keeps that rise clear above it, in whole grid lines, so it does not overprint the text above.
• Breaking. The paragraph never breaks before line sink: it moves on whole to the next column or page instead, unless it is alone in an empty column that cannot hold those lines, where it breaks all the same and raises a dropCap warning. A heading kept with its text keeps those lines under it. The part that goes on in the next column carries no initial and full-width lines; broken again for a column of another width, the first lines keep their indent. Column balancing may set the paragraph loose or tight like any other, and never adds space between the shortened lines.
• Scripts. The lines are shortened on the start side: the left in Latin text, the right in Arabic and Hebrew. A letter that joins the next one (Arabic, Syriac, N'Ko) is not set apart, and the paragraph raises a dropCap warning; horizontal Chinese and Japanese take a one-character initial (首字下沉). Vertical text takes none (warning). A paragraph that opens with no letter or digit (a reference, a formula, a note mark) takes none either (warning).
• Outputs. The canvas, the HTML viewer and fixed EPUB paint the initial beside the lines; the HTML writes it right before the first line's text with nothing between, so a screen reader reads the word whole. In a tagged PDF the initial is part of the paragraph's P, and with the rest of its word a Span whose /ActualText is the word: text extraction reads Long before, never L ong before. A reflowable EPUB sets it as a CSS initial-letter (lines, sink), floated where the reading system does not support it.

The settings are checked with the rest of the configuration (see Configuration warnings): an unknown key in a drop cap or its lead-in is reported as unknownConfigKey, a punctuation or shortParagraph that is none of its words, or a lines, sink or characters that is no whole number from 1, as unknownConfigValue, and the default is used. Drop caps are off by default, so no stored document changes.

One family per fontFamily

fontFamily — here and in every other font-family field (headings.fontFamily, tableStyle.bodyFontFamily, separatorFontFamily, a chip style's or a design element's fontFamily…) — names one family. The canvas, the HTML output and the PDF must set the same face, and the PDF embeds one font per family with no fallback chain, so there is nothing for a CSS font stack to fall back to. A stack is set in its first family and reported as a configuration warning:

bodyText: { fontFamily: "'EB Garamond', Georgia, serif" } // set in EB Garamond

Load that family before laying out (see Custom fonts and the font provider under Generating PDFs); if it is missing, the browser measures with its default font, whatever the rest of the stack says. A comma inside quotes is part of a name ('"Foo, Bar"' is one family).

---

← Configuration: headers and footers · Configuration: hyphenation and language →