Skip to content

Components and layout

Components are the building blocks of every export. They are implemented in libs/export/src/html/components and wired together through configuration.sfo.yml. Each component focuses on one area—pages, headers and footers, typography, tables of contents, figure handling, and so on. The default templates show two typical stacks:

  • Journal articles (generic-journal) use Page, HtmlPage, EpubPage, HeadersAndFooters, JournalTitle, TableOfContents, Footnote, Typography, GoogleFont, Environment, ParagraphNumbering, the metadata components ArticleMeta, JournalMeta, and PermissionsMeta, Reader with three Static panels, Index, and Ojs. They balance PDF and web outputs with minimal branching. generic-journal-toc is a separate template with nearly the same stack, without ParagraphNumbering, Index, and Ojs.
  • Monographs (generic-monograph) add long-form helpers such as MonographTitle, multiple HeadersAndFooters blocks scoped by region, Content seeds for cover pages, ContentHole, Listings to build figure/table registers, PageOffset, BookMeta, Settings, and one Variant.

How components are loaded

When an export runs, the loader (libs/tdk/src/template.ts) reads each component block in order and initialises the matching TypeScript class. The component receives the values from the block’s spec section and renders styles or markup back into the document.

Because components are executed sequentially, structure the configuration so the flow matches the final publication: cover page components first, then front matter, body, and appendices.

Common components

Below are some frequently used entries you will encounter in the default templates. Use the Example column to jump between journal and monograph snippets when you document your own components.

Component (kind) Purpose Example
Page Controls paper size, margins, running heads, and page-break rules for PDF/Paged.js. Journal Page exposes single-sided A4 defaults; monograph Page configures two-page spreads and double-sided handling.
HtmlPage / EpubPage Define typography and spacing for browser and EPUB exports. Journals keep matching font stacks; monographs add hyphenation settings and deeper TOC depth in EpubPage. See Smart line wrapping.
HeadersAndFooters Inject headers/footers via Handlebars templates and control folios. Journals reuse a single asset across runners; monographs register separate blocks per layout region (front, body, back).
MonographTitle Builds structured title pages with branded typography. Only present in generic-monograph; include when books need a formal cover sequence.
JournalTitle Renders the article title, subtitle, authors, and affiliations on the first page. Both journal templates place it on the cover. See Affiliations in JournalTitle.
Content Seeds boilerplate nodes (cover pages, acknowledgements) for new documents. Monograph template pre-populates German cover sheets with placeholders.
ContentHole Marks where the document's own parts go among the components of a region. The monograph puts one on the front matter so the table of contents follows the front-matter chapters.
Typography Sets base headings, numbering, and front-matter styling. The journal turns heading numbering off (defaultNumberingStyle: none); the monograph numbers headings with a dot suffix.
TableOfContents Generates navigational scaffolding; can be limited to specific runners. generic-journal puts one on the cover, PDF only, depth 4. The separate generic-journal-toc template adds an "Agenda" with depth 2. The monograph raises the depth to 5.
Listings Builds figure/table listings with optional localisation. Only in the monograph template to reflect long-form publishing needs.
Index Builds an index from the index entries marked in the text (renderMode, columnCount). generic-journal places it at the back (page: back).
ParagraphNumbering Numbers the paragraphs of the document. generic-journal enables it for the body (page: body, spec: {}).
Footnote Footnote and endnote layout. See Footnotes.
GoogleFont Downloads and bundles fonts from Google Fonts. See Fonts.
ArticleMeta Article metadata: article type, version, issue, pages, identifiers, history dates. Used by JATS XML, OJS XML, and the templates' Handlebars snippets. The journal templates preset articleType.
JournalMeta Journal metadata: name, short name, ISSN, publisher. The journal templates preset name.
PermissionsMeta Copyright and licence. The journal templates preset copyrightYear.
BookMeta Book metadata for BITS XML and cover pages: identifiers, ISBNs, titles, publisher. The monograph adds it with spec: {}, so authors fill it in.
Ojs Destination settings for the OJS XML export. Only in generic-journal. See OJS export.
Reader Look and panels of the Reader: theme.color, theme.mode, and display (table of contents, figure panel). The monograph hides both panels by default.
Static Renders a fixed piece of HTML (dom, with Handlebars helpers) and optional styles. The journal templates use it with runners: [reader] to add metadata and copyright panels to the Reader (metadata.reader.position: header or dca).
Settings Editor shortcuts: quickSettings (paths shown in the quick settings panel) and quickEdits (command-palette entries). The monograph exposes the figure labels as quick settings.
ArticleMetaSidebar A first-page metadata aside for PDF and HTML: masthead, history, keywords, corresponding author, citation, licence. No shipped template uses it. See Article metadata sidebar.
Variant Applies JSON patches to tweak defaults or apply presets. The journal templates ship none; the monograph offers one, A5, in the page-sizes group.
Environment Boxes, labels and numbering for environments, image transformation, and math macros. See Math macros below.
PageOffset Starts the page counter at a given number, for example for an article inside an issue. The monograph places one on the front matter (page: front, PrinceXML only). See Page offset below.

