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
, andasset
are common values.path
is relative to the template directory. Use./
to stay within the template folder ortpl/...
when assets should be mounted for downstream use.inline: true
embeds the file content directly into the configuration. The loader inlibs/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
anddimensions
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
keepsstyles.scss
lightweight and references it through theasset-styles
entry so PDF exports bundle the tweaks even without variant support.generic-monograph
relies onPage.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
- Create the template file under
assets/
, for exampleassets/cover-banner.hbs
. - Register it in the
assets
array with a uniqueid
andinline: true
if 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
.