Templates and workspace files

A template is a document layout that you keep in your workspace and fill with data each time you render. You edit its draft in Studio, preview it with sample data, and publish it as a numbered version that your applications render. To build one step by step, start with build a template.

Kinds of templates

Create a template in Studio’s explorer with New entity → Template (in the + menu or a folder’s … menu). Start with decides its kind:

Start with	Source file	Renders	Learn more
Blank template, Invoice example	template.html	PDF	Handlebars templates
PDF file, drafted with AI	template.html	PDF	From a PDF
HTML file (upload one, up to 1 MB)	template.html	PDF	Handlebars templates
Excel workbook (XLSX)	template.html and the uploaded .xlsx	XLSX	Spreadsheet templates
Spreadsheet (XLSX and PDF tables)	sheets.json	XLSX or PDF	Spreadsheet templates
Not in Studio; create it with the API	composition.json	PDF	Component templates

A template has exactly one source, and the source decides what it can render. Invoice example and Spreadsheet also create a sample.json data file beside the template (in a new folder named after the template when you create it at the workspace root).

From a PDF

PDF file, drafted with AI turns a PDF you already send, such as an invoice from your current system, into a template that looks like it. Upload a PDF of up to 10 MB and 10 pages, without a password.

1. Claude, Anthropic’s AI, reads the PDF and writes a draft: template.html with the layout and fixed text, and a sample.json with the values that change from one document to the next.
2. Typefold renders the draft, compares it with your PDF page by page and sends the differences back, a few times, until the draft matches closely.
3. The best draft opens as a template in a new folder named after it, with sample.json and the PDF’s raster images beside it. Edit it like any other template, then publish it.

It usually takes two to five minutes; you can close the window meanwhile. Fonts are replaced with Arial, and vector logos with a box of the same size, so upload your fonts and logo afterwards.

The PDF and the images of each draft go to Anthropic; Typefold doesn’t keep the PDF. On the hosted service, see the privacy policy. Each plan allows a number of templates from a PDF a month, shown under Manage → Render limits.

The files of a template

A template’s tab in Studio shows its source on top and its other files in tabs below it. An Export folder zip holds each of them as a file.

Studio tab	File	What it holds
Source (top)	template.html, sheets.json or composition.json	The body of the document.
helpers.js	helpers.js	Your JavaScript helpers. HTML templates only; see Handlebars templates.
Page header	header.html	Handlebars drawn in the top margin of every page. Not for spreadsheet templates.
Page footer	footer.html	Handlebars drawn in the bottom margin of every page. Not for spreadsheet templates.
page.json	page.json	Paper, margins, language and PDF options; see page.json.
fields.json	fields.json	The content fields a content editor may change.
content.json	content.json	The values of those fields.

• The Page header, Page footer, fields.json and content.json tabs show once they have content. Add them with the + (Add a file) at the end of the tab bar. Page numbers and the other header and footer markup are in build a template.
• HTML templates also have a Bindings tab, which lists every placeholder in the HTML and the value the sample data gives it.
• Everything else a template uses is a workspace file that it names by path. The preview toolbar sets three of them:
  • Data: the sample data file previews render with. Pick one in or under the template’s folder.
  • Template files (the folder icon): the stylesheets the template applies and the beforeRender scripts it runs, in the order you tick them. Up to 20 stylesheets and 10 scripts.
  • Workbook, for an Excel workbook template: the .xlsx file it fills.

page.json

page.json sets the template’s paper and the PDF’s defaults. Edit it in the page.json tab, or use PDF properties in the preview toolbar, which edits the same settings in a form.

page.json

{
  "pageSize": { "widthMm": 210, "heightMm": 297 },
  "orientation": "portrait",
  "margins": { "topMm": 15, "rightMm": 15, "bottomMm": 20, "leftMm": 15 },
  "locale": "en-GB",
  "metadata": { "title": "Invoice {{invoice.number}}" }
}

