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

The first document must use kind: Configuration. It provides the human-readable title and global settings for the template.
Optional documents using kind: Variant define reusable presets (see Variants and presets).
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.

Sample: compact journal setup

---
kind: Configuration
spec:
  title: Journal Article
  description: A generic journal template
  type: journal
  readme: |
    # About
    This template will provide a basic one column PDF export with a choice of citation styles.
  citationStyle:
    id: apa
  citationStyleAlternative:
    - id: ieee
  labels:
    - princexml
    - html
    - epub
  assets:
    - id: logo
      type: logo
      path: tpl/generic-journal/assets/unicorn-journal-logo-wide.jpg
    - id: headers-and-footers
      type: hbs
      path: ./assets/headers-and-footers.hbs
      inline: true
ui:
  showTo: []

Journals usually highlight multiple citation styles and may keep ui.showTo: [] so only admins can select them until branded assets are ready.
spec.readme is rendered in the editor to explain when to use the template; keep it brief and link to internal guides if necessary.
Assets should include every Handlebars snippet and style the configuration references. Inline small files so they are bundled automatically.

Sample: monograph-focused configuration layer

---
kind: Configuration
spec:
  slug: generic-monograph
  title: Monograph template
  publisher: Unicorn University
  type: thesis
  language: de-DE
  languageAlternatives:
    - en-US
  labels:
    - html
    - epub
    - princexml
    - reader
    - bitsxml
  assets:
    - id: headers-and-footers
      type: hbs
      path: ./assets/headers-and-footers.hbs
      inline: true
  variantGroups:
    - name: page-sizes
      title: Page Sizes

Monographs often set a default language and publisher up front and enable archival exports such as bitsxml.
variantGroups collect related layout presets (e.g. different page sizes) so authors cannot apply conflicting variants.
Because monograph layouts rely heavily on cover/front/back matter, bundle separate header/footer assets and refer to them by metadata.name later in the file.

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.

Journal vs monograph defaults
Journals typically expose additional citation styles and Paged.js badges; monographs usually configure default languages, publishers, and variant groups. Record any extra expectations (for example, “requires coverpage asset”) in spec.readme.

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.

When documenting a component block, reference the schema URL at the top of the snippet. It keeps IDE completion working and signals which TypeScript source controls the available fields.

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.

Patch types at a glance

Variants rely on two patch modes. Use this guide to decide which one fits:

Patch `type`	What it changes	Ideal for	Journal example	Monograph example
`default`	JSON Schema defaults that appear when authors open the settings UI.	Tweaking starting values while keeping stored documents untouched.	Set the journal `Page` font size default to `11pt`.	Switch the monograph `Page` default size to `A5` in the `A5` variant.
`conf`	Saved configuration values inside `configuration.sfo.yml`.	Shipping a preset layout or injecting additional custom styles.	Add a `customStyles` block for Paged.js-only tweaks.	Insert engineering faculty-specific CSS in the `engineering` variant.

Always keep patch paths aligned with the component schema. If you target a specific instance (common in monographs with multiple header/footer blocks), include both target.kind and target.metadata.name so the patch stays stable.