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
idreferences the file from component blocks, usually asspec.template.fileId: headers-and-footers.typeis a free-form label;logo,hbs, andassetare common values.pathis relative to the template directory. Use./to stay within the template folder ortpl/...when assets should be mounted for downstream use.inline: trueembeds the file content directly into the configuration. The loader inlibs/tdk/src/template.tsreads the file and attaches it to the asset so that exports do not need to access the filesystem later.roleanddimensionsare 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 backHeadersAndFootersblocks, 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-journalkeepsstyles.scsslightweight (title metadata and the Reader header). It also lists the file asasset-stylesinassets, which the loader would do anyway.generic-monographhas nostyles.scssand nocustomStyles; 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, andListingstake atranslationsblock keyed by locale (for examplede-DE). They override the built-in labels for that language. The loader does not read a separate translations folder. metaData.schema.ymlbeside 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
- Create the template file under
assets/, for exampleassets/cover-banner.hbs. - Register it in the
assetsarray with a uniqueidandinline: trueif the file is small. - Reference the asset from a component (
HeadersAndFooters,MonographTitle, or a custom component) usingfileId. - 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.