Setting	Default	What it does
pageSize		Required. widthMm and heightMm, each above 0 and up to 2,000.
orientation	portrait	portrait or landscape.
margins		Required. topMm, rightMm, bottomMm and leftMm, each 0 to 500.
locale	en-US	The template’s language: picks the translation file and sets the PDF’s language. See translations.
pageRanges		Pages to keep, such as 1-5, 8, 11-. Page numbers still count the whole document.
metadata		PDF properties such as title, author and subject. Values may use {{path}} placeholders. See PDF standards and security.
encryption		Passwords and permissions. Passwords may use {{path}} placeholders. See PDF standards and security.
signature		Sign with a workspace signing certificate. See PDF standards and security.
operations		Up to 10 steps that add another template’s pages before or after this one, or draw them onto it. See combine templates.
pdfa		The PDF/A level to write and check. See PDF standards and security.
pdfua		The PDF/UA part to write and check. See PDF standards and security.
opaqueFills		true draws see-through content (CSS opacity, translucent colours) at full strength. Shown in PDF properties as Ignore opacity.
preferCssPageSize		true prints on the paper a CSS @page { size } rule names instead of pageSize. See supported CSS.

A Reports API request or a preview can override most of these for one render.

Workspace files and folders

Templates and workspace files sit together in one tree of folders in Studio’s explorer. One file can be used by many templates, so a shared stylesheet or logo is edited in one place. Create a file with New entity and the kind below, or drop files into Import…:

New entity	Default name	Holds
Sample data	data.json	Data for previews. Must be valid JSON. Production renders use the data you send instead.
Localization	en.json	Translation labels, named for a language tag such as de-CH.json. See translations.
Partial	partial.html	A reusable piece of Handlebars, used with {{> name}} or {{component "path"}}.
Script	shared-helpers.js	A beforeRender script. See Handlebars templates.
Stylesheet	shared-styles.css	CSS, ticked under Template files or included with {#asset}.
Asset	the uploaded name	An uploaded font, image, .xlsx workbook or PDF file.

• Names are unique within a folder, ignoring case.
• A file’s header in Studio shows Used by with the templates that use it, and their live version. Saving a shared file saves it straight to the workspace; it has no draft of its own.
• In the explorer, Clone, Cut, Copy and Paste copy or move templates, files and folders. A copy of a template is a new template that has not been published.
• Size and count limits are in limits.

How paths resolve

A template names a file by its path, such as styles/invoice.css. Keep a template’s files in its folder or in subfolders of it.

Reference	Example	Where it looks
Partial	{{> lines}}	The referencing file’s folder, then its partials subfolder. Also tries .hbs, .html and .handlebars.
Component	{{component "components/row.html"}}	The referencing file’s folder, then the template’s folder.
Include	{#asset styles/theme.css @encoding=utf8}	The referencing file’s folder, then the template’s folder. Includes can nest.
Embedded font or image	{#asset fonts/brand.ttf @encoding=dataURI}	As for an include.
HTML src, CSS url()	src="./images/logo.svg"	The referencing file’s folder.
Data, Template files, Workbook	sample.json	The template’s folder.
Translation files	de-CH.json	The template’s folder and its localizations subfolder.

• In a {#asset} or {{component}} path, a leading / starts at the workspace root.
• ../ goes up a folder; above the root it stays at the root.
• Folder and file names match ignoring case.
• Quote paths that contain spaces or parentheses: url("../Client (2)/logo.png"), {#asset "../Client (2)/theme.css" @encoding=utf8}.
• An {#asset} path may end in Handlebars, such as {#asset ./icons/{{icon}}.svg @encoding=dataURI}. Publishing then copies every uploaded file directly in that folder (./icons, not its subfolders) into the version.
• A src or url() value without a / that starts with no . and matches no file is left as it is.

Missing and moved files

Renaming or moving a file, folder or template never rewrites the paths that point to it. Saving does not check paths; previewing and publishing do. A missing file, or a file of the wrong kind (such as a font included with @encoding=utf8), fails with 400 ASSET_INVALID and lists each path with the file that names it. Files that include each other in a loop fail with 400 BAD_REQUEST.

Drafts and history

The draft is what you edit. Save in the editor header (or Ctrl+S, Cmd+S on a Mac) saves it as a new revision. Revision 1 is the template as it was created or imported, and every save adds one. Revisions cannot be changed or deleted.

History compares any two revisions file by file, including which data, stylesheets and scripts the template used. Restore revision loads one into the editor as unsaved edits; click Save to keep it.

If someone else saved the draft since you opened it, your save fails and your edits stay in the editor. Copy your changes, reload the template, and apply them again.

Preview

Update preview renders what is in the editor, unsaved edits included, with the sample data file chosen in Data. Nothing is saved or published.

• Output switches between XLSX and PDF for a spreadsheet template.
• Preview picks one of the template’s translation languages for this preview only. It shows once the template has a translation file.
• The Profiler tab shows how long the render took and any console.log output from helpers and scripts.
• Check accessibility and conformance checks the PDF against PDF/A and PDF/UA. See PDF standards and security.
• Shared files render as last saved. An unsaved sample data file open in another tab is the exception: the preview uses its text as it is.

A PDF preview counts against your render allowances like any render. An XLSX preview does not count, but it is refused while the allowances are used up. See limits. Through the API, a preview can also return the filled HTML before PDF layout; see the API reference.

Publish a version

Publish in the editor header publishes the saved draft as the template’s next version: 1, 2, 3 and so on. Save first; Publish is unavailable while there are unsaved changes, and when the saved draft is already live. The status beside the template’s name shows where it stands:

Status	Meaning
Unsaved changes	The editor holds edits that are not saved.
Saved · not published	The template has never been published.
Saved · changes since v2	The saved draft differs from the live version 2.
Published v2	The saved draft is live as version 2.

Publishing copies into the version every file the template uses at that moment: partials, stylesheets, scripts (including folder and workspace-wide ones), translations, sample data, fonts, images and the workbook. It does not render the template, so preview first.

When changes go live

• Editing the draft or a shared file changes the next preview and the next publish of every template that uses it.
• A version keeps its own copy of every file. What your applications render does not change until you publish again, and deleting or editing a file never breaks a version.
• Versions cannot be changed or deleted.
• A version freezes your template, not Typefold itself. An upgrade of Typefold that fixes layout can change the output of an existing version.

To render the latest version by name, use the Reports API. To render one specific version as a background job, use the Renders API.

Import files and templates

In the explorer, click + → Import…, or Import into folder… in a folder’s … menu, then drop files or a folder:

You drop	Studio
A project folder	Creates a new template, in a folder of its own, from the HTML and its files.
A .zip made by Export folder or Export workspace	Updates the folders, files and templates it holds, and creates the rest. See deploy across environments.
A report archive from another tool	Imports its templates. See migrating.
Other files	Adds them to the folder: .css as a stylesheet, .js as a script, .html as a partial, a language-named .json as a translation, other .json as data, anything else as an asset.

A project folder has exactly one .html file and at most one .js helpers file at the top level, optional .css files, optional data/, localizations/ and partials/ folders, and images (.png, .jpg, .svg) and fonts (.woff2, .ttf, .otf) in named folders such as fonts/. It holds at most 245 files and 10 MB. Imported templates arrive as drafts: preview them, then publish each one.

Delete templates and folders

Choose Delete in a template’s or folder’s … menu in the explorer.

• Deleting a folder deletes everything in it. It is refused while a template or file outside the folder still uses one of its files.
• A single workspace file cannot be deleted on its own, only with its folder.
• There is no undo. New renders of a deleted template fail with 404 NOT_FOUND, including renders by name. Files already rendered are kept.

Manage templates through the API

Everything on this page can also be done through the API, for example from a build script: create templates, save drafts, read revisions, preview, publish, manage folders and files, and import or export a zip. Reading needs the template:read scope, changing template:write, and publishing template:publish; uploading fonts and images also needs asset:manage. See the API reference for every endpoint and field, and the HTTP API for keys and errors.

Next steps

• Build a template in Studio: paper, header and footer, fonts and images.
• Handlebars templates: helpers, scripts and partials.
• Combine templates: covers, terms and letterheads.
• Deploy across environments: copy templates to another workspace or installation.