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.

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 the Configuration block from the settings form, so only developers change it, in the YAML.
  • 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.
  • Monograph layouts use separate HeadersAndFooters blocks for front, body, and back matter. Each block picks its Handlebars asset by id in spec.template.fileId: the three PDF blocks share headers-and-footers, and the HTML block uses headers-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”) in spec.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 a kind: Reader component to configure the Reader's look.
  • jatsxml — offers JATS XML and JATS XML (ZIP). The article metadata comes from the ArticleMeta, JournalMeta, and PermissionsMeta components.
  • bitsxml — offers BITS XML. Add a kind: BookMeta component for the book metadata.
  • ojsxml — offers one OJS XML (ZIP) entry per OJS release. Add a kind: Ojs component with the destination journal's sectionRef and userGroupRef (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
  • 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, body, or back.
  • 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. 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.