Components and layout
Components are the building blocks of every export. They are implemented in libs/export/src/html/components and wired together through configuration.sfo.yml. Each component focuses on one area—pages, headers and footers, typography, tables of contents, figure handling, and so on. The default templates show two typical stacks:
- Journal articles (
generic-journal) usePage,HtmlPage,EpubPage,HeadersAndFooters,JournalTitle,TableOfContents,Footnote,Typography,GoogleFont,Environment,ParagraphNumbering, the metadata componentsArticleMeta,JournalMeta, andPermissionsMeta,Readerwith threeStaticpanels,Index, andOjs. They balance PDF and web outputs with minimal branching.generic-journal-tocis a separate template with nearly the same stack, withoutParagraphNumbering,Index, andOjs. - Monographs (
generic-monograph) add long-form helpers such asMonographTitle, multipleHeadersAndFootersblocks scoped by region,Contentseeds for cover pages,ContentHole,Listingsto build figure/table registers,PageOffset,BookMeta,Settings, and oneVariant.
How components are loaded
When an export runs, the loader (libs/tdk/src/template.ts) reads each component block in order and initialises the matching TypeScript class. The component receives the values from the block’s spec section and renders styles or markup back into the document.
Because components are executed sequentially, structure the configuration so the flow matches the final publication: cover page components first, then front matter, body, and appendices.
Common components
Below are some frequently used entries you will encounter in the default templates. Use the Example column to jump between journal and monograph snippets when you document your own components.
Component (kind) |
Purpose | Example |
|---|---|---|
Page |
Controls paper size, margins, running heads, and page-break rules for PDF/Paged.js. | Journal Page exposes single-sided A4 defaults; monograph Page configures two-page spreads and double-sided handling. |
HtmlPage / EpubPage |
Define typography and spacing for browser and EPUB exports. | Journals keep matching font stacks; monographs add hyphenation settings and deeper TOC depth in EpubPage. See Smart line wrapping. |
HeadersAndFooters |
Inject headers/footers via Handlebars templates and control folios. | Journals reuse a single asset across runners; monographs register separate blocks per layout region (front, body, back). |
MonographTitle |
Builds structured title pages with branded typography. | Only present in generic-monograph; include when books need a formal cover sequence. |
JournalTitle |
Renders the article title, subtitle, authors, and affiliations on the first page. | Both journal templates place it on the cover. See Affiliations in JournalTitle. |
Content |
Seeds boilerplate nodes (cover pages, acknowledgements) for new documents. | Monograph template pre-populates German cover sheets with placeholders. |
ContentHole |
Marks where the document's own parts go among the components of a region. | The monograph puts one on the front matter so the table of contents follows the front-matter chapters. |
Typography |
Sets base headings, numbering, and front-matter styling. | The journal turns heading numbering off (defaultNumberingStyle: none); the monograph numbers headings with a dot suffix. |
TableOfContents |
Generates navigational scaffolding; can be limited to specific runners. | generic-journal puts one on the cover, PDF only, depth 4. The separate generic-journal-toc template adds an "Agenda" with depth 2. The monograph raises the depth to 5. |
Listings |
Builds figure/table listings with optional localisation. | Only in the monograph template to reflect long-form publishing needs. |
Index |
Builds an index from the index entries marked in the text (renderMode, columnCount). |
generic-journal places it at the back (page: back). |
ParagraphNumbering |
Numbers the paragraphs of the document. | generic-journal enables it for the body (page: body, spec: {}). |
Footnote |
Footnote and endnote layout. | See Footnotes. |
GoogleFont |
Downloads and bundles fonts from Google Fonts. | See Fonts. |
ArticleMeta |
Article metadata: article type, version, issue, pages, identifiers, history dates. Used by JATS XML, OJS XML, and the templates' Handlebars snippets. | The journal templates preset articleType. |
JournalMeta |
Journal metadata: name, short name, ISSN, publisher. | The journal templates preset name. |
PermissionsMeta |
Copyright and licence. | The journal templates preset copyrightYear. |
BookMeta |
Book metadata for BITS XML and cover pages: identifiers, ISBNs, titles, publisher. | The monograph adds it with spec: {}, so authors fill it in. |
Ojs |
Destination settings for the OJS XML export. | Only in generic-journal. See OJS export. |
Reader |
Look and panels of the Reader: theme.color, theme.mode, and display (table of contents, figure panel). |
The monograph hides both panels by default. |
Static |
Renders a fixed piece of HTML (dom, with Handlebars helpers) and optional styles. |
The journal templates use it with runners: [reader] to add metadata and copyright panels to the Reader (metadata.reader.position: header or dca). |
Settings |
Editor shortcuts: quickSettings (paths shown in the quick settings panel) and quickEdits (command-palette entries). |
The monograph exposes the figure labels as quick settings. |
ArticleMetaSidebar |
A first-page metadata aside for PDF and HTML: masthead, history, keywords, corresponding author, citation, licence. | No shipped template uses it. See Article metadata sidebar. |
Variant |
Applies JSON patches to tweak defaults or apply presets. | The journal templates ship none; the monograph offers one, A5, in the page-sizes group. |
Environment |
Boxes, labels and numbering for environments, image transformation, and math macros. | See Math macros below. |
PageOffset |
Starts the page counter at a given number, for example for an article inside an issue. | The monograph places one on the front matter (page: front, PrinceXML only). See Page offset below. |
To explore all available components, browse the registry in libs/export/src/html/components/index.ts. Each component folder usually contains a *.schema.ts file that documents the supported options. Reference those files when writing documentation so you can point editors to the authoritative schema.
Making components configurable
The UI in the editor only exposes the fields declared in a component’s JSON schema. If you want authors to edit a value:
- Find the configuration path in the schema file (for example
properties/page/properties/margins/properties/inner). - Add the relevant field to the component’s
specblock inconfiguration.sfo.yml. - Optionally list the path in a separate
kind: Settingsblock underspec.quickSettingsso it appears in the “Quick settings” panel (seelibs/export/src/html/components/settings/settings.schema.ts).
kind: Settings
ui:
showTo: []
spec:
quickSettings:
components:
- component:
name: Environment
options:
- path: environments.image.label
description: Label (e.g. Bild, Figure, Abbildung)
Keeping configuration options tightly scoped to components helps new maintainers understand where a particular setting comes from and minimises the risk of breaking unrelated parts of the export.
Documenting component interplay
- Link back to the configuration. When you introduce a component, note which
assetsentry or metadata name the template expects. Example: the monographHeadersAndFootersblocks rely onmetadata.name(for-front,for-body,for-back) so variants can patch them individually. - Call out runner differences. Journals often share component specs across PrinceXML and HTML. Monographs split responsibilities—for example, a dedicated
HeadersAndFooterswithrunners: [html]to avoid PrinceXML-only features. - Surface localisation hooks. Components like
TableOfContentsandListingsaccepttranslationsblocks. Highlight where monographs set German labels so teams know how to add additional locales.
Math macros
A template can define short names for equations in its Environment block. An author writes x \in \R, and every export (PDF, HTML, EPUB, JATS, BITS) receives the expanded x \in \mathbb{R}.
kind: Environment
spec:
mathMacros:
R: { args: 0, body: '\mathbb{R}' }
vv: { args: 1, body: '\mathbf{#1}' }
pair: { args: 2, body: '\left( #1, #2 \right)' }
- Shape. Each entry is
name: { args: <0-9>, body: '<TeX>' }. The name is letters only, without a backslash, case-sensitive, and at most 64 letters.#1to#9in the body are the arguments; there are no optional arguments. A body has at most 4096 characters and no line breaks. - Quote bodies with single quotes. In a double-quoted YAML string the backslash starts an escape:
"\theta"becomes a tab plusheta,"\frac"a form feed plusrac.body: '\mathbb{R}'is right;body: "\mathbb{R}"is wrong. - Refused names. Names TeX or MathJax already define (
\frac, and also\abs,\norm,\set) are refused; pick another, for examplenrm. - Invalid entries are skipped, not fatal. The export logs a
MATH_MACRO_IGNOREDwarning per skipped entry, with the name and the reason, and uses the rest. Expansion never fails an export: an equation that grows too large is left as typed. - Documents can override. A document adds or changes single macros in its metadata under
Environment.mathMacros.<name>; it cannot remove a template macro. Templates without anEnvironmentblock still pick up the document's own macros. An equation that defines a name itself (\newcommand,\def) uses its own definition for the rest of that equation. - Headings and titles. Formulas in headings, the title and the subtitle are expanded before bookmarks, running heads, the table of contents, the EPUB navigation and OJS titles are made from them, so
\R^nreadsℝ^nthere. - Limit. Templates rendered by the legacy renderer do not support document macros.
Treat macro names as a public contract: authors type them into their equations. Renaming or removing one breaks every equation that uses it, so add a new name instead.
Page offset
PageOffset starts the page counter at a given number, for example when an article is page 45 to 60 of an issue.
kind: PageOffset
spec:
offsetKey: PageOffset.offset
firstPageSide: follow-number
offset: the number to start at. Prefer setting it in the document's metadata underPageOffset.offsetand pointingoffsetKeythere. Avoid the legacy top-leveloffsetkey: it comes with a schema default of 1, so every article would start at page 1 when no offset is set.firstPageSide(PDF only, defaultrecto):rectoalways starts on a right-hand page.follow-numberstarts on a left-hand page when the offset is even and on a right-hand page when it is odd, as in a printed issue where even pages are on the left. A first section forced onto a right-hand page (page break: right) still wins.- With
page: front,body, … the placement starts on a new page, and a blank page may be added before it.
Table themes
Tables pick a named theme in Environment under environments.table.theme. The built-in themes are plain, plain-outside, apa (the default), table1, table2, and table3; the journal templates use table1, the monograph table2. A template can add its own themes under environments.table.themes. A theme with the name of a built-in overrides it and keeps every field it does not set.
kind: Environment
spec:
environments:
table:
theme: house
themes:
- name: house
borderWidth: 0.5pt
borderColor: '#999999'
header:
backgroundColor: '#eeeeee'
fontWeight: bold
alternateRow:
backgroundColor: '#f7f7f7'
Cell and header text alignment are not part of a theme; authors set them per cell.
Table column widths
environments.table.columnWidths in Environment decides how column widths are applied:
fit(default): each column grows to fit its content.honor: columns keep the widths set in the editor, and the table is clamped to the page width. Tables with the same column widths then render at the same width; content that does not fit wraps.
It applies to HTML/PDF, JATS/BITS, and Markdown output.
Smart line wrapping in HTML
HtmlPage.page.font.textWrap turns on the browser's text-wrap for the HTML export:
wrap(default): browser default, output unchanged.pretty: avoids very short last lines in body text and balances short blocks such as headings and captions.balance: balances every block; long paragraphs are unaffected.
PDF output and browsers without support ignore it. With justified text, pretty can widen word spacing in Safari, so check the result.
Affiliations in JournalTitle
JournalTitle has options for where the author affiliations go and how they are numbered:
affiliations.floatPlacement(PDF only):none(default) lists them under the authors,bottomputs them in a float at the foot of the page, andfootnote-areaputs them in the footnote area, sharing its separator and counter.footnote-areaneeds aFootnotecomponent in footnote mode.affiliations.numberedBy:affiliation(default) numbers the affiliations, and each author points at one.authornumbers the authors, and each affiliation line lists the authors at it. Withfootnote-area, the numbers continue into the real footnotes.showCorrespondingInline(defaulttrue): set it tofalseto hide the corresponding-author line under the authors, for example when it is shown elsewhere.singleAffiliationIndex: whether a single affiliation still gets its superscript number.
The defaults leave existing templates unchanged.
OJS export
The Ojs component configures the OJS Native XML export (label ojsxml). It has no published schema yet, so the block has no $schema line.
kind: Ojs
spec:
version: '3.5'
versionAlternatives:
- '3.6'
sectionRef: ART
userGroupRef: Author
versionis pre-selected; each release inversionAlternativesgets its own entry in the export panel. Without anOjsblock, every supported release is offered.sectionRefis the abbreviation of the destination journal's section. A section set in the document's article metadata wins over it.userGroupRefis the name of the journal's author user group (for exampleAuthor, orAutor/inin a German install). OJS 3.4 and 3.5 need it; 3.6 does not use it.
OJS matches both values against the destination journal. A wrong value still gives valid XML but fails at the journal's import, so the export refuses to guess them. A journal with its own section abbreviations or a non-English user group must set them in its template.
Article metadata sidebar
ArticleMetaSidebar places a metadata aside on the first page of PDF and HTML exports: journal masthead, subject or article type, history dates, keywords, corresponding author, a recommended citation, and the licence. Each block can be switched off. It has no effect on JATS, BITS, or OJS output.
mode: band(default) reserves a column along the side of the first page and keeps the body in the other column.mode: wrapfloats the aside so the body text wraps beside it (PrinceXML).
The component exists, but no shipped template uses it. Add a kind: ArticleMetaSidebar block to try it; when you do, consider showCorrespondingInline: false in JournalTitle so the corresponding author is not shown twice.