Custom string replacement

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

• To replace specific strings with others.
• To use WordPress-like short codes, e.g. −−COPYRIGHT−− becomes ©2025 where code inserts the current year.
• 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: Publican ignores pass-through files.)

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

where:

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

You can set any number of search and replace options.

Server root example #

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

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

This allows you to create links in markdown that automatically change when using a different root directory, 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 aligning cells 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 #

You can define functions in your configuration file that run 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 runs after loading and parsing a content file (or virtual file).

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 runs after a page has been fully rendered (before 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;
  }
);