Skip to the document

How themes work

A theme controls how a vault's documents look, both on screen and in a printed PDF, without touching the documents themselves. Swap the theme and the same document gets a different typeface, colour palette and cover page.

What a theme is made of

A .theme file is a zip built from a theme.json manifest:

{
  "id": "acme",
  "name": "Acme",
  "version": "1.0.0",
  "page": "A4",
  "styles": { "tokens": "tokens.css", "screen": "screen.css", "print": "print.css" },
  "templates": { "cover": "templates/cover.html", "header": "templates/header.html", "footer": "templates/footer.html" }
}

Only tokens.css is required; screen, print and the three templates are all optional, so a minimal theme can be just a set of colours and fonts.

What a theme controls

  • Tokens (tokens.css) set the --fx-* CSS custom properties, fonts, colours, radius, spacing, plus any @font-face rules. These are shared everywhere: the app's own screen view, the printed page, and inside every block's sandbox, so a block written against the token names picks up the vault's theme automatically without any configuration.
  • Screen CSS (screen.css) is extra styling applied only in the app's infinite layout.
  • Print CSS (print.css) is extra styling applied only to the paginated layout, used by the app's Paginated view and PDF export. Because this goes through Paged.js, it can use @page margin boxes, named pages, and running elements for repeating headers and footers. Writing a theme covers this in detail.
  • Templates (cover, header, footer) are small HTML files with {{placeholder}} syntax, filled in from the vault's values, the document's frontmatter over them, and the title. A document with cover: true in its frontmatter gets the theme's cover page if it defines one; a theme with no cover template has no cover page.

Choosing a theme

A theme can be selected in two places:

  • Per vault, in vault.json's theme field. This is what a document uses unless it says otherwise.
  • Per document, in that document's own frontmatter theme: key, overriding the vault's default just for that one document.

If the named theme isn't installed anywhere Plicine looks (the vault's own .vault/themes/ folder, the library, or the community folder), the document falls back to the built-in default theme and a warning explains why. The built-in theme is Plicine's own: a cream page, ink text and a green accent, set in Newsreader and Instrument Sans, with a cover page and a footer. It's also the only theme whose PDFs end with the "Made with Plicine · plicine.com" line, which credit: false turns off; a theme of your own carries no such line unless you ask for it in theme.json. Its id is still default, so a vault that names default keeps working.

Switching themes in the app

The theme selector in the app's topbar lets you preview any installed theme against the document you're currently reading, without changing anything on disk. It's a session-only override: reload the page, export from the CLI, or open the vault on another machine, and you're back to whatever the document and vault actually specify. This is a good way to check how a document looks in a different theme before deciding to commit to it in frontmatter.

See Writing a theme for a hands-on tutorial building a theme from the reference one, and The .theme package for the full manifest and template syntax.