Publican public methods

The Publican object provides the following public methods that can be used in the publican.config.js configuration files.

.addContent() #

Content can also be passed to Publican as a string in the configuration file. This may be useful if you are retrieving data from a Content Management System API rather than using the file system.

To add virtual content, call:

publican.addContent( <filename>, <content> [, <dataObject> ] );

prior to running the build process (await publican.build();). The arguments:

1. filename follows the directory structure rules and determines the content type (HTML, markdown, etc.)

2. content is the main content strong with front matter if necessary.

3. dataObject is an optional initialization object containing values that you would normally use in front matter (properties defined in front matter take precedence).

The following example creates a page with a filename and content string:

publican.config.js

publican.addContent(
  'article/virtual-post.md', `
---
title: Virtual post
---
This is a virtual post!
`);

The following example is similar but also passes a data object:

publican.config.js

publican.addContent(
  'article/virtual-post.md', `
---
title: Virtual post
---
This is a virtual post!
`,
  {
    title: 'My title',
    description: 'My description',
    date: new Date(), // now
    tags: ['automatic', 'content'],
    groups: 'virtual, content'
  }
);

The title is Virtual post rather than My title because content front matter takes priority.

You can pass:

• date as a Date() object or string such as "2025-12-25".

• menu and index values as strings or Boolean false.

• tags and groups as arrays or comma-separated strings.

• a dataObject.content property when the content parameter is falsy, e.g.

  publican.addContent(
    'article/virtual-post.md',
    null,
    {
      title: 'My post',
      content: 'Some content.'
    }
  );
  

.addTemplate() #

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>

.clean() #

An asynchronous function that removes all files from the build directory. The .clean() method should be called prior to running .build() and ensures old files will not be present.

publican.config.js

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

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

// clear build directory
await publican.clean();

// build site
await publican.build();

The .clean() method works cross-platform so you do not require Node.js directory handling modules or alternative npm scripts.

.build() #

The main asynchronous function to start a build. It should be called after all options are set at the end of the configuration file.

publican.config.js excerpt

// build site
await publican.build();

When watch mode is enabled, Publican will monitor content and template files and automatically rebuild again.