Skip to content

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 lean on a concise set of components: Page, HtmlPage, EpubPage, HeadersAndFooters, and TableOfContents (optional). They balance PDF and web outputs with minimal branching.
  • Monographs add long-form helpers such as MonographTitle, multiple HeadersAndFooters blocks scoped by region, Content seeds for coverpages, and Listings to build figure/table registers.

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.
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.
Content Seeds boilerplate nodes (cover pages, acknowledgements) for new documents. Monograph template pre-populates German cover sheets with placeholders.
Typography Sets base headings, numbering, and front-matter styling. Monograph typography introduces margin tweaks and dotted suffixes; journals keep defaults lightweight.
TableOfContents Generates navigational scaffolding; can be limited to specific runners. Journal with TOC variant enables it via generic-journal-toc; monograph version raises depth to capture subparts.
Listings Builds figure/table listings with optional localisation. Only in the monograph template to reflect long-form publishing needs.
Variant Applies JSON patches to tweak defaults or apply presets. Journals use variants sparsely; monograph offers A5 and faculty-specific variants grouped under page-sizes.

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:

  1. Find the configuration path in the schema file (for example properties/page/properties/margins/properties/inner).
  2. Add the relevant field to the component’s spec block in configuration.sfo.yml.
  3. Optionally list the path under Configuration → spec.quickSettings so it appears in the “Quick settings” panel (see libs/export/src/html/components/settings/settings.schema.ts).

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 assets entry or metadata name the template expects. Example: the monograph HeadersAndFooters blocks rely on metadata.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 HeadersAndFooters with runners: [html] to avoid PrinceXML-only features.
  • Surface localisation hooks. Components like TableOfContents and Listings accept translations blocks. Highlight where monographs set German labels so teams know how to add additional locales.