Skip to content

Templates

Templates control how a project looks in every export. They bundle styles, assets, and configuration so that authors can focus on their content while the system handles layout.

What you get out of the box

Our default installation ships with the Generic Monograph and Generic Journal templates. Each template exposes friendly settings in the editor—paper size, headers, fonts, and more—so you can start with sensible defaults and fine-tune only when needed.

Supported export formats

  • PDF (PrinceXML is our primary engine; Paged.js remains available for experimentation with limited functionality)
  • HTML for the responsive reader
  • EPUB
  • XML (JATS and BITS)

About Paged.js

We support the open-source Paged.js ecosystem and keep it available for teams who want to experiment. For production-grade publishing, especially when accessibility and precise layout control are essential, we recommend staying with PrinceXML.

Where templates live

Templates are stored on disk. Standard installations include them so you can use them immediately. When you start the container it serves our standard templates from here. You can copy these into your own instance template directory or make use of the community templates.

Each template directory follows the same pattern:

File or folder generic-journal (journal) generic-monograph (monograph)
configuration.sfo.yml Drives a compact one-column layout with shared settings for PDF, HTML, EPUB, Paged.js, and Reader exports. Adds monograph-specific components (cover structure, listings) and variant groups for alternative page sizes.
metaData.schema.yml Defines lightweight project metadata (for example themeColor). Captures more extensive dissertation metadata and localisation defaults.
styles.scss Registers utility styles and PDF tweaks bundled in assets. Not present—monograph styles live entirely in component customStyles for clarity.
assets/ Holds Handlebars header/footer snippets and logos used by PDF and Paged.js runners. Includes multiple header/footer variants (cover, front matter, HTML) plus title-page templates.

Use the two samples together: the journal template shows the minimal building blocks, while the monograph template demonstrates how to scale the same structure for multi-part publications.

How rendering works (high level)

  1. The editor reads configuration.sfo.yml to show human-friendly settings.
  2. When you export, the pipeline loads the configuration and assets from disk (see libs/tdk/src/template.ts).
  3. Individual components—like headers, typography, or the table of contents—render into the document based on the settings you selected.
  4. Optional variants apply JSON patches to adjust defaults (for example, switching between single- and double-sided layouts).

You do not need to understand the TypeScript source to get started, but it is helpful to know that every toggle in the UI ultimately maps back to these configuration files.

From clone to production

  1. Copy a reference template. Duplicate generic-journal when you need a lightweight article layout; choose generic-monograph for multi-part books or theses.
  2. Rename and retitle. Update spec.slug, spec.title, and spec.description in configuration.sfo.yml so authors can find the new template. Journals often expose multiple citation styles, while monographs may set default languages or publishers.
  3. Align assets and metadata. Replace logo files, adjust metaData.schema.yml, and review ui.showTo to control visibility. Monographs usually require extra coverpage assets and multi-language labels.
  4. Expose only supported exports. Keep spec.labels in sync with the configured runners; the journal sample enables Paged.js, whereas the monograph omits it and adds bitsxml for archival output.
  5. Test every export. Run HTML, PrinceXML PDF, and any additional outputs before shipping. Monograph variants (such as the A5 preset) require testing with and without the variant applied.

Document the customisations you make—especially variants, metadata fields, and asset conventions—in the spec.readme block so others can maintain the template.

Customising templates safely

The quickest way to customise a standard template is from the editor: open Document settings → Template options and adjust typography, margins, or other exposed controls. These choices are stored alongside the document, so you can experiment without altering the base template.

Settings UI showing multiple options to customise a template

Settings UI example

Template authors decide which options appear in the editor by editing configuration.sfo.yml.

To change the defaults for everyone, copy the template directory and edit its files. Typical next steps include:

  • Adjusting default values inside configuration.sfo.yml
  • Updating assets (logos, headers, additional styles)
  • Extending metadata schemas or providing translations

Learn more

Use the guides in this section when you are ready to dive deeper:

  • Configuration basics — structure of configuration.sfo.yml, the most common keys, and how they surface in the editor.
  • Components and layout — how reusable components such as headers, typography, and tables of contents work together.
  • Assets and media — managing Handlebars templates, images, and styles referenced from the configuration.
  • Variants and presets — using variants to offer predefined layouts without duplicating an entire template.
  • Fonts — packaging custom fonts and linking to hosted services.
  • Metadata extensions — defining custom data your template consumes.
  • Styling conventions — deciding between global SCSS and component-level CSS.