Custom event hook functions

Functions can be defined in your configuration or plugin files that are called when specific events occur at build time. The functions can inspect, add, alter, or remove data.

Synchronous functions only #

Only synchronous functions can be used in hooks. Do not add functions that are async or return a Promise since they are not likely to resolve before the build completes.

If necessary, you can call asynchronous code to fetch data before calling await publican.build() and use that in hook functions.

Processing order #

Hooks are implemented as a JavaScript Set so any number of functions can be associated with a single event using .add(). Similarly, .delete() and .clear() can be used to remove one or all functions respectively.

Functions are normally processed in the order they are defined, but this cannot be guaranteed. Ensure your code does not depend on a specific execution order.

processContent #

A function hook called after a content file (or virtual file) is loaded, parsed, and has markdown converted to HTML.

Function parameters:

1. data (object): the content file’s parsed post properties.
2. filename (string): the filename relative to the content directory.

The function can examine and change any data property because it’s passed by reference. Return values are ignored.

// example processContent hook
// output filename and append the word "POST: " to every title
publican.config.processContent.add(
  (data, filename) => {
    console.log(`processing ${ filename }`);
    data.title = 'POST: ' + data.title;
  }
);

processTemplate #

A function hook called after a template file (or virtual file) is loaded.

Function parameters:

1. template (string): the template content.
2. filename (string): the filename relative to the template directory

The function can examine, change, and return the template string to update it (in memory).

// example processTemplate hook
// prepends the template filename as an HTML comment
publican.config.processTemplate.add(
  (template, filename) => `\n<!-- ${ filename } -->\n${ template }`
);

processRenderStart #

A function hook called once before page rendering starts.

Function parameters:

1. tacs (object): the global tacs object.

The function can examine and modify any tacs property because it’s passed by reference. Return values are ignored.

// example processRenderStart hook
// creates a new global tacs.tagScore Map
// which stores the number of posts for each tag reference
publican.config.processRenderStart.add(
  tacs => {
    tacs.tagScore = new Map();
    tacs.tagList.forEach(t => tacs.tagScore.set(t.ref, t.count));
  }
);

processPreRender #

A function hook called for each page just before it’s rendered.

Function parameters:

1. data (object): the post data object.
2. tacs (object): the global tacs object.

The function can examine and modify either object because they are passed by reference. Return values are ignored.

// example processPreRender hook
// set a new data.renderTime property on HTML content
publican.config.processPreRender.add(
  data => {
    if (data.isHTML) data.renderTime = new Date();
  }
);

processPostRender #

A function hook called for each page when it’s been fully rendered prior to minification and saving to the file system.

Function parameters:

1. output (string): the rendered content.
2. data (object): the post data object.
3. tacs (object): the global tacs object.

The function can examine, change, and return the output string to update it.

// example processPreRender hook
// add meta tags to HTML content
publican.config.processPostRender.add(
  (output, data) => {
    if (data.isHTML) {
      output = output.replace(
        '</head>',
        '<meta name="generator" content="Publican" />\n' +
        `<meta name="generated" content="${ data.renderTime }" />\n` +
        '</head>'
      );
    }
    return output;
  }
);