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: Variantdefine 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.
ui.showTo: []hides theConfigurationblock from the settings form, so only developers change it, in the YAML. spec.readmeis 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. variantGroupscollect related layout presets (e.g. different page sizes) so authors cannot apply conflicting variants.- Monograph layouts use separate
HeadersAndFootersblocks for front, body, and back matter. Each block picks its Handlebars asset byidinspec.template.fileId: the three PDF blocks shareheaders-and-footers, and the HTML block usesheaders-and-footers-html.metadata.name(for-front,for-body,for-back) only tells the blocks apart, for example for variant patches.
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 identifier read by the template development kit. The app itself identifies a template by its directory name, so keep the two the same. |
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). |
citationStyleAlternative |
Further CSL styles authors can pick instead of the default. |
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. Assets are copied into export bundles unless they set static: false. |
labels |
Switch on exports in the export panel and advertise them as badges. They must match the components you configure (see below). |
variantGroups |
Optional UI groups to keep conflicting variants apart. |
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 the OJS export; monographs usually configure default languages, publishers, and variant groups. Record any extra expectations (for example, “fill in the book metadata before a BITS export”) inspec.readme.
Export labels in detail
Some labels decide which exports the export panel offers. Use them only when the template really supports the corresponding export:
reader— offers Reader and Reader Snapshot (ZIP). Add akind: Readercomponent to configure the Reader's look.jatsxml— offers JATS XML and JATS XML (ZIP). The article metadata comes from theArticleMeta,JournalMeta, andPermissionsMetacomponents.bitsxml— offers BITS XML. Add akind: BookMetacomponent for the book metadata.ojsxml— offers one OJS XML (ZIP) entry per OJS release. Add akind: Ojscomponent with the destination journal'ssectionRefanduserGroupRef(see OJS export); the export refuses to guess these values.
The other labels — princexml, pagedjs, html, and epub — are badges only. The export panel always offers PDF, PDF alternative (Paged.js), HTML, and EPUB, whatever the labels say. To keep a component out of one output, use its runners.
If a template lists a label but the prerequisite component is missing, the export may fail or lack metadata. Treat the labels as a 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
kindpicks the component class (see Components and layout).metadataholds identifiers or friendly labels. Thenamefield helps when you need to target a specific component from a variant patch.runnersrestrict where the component is used (princexmlfor PDF,htmlfor web,epub, etc.). Leave it out to include the component everywhere.pagecan pin the component to a layout region such ascover,front,body, orback.specstores 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. |
The A5 variant switches the Page default size to A5 and lowers font size, margins, and header heights. |
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. |
Not used; the monograph's only variant uses default patches. |
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.