To explore all available components, browse the registry in libs/export/src/html/components/index.ts. Each component folder usually contains a *.schema.ts file that documents the supported options. Reference those files when writing documentation so you can point editors to the authoritative schema.

Making components configurable

The UI in the editor only exposes the fields declared in a component’s JSON schema. If you want authors to edit a value:

  1. Find the configuration path in the schema file (for example properties/page/properties/margins/properties/inner).
  2. Add the relevant field to the component’s spec block in configuration.sfo.yml.
  3. Optionally list the path in a separate kind: Settings block under spec.quickSettings so it appears in the “Quick settings” panel (see libs/export/src/html/components/settings/settings.schema.ts).
kind: Settings
ui:
  showTo: []
spec:
  quickSettings:
    components:
      - component:
          name: Environment
          options:
            - path: environments.image.label
              description: Label (e.g. Bild, Figure, Abbildung)

Keeping configuration options tightly scoped to components helps new maintainers understand where a particular setting comes from and minimises the risk of breaking unrelated parts of the export.

Documenting component interplay

  • Link back to the configuration. When you introduce a component, note which assets entry or metadata name the template expects. Example: the monograph HeadersAndFooters blocks rely on metadata.name (for-front, for-body, for-back) so variants can patch them individually.
  • Call out runner differences. Journals often share component specs across PrinceXML and HTML. Monographs split responsibilities—for example, a dedicated HeadersAndFooters with runners: [html] to avoid PrinceXML-only features.
  • Surface localisation hooks. Components like TableOfContents and Listings accept translations blocks. Highlight where monographs set German labels so teams know how to add additional locales.

Math macros

A template can define short names for equations in its Environment block. An author writes x \in \R, and every export (PDF, HTML, EPUB, JATS, BITS) receives the expanded x \in \mathbb{R}.

kind: Environment
spec:
  mathMacros:
    R: { args: 0, body: '\mathbb{R}' }
    vv: { args: 1, body: '\mathbf{#1}' }
    pair: { args: 2, body: '\left( #1, #2 \right)' }
  • Shape. Each entry is name: { args: <0-9>, body: '<TeX>' }. The name is letters only, without a backslash, case-sensitive, and at most 64 letters. #1 to #9 in the body are the arguments; there are no optional arguments. A body has at most 4096 characters and no line breaks.
  • Quote bodies with single quotes. In a double-quoted YAML string the backslash starts an escape: "\theta" becomes a tab plus heta, "\frac" a form feed plus rac. body: '\mathbb{R}' is right; body: "\mathbb{R}" is wrong.
  • Refused names. Names TeX or MathJax already define (\frac, and also \abs, \norm, \set) are refused; pick another, for example nrm.
  • Invalid entries are skipped, not fatal. The export logs a MATH_MACRO_IGNORED warning per skipped entry, with the name and the reason, and uses the rest. Expansion never fails an export: an equation that grows too large is left as typed.
  • Documents can override. A document adds or changes single macros in its metadata under Environment.mathMacros.<name>; it cannot remove a template macro. Templates without an Environment block still pick up the document's own macros. An equation that defines a name itself (\newcommand, \def) uses its own definition for the rest of that equation.
  • Headings and titles. Formulas in headings, the title and the subtitle are expanded before bookmarks, running heads, the table of contents, the EPUB navigation and OJS titles are made from them, so \R^n reads ℝ^n there.
  • Limit. Templates rendered by the legacy renderer do not support document macros.

Treat macro names as a public contract: authors type them into their equations. Renaming or removing one breaks every equation that uses it, so add a new name instead.

Page offset

PageOffset starts the page counter at a given number, for example when an article is page 45 to 60 of an issue.

kind: PageOffset
spec:
  offsetKey: PageOffset.offset
  firstPageSide: follow-number
  • offset: the number to start at. Prefer setting it in the document's metadata under PageOffset.offset and pointing offsetKey there. Avoid the legacy top-level offset key: it comes with a schema default of 1, so every article would start at page 1 when no offset is set.
  • firstPageSide (PDF only, default recto): recto always starts on a right-hand page. follow-number starts on a left-hand page when the offset is even and on a right-hand page when it is odd, as in a printed issue where even pages are on the left. A first section forced onto a right-hand page (page break: right) still wins.
  • With page: front, body, … the placement starts on a new page, and a blank page may be added before it.

Table themes

Tables pick a named theme in Environment under environments.table.theme. The built-in themes are plain, plain-outside, apa (the default), table1, table2, and table3; the journal templates use table1, the monograph table2. A template can add its own themes under environments.table.themes. A theme with the name of a built-in overrides it and keeps every field it does not set.

kind: Environment
spec:
  environments:
    table:
      theme: house
      themes:
        - name: house
          borderWidth: 0.5pt
          borderColor: '#999999'
          header:
            backgroundColor: '#eeeeee'
            fontWeight: bold
          alternateRow:
            backgroundColor: '#f7f7f7'

Cell and header text alignment are not part of a theme; authors set them per cell.

Table column widths

environments.table.columnWidths in Environment decides how column widths are applied:

  • fit (default): each column grows to fit its content.
  • honor: columns keep the widths set in the editor, and the table is clamped to the page width. Tables with the same column widths then render at the same width; content that does not fit wraps.

It applies to HTML/PDF, JATS/BITS, and Markdown output.

Smart line wrapping in HTML

HtmlPage.page.font.textWrap turns on the browser's text-wrap for the HTML export:

  • wrap (default): browser default, output unchanged.
  • pretty: avoids very short last lines in body text and balances short blocks such as headings and captions.
  • balance: balances every block; long paragraphs are unaffected.

PDF output and browsers without support ignore it. With justified text, pretty can widen word spacing in Safari, so check the result.

Affiliations in JournalTitle

JournalTitle has options for where the author affiliations go and how they are numbered:

  • affiliations.floatPlacement (PDF only): none (default) lists them under the authors, bottom puts them in a float at the foot of the page, and footnote-area puts them in the footnote area, sharing its separator and counter. footnote-area needs a Footnote component in footnote mode.
  • affiliations.numberedBy: affiliation (default) numbers the affiliations, and each author points at one. author numbers the authors, and each affiliation line lists the authors at it. With footnote-area, the numbers continue into the real footnotes.
  • showCorrespondingInline (default true): set it to false to hide the corresponding-author line under the authors, for example when it is shown elsewhere.
  • singleAffiliationIndex: whether a single affiliation still gets its superscript number.

The defaults leave existing templates unchanged.

OJS export

The Ojs component configures the OJS Native XML export (label ojsxml). It has no published schema yet, so the block has no $schema line.

kind: Ojs
spec:
  version: '3.5'
  versionAlternatives:
    - '3.6'
  sectionRef: ART
  userGroupRef: Author
  • version is pre-selected; each release in versionAlternatives gets its own entry in the export panel. Without an Ojs block, every supported release is offered.
  • sectionRef is the abbreviation of the destination journal's section. A section set in the document's article metadata wins over it.
  • userGroupRef is the name of the journal's author user group (for example Author, or Autor/in in a German install). OJS 3.4 and 3.5 need it; 3.6 does not use it.

OJS matches both values against the destination journal. A wrong value still gives valid XML but fails at the journal's import, so the export refuses to guess them. A journal with its own section abbreviations or a non-English user group must set them in its template.

Article metadata sidebar

ArticleMetaSidebar places a metadata aside on the first page of PDF and HTML exports: journal masthead, subject or article type, history dates, keywords, corresponding author, a recommended citation, and the licence. Each block can be switched off. It has no effect on JATS, BITS, or OJS output.

  • mode: band (default) reserves a column along the side of the first page and keeps the body in the other column.
  • mode: wrap floats the aside so the body text wraps beside it (PrinceXML).

The component exists, but no shipped template uses it. Add a kind: ArticleMetaSidebar block to try it; when you do, consider showCorrespondingInline: false in JournalTitle so the corresponding author is not shown twice.