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.

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:

Component (kind) Purpose
Page Controls paper size, margins, running heads, and page-break rules.
HeadersAndFooters Injects page headers, footers, and folios. Often paired with Handlebars templates from the assets/ folder.
Typography Sets base font families, sizes, and line heights.
TableOfContents Generates a table of contents with configurable depth and styling.
Bibliography Formats the reference list using the selected citation style.
Variant Applies JSON patches to tweak defaults—see Variants and presets.

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.

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.