Skip to content

Assets and media

Templates bundle everything they need—stylesheets, logos, header snippets—so exports stay self-contained. These assets live beside configuration.sfo.yml inside the template directory.

Registering assets in the configuration

The main Configuration block contains an assets array. Each entry looks like this:

spec:
  assets:
    # Journal assets
    - id: logo
      type: logo
      path: tpl/generic-journal/assets/unicorn-journal-logo-wide.jpg
      dimensions:
        width: 1173px
        height: 586px
    - id: headers-and-footers
      type: hbs
      path: ./assets/headers-and-footers.hbs
      inline: true
    - id: asset-styles
      type: asset
      path: ./styles.scss
      inline: true

    # Monograph assets
    - id: headers-and-footers
      type: hbs
      path: ./assets/headers-and-footers.hbs
      inline: true
    - id: headers-and-footers-html
      type: hbs
      path: ./assets/headers-and-footers-html.hbs
      inline: true
  • id references the file from component blocks, usually as spec.template.fileId: headers-and-footers.
  • type is a free-form label; logo, hbs, and asset are common values.
  • path is relative to the template directory. Use ./ to stay within the template folder or tpl/... when assets should be mounted for downstream use.
  • inline: true embeds the file content directly into the configuration. The loader in libs/tdk/src/template.ts reads the file and attaches it to the asset so that exports do not need to access the filesystem later.
  • role and dimensions are optional hints for downstream consumers.

Journal vs monograph
Journals typically use one headers/footers partial for PrinceXML and a second, simpler one for Paged.js. The monograph registers one partial for PDF, shared by its front, body, and back HeadersAndFooters blocks, and one for HTML. Make sure the component blocks and assets stay in sync.

Assets are static by default: they are copied to export bundles, even if the file is not referenced elsewhere. Set static: false to leave an asset out.

Stylesheets

A template-wide stylesheet named styles.scss is automatically picked up. During loading the file is registered as the asset-styles asset and added as the first style in the export pipeline (stylePaths in libs/tdk/src/template.ts). You do not need to list it in assets yourself. This is a good place for shared rules such as brand colours or utility classes. Component-specific styles can still live next to their Handlebars templates for clarity.

  • generic-journal keeps styles.scss lightweight (title metadata and the Reader header). It also lists the file as asset-styles in assets, which the loader would do anyway.
  • generic-monograph has no styles.scss and no customStyles; it relies on component settings alone. Document which approach you follow so other teams know whether to look for SCSS files or inline CSS.

Translations and metadata

  • Translations live in the configuration itself: components such as Environment, TableOfContents, and Listings take a translations block keyed by locale (for example de-DE). They override the built-in labels for that language. The loader does not read a separate translations folder.
  • metaData.schema.yml beside the configuration is a JSON Schema (via YAML) that defines custom metadata fields collected from authors before exporting. See Metadata extensions.

Both are optional but help teams keep template behaviour predictable across languages and publication series.

Adding a new Handlebars partial

  1. Create the template file under assets/, for example assets/cover-banner.hbs.
  2. Register it in the assets array with a unique id and inline: true if the file is small.
  3. Reference the asset from a component (HeadersAndFooters, MonographTitle, or a custom component) using fileId.
  4. Test all runners that consume the asset. Monographs often need separate partials per runner because PrinceXML and HTML outputs support different helpers.

Leave a short comment in configuration.sfo.yml or the template readme explaining how the partial is used—especially when multiple templates share the same id.