Publican templates

468 words, 3-minute read

Publican templates define how content is slotted into HTML to create static web pages. Templates typically define page headers, footers, navigation, and content locations.

Example template #

Publican uses the jsTACS templating engine. It parses standard JavaScript template literal ${ expressions } which can access page content data and global site tacs properties.

default.html

<!doctype html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>${ data.title }</title>
  </head>
  <body>

    <header>
      <nav><a href="${ tacs.root }">HOME</a></nav>
    </header>

    <main>
      <h1>${ data.title }</h1>
      ${ data.content }
    </main>

  </body>
</html>

Note:

See the jsTACS page for more information.

Template file location #

Create template files in src/template/ unless you set an alternative directory in publican.config.js, e.g.

publican.config.js

// imports
import { Publican } from 'publican';

// create Publican object
const publican = new Publican();

// alternative template location
publican.config.dir.template = './my-templates/';

// build site
await publican.build();

Default templates #

A template can be selected in the content’s front matter:

---
title: Some content
template: my-template.html
---

When this is not set, Publican uses a default template file named default.html. You can set any template name in publican.config.js, e.g.

publican.config.js excerpt

publican.config.defaultHTMLTemplate = 'main.html';

You can also change the default template for directory index pages:

publican.config.js excerpt

publican.config.dirPages.template = 'dir.html';

and tag index pages:

publican.config.js excerpt

publican.config.tagPages.template = 'tag.html';

Virtual template files #

Templates can be passed to Publican as a string in the configuration file. This may be useful if you want to create custom templates or partials using conditions or other logic.

To add a virtual template, call:

publican.addTemplate( <filename>, <content> );

The filename is relative to the template location. The following example adds a template which shows an HTML <blockquote> section when a quote value is set in front matter.

publican.config.js excerpt

publican.addTemplate(
  '_partials/blockquote.html',
  '${ data.quote ? `<blockquote>${ data.quote }</blockquote>` : "" }'
);

It can be used in any other template with an include() expression:

default.html excerpt

<main>
  ${ include('_partials/blockquote.html') }
  ${ data.content }
</main>