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: front-headers-and-footers
      type: hbs
      path: ./assets/front-headers-and-footers.hbs
      inline: true
  • id references the file from component blocks (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 share one headers/footers partial across all PDF-focused runners. Monographs register multiple partials—cover, front matter, HTML—to accommodate different page counters, translations, and branding. Make sure the component blocks and assets stay in sync.

Any asset marked as static: true is always copied to export bundles, even if the file is not referenced elsewhere.

Stylesheets

A template-wide stylesheet named styles.scss is automatically picked up. During loading the file is added as the first style in the export pipeline (stylePaths in libs/tdk/src/template.ts). 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 and references it through the asset-styles entry so PDF exports bundle the tweaks even without variant support.
  • generic-monograph relies on Page.spec.customStyles blocks instead. Document which approach you follow so other teams know whether to look for SCSS files or inline CSS.

Translations and metadata

You can provide additional folders alongside assets:

  • translations/<locale>.yaml — used by the loader to merge in locale-specific labels when a document switches languages.
  • metaData.schema.yml — a JSON Schema (via YAML) that defines custom metadata fields collected from authors before exporting.

Both files 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.