Skip to content

Configuration basics

Every template has a configuration.sfo.yml (sometimes named configuration.yml). This file contains several YAML documents separated by ---. Together they describe what the template does, which options appear in the editor, and which components render during export.

File layout at a glance

  1. The first document must use kind: Configuration. It provides the human-readable title and global settings for the template.
  2. Optional documents using kind: Variant define reusable presets (see Variants and presets).
  3. The remaining documents configure individual components such as headers, typography, or the table of contents.

The order matters: components appear during export in the same order they are listed in the file. Keep related blocks together so future maintainers can follow the flow from cover pages through back matter.

Core keys in the main Configuration

The interface is defined in libs/export/src/html/components/configuration/configuration.schema.ts. The most commonly used fields are:

Key Why it matters
slug Optional stable identifier referenced by other systems.
title Display name shown in the editor when users pick a template.
description Short explanation so teams understand when to use it.
type A category (journal, thesis, general, scientific, or monograph) used for filtering.
citationStyle.id Default CSL style applied to references (for example apa).
language / languageAlternatives Default UI language and fallback locales.
assets List of files bundled with the template—logos, Handlebars snippets, extra stylesheets. Each entry can set inline: true to embed the file content directly.
labels Short badges that advertise which exports the template supports. They must match the components and runners you configure (see below).
variantGroups Optional UI groups to keep conflicting variants apart.
subTemplates Predefined stacks of variants that appear as ready-made presets.

Any additional keys are ignored by the schema loader but should generally be avoided unless you are migrating older templates.

Export labels in detail

Labels are important for what is being available as an export in the editor. They also help editors pick the right template by displaying small badges such as “PDF” or “EPUB”. Use them only when the template really supports the corresponding export:

  • html — list this when the configuration contains components with runners: [html] (or no runners) so an HTML export is available.
  • epub — add when you include EPUB specific runners.
  • princexml — indicates the PDF exporter works; ensure the relevant components include princexml in their runners.
  • reader — set when the template includes a kind: Reader component so the web reader has the necessary layout pieces.
  • bitsxml — requires a kind: BookMeta component to provide the metadata used in BITS XML exports.
  • jatsxml — requires a kind: JatsMeta component for JATS XML exports.

If a template lists a label but the prerequisite component or runner is missing, the badge becomes misleading and exports may fail. Treat the labels as a quick promise to users: only add them when the setup satisfies the matching condition.

Describing components

Each component document has the shape:

# yaml-language-server: $schema=https://…/TableOfContents.json
kind: TableOfContents
metadata:
  name: default-toc
runners:
  - princexml
  - html
page: front
spec:
  depth: 3
  showPageNumbers: true
  • kind picks the component class (see Components and layout).
  • metadata holds identifiers or friendly labels. The name field helps when you need to target a specific component from a variant patch.
  • runners restrict where the component is used (princexml for PDF, html for web, epub, etc.). Leave it out to include the component everywhere.
  • page can pin the component to a layout region such as cover, front, or body.
  • spec stores the settings exposed by that component’s JSON schema.

Schema assistance in editors

Most sample files begin with a comment like # yaml-language-server: $schema=https://…. When present, IDEs that support YAML Language Server auto-completion can validate the document against the schema shipped with the export pipeline. If you copy a component block, keep the schema URL so other authors get inline documentation for free.