Custom string replacement

You often want to change strings in built files. For example:

• To replace specific strings with others.
• To implement WordPress-like short codes, e.g. −−COPYRIGHT−− becomes ©2025 where the year is generated by code.
• To add functionality that isn’t possible in other ways, e.g. define <aside>, <section>, or <article> blocks in markdown.

Publican provides two output manipulation options:

1. simple string replacement
2. event function hooks

Simple string replacement #

You can search and replace strings in the final built files using the publican.config.replace Map in your publican.config.js configuration file. (Note that pass-through files are ignored.)

publican.config.replace.set(<search>, <replace>);

where:

• <search> is a search string or regular expression
• <replace> is the replacement string

You can set as many search and replace options as you like.

Server root example #

The following code replaces all references to −−ROOT−− with the server’s root directory (normally /):

publican.config.replace.set(
  '−−ROOT−−',
  publican.config.root
);

This allows you to create links in markdown that automatically change when a different root directory is used, e.g.

* [Home](−−ROOT−−)
* [About us](−−ROOT−−about/)
* [Contact us](−−ROOT−−about/contact/)

Date formatting example #

The following code uses a regular expression to convert YYYY-MM-DD dates to DD-MM-YYYY format:

publican.config.replace.set(
  /(\d{4})-(\d{2})-(\d{2})/g,
  '$3-$2-$1'
);

Copyright year example #

The following code replaces −−COPYRIGHT−− with a copyright symbol and the current year (©2025):

publican.config.replace.set(
  '−−COPYRIGHT−−',
  `©${ (new Date()).getUTCFullYear() }`
);

Table style examples #

Tables defined in markdown apply an inline style attribute when cells are aligned right or center. You can replace this with a class using the following code:

publican.config.replace.set( ' style="text−align:right"', ' class="right"' );
publican.config.replace.set( ' style="text−align:center"', ' class="center"' );

Event function hooks #

Functions can be defined in your configuration file that are called when specific events occur during the build. Functions typically inspect, add, alter, or remove data.

The two most useful hooks for string replacement are processContent and processPostRender. For more information, refer to the event functions reference.

processContent #

This function hook is called after a content file (or virtual file) is loaded and parsed.

Function parameters:

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

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

// example processContent hook
// prepend the word "POST: " to every title
publican.config.processContent.add(
  (data, filename) => {
    data.title = 'POST: ' + data.title;
  }
);

processPostRender #

This function hook called after each page has 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 a updated output string:

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