Site templates

site.template in your curvenote.yml sets the theme that curvenote start, curvenote build and curvenote deploy use to render your site. The default is the Curvenote theme, and curvenote init writes it into every new project:

site:
  template: curvenote@latest

The Curvenote theme¶

curvenote is a short name for the Curvenote theme, whose source lives at github.com/curvenote-themes/curvenote. It is the only theme name the CLI accepts.

• curvenote and curvenote@latest use the latest branch of the theme, and pick up new releases when you download the theme again (see Caching and pinning).

• curvenote@<ref> uses a tag, branch or commit of the theme, for example curvenote@v2.3.1. Use a tag or commit to pin your site to one version.

When you run curvenote start, the CLI downloads the theme on first use, builds your pages and prints a link to the running site:

The link ends in ?params=, a base64url-encoded JSON object that tells the theme which CLI version started it, for example {"version":"0.17.6"}.

What site.template accepts¶

Templates you build yourself work the same way: point site.template at a local folder while you develop the template, then at its GitHub repository or a release zip when you share it. To change how individual parts of a page render without a whole template, use site render plugins instead.

Values the CLI ignores¶

Any other value falls back to the default template, and the CLI prints a warning that names the value it ignored. That includes:

• other theme names, such as book-theme or Curvenote

• hosts other than github.com, and http:// URLs

• files that are not zip archives

• GitHub /tree/ and /blob/ links

• a bare owner/repo

Projects that set site.template: book-theme or another theme name now render with the Curvenote theme. To keep using a different theme, point site.template at its GitHub repository or a local copy of it.

The --template option¶

curvenote start --template <value> overrides site.template for one run and follows the same rules. If the CLI does not accept the value, it prints a warning and uses site.template from your curvenote.yml instead.

curvenote start --template curvenote@v2.3.1

Caching and pinning¶

Downloaded templates are kept in _build/templates/site/, one folder per URL, and are not downloaded again. To pick up a newer version of a branch such as latest, delete them and start again:

curvenote clean --templates
curvenote start

To stay on one version, use a tag or commit instead of a branch. If a branch and a tag share a name, GitHub chooses one; use a /releases/tag/<tag> link or a .../archive/refs/tags/<tag>.zip URL to ask for the tag.

If your project has a folder named curvenote that contains a template.yml, site.template: curvenote uses that folder rather than the Curvenote theme. Write ./curvenote to make that explicit.

How commands write site.template¶

• curvenote init, curvenote clone and curvenote pull write curvenote@latest into site.template.

• curvenote init --github <url> replaces a missing or ignored site.template in the cloned curvenote.yml with curvenote@latest, and warns. Values the CLI accepts are left alone.

• Commands that rewrite curvenote.yml keep site.template exactly as you wrote it, even when the CLI resolves it to a zip URL to download.