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 three templates. The editor lists them by their spec.title:

Directory Listed as For
generic-journal Journal Article A one-column journal article, including OJS export.
generic-journal-toc Report The journal template with a table of contents ("Agenda") and without OJS export. It is a separate template, not a variant.
generic-monograph Monograph template A book or thesis with seeded cover pages, chapters, and lists of figures and tables.

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 is offered as "PDF alternative" for experimentation, with limited functionality)
  • HTML, as a single file or as a ZIP with its assets
  • EPUB
  • Reader, plus a Reader Snapshot (ZIP) that a separately hosted Reader loads
  • JATS XML (articles) and BITS XML (books)
  • OJS Native XML for OJS 3.5 and 3.6
  • Data Snapshot (ZIP), a copy of the document for another installation

Which of these a template offers depends on its spec.labels (see Export labels). The user manual describes each format from the author's side in Choose a format.

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 for PDF, Paged.js, HTML, EPUB, Reader, JATS XML, and OJS XML exports. Adds monograph components (MonographTitle, Content seeds for the cover pages, Listings), separate header/footer blocks for front, body, and back matter, and one variant (A5) in the page-sizes group.
metaData.schema.yml Defines one custom field, themeColor, used by the header asset. Defines a single free-text comment field; book metadata comes from the BookMeta component instead.
styles.scss A short stylesheet for the title metadata and the Reader header; the loader adds it automatically. Not present. The monograph uses no custom CSS; its look comes from the component settings.
assets/ Holds Handlebars header/footer snippets (PrinceXML and Paged.js) and logos. Holds two header/footer snippets (PDF and HTML) and a logo. The cover pages are not assets: the Content block seeds them as editable parts of a new document.

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. Give the template its own directory name: the app identifies a template by its directory. Also update spec.slug (read by the template development kit), 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 need their own cover-page seeds in Content and multi-language labels.
  4. Expose only supported exports. Keep spec.labels in sync with what the template supports: reader, jatsxml, bitsxml, and ojsxml switch the matching exports on. The journal sample lists jatsxml and ojsxml; the monograph lists 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 Export configuration, choose the template, and click the gear (Open Template Configuration). Adjust typography, margins, or other exposed controls there. These choices are stored with the document once you save it, so you can experiment without altering the base template. See Make simple changes in the settings in the user manual.

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 adding translations to components

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.