Plugins

Plugins extend ReLaXed with new features, providing Pug commands or Javascript or styling frameworks to your documents, or post-processing filters. This page describes how to use and how to write plugins.

Using plugins

This section explains how to activate a plugin. It does not cover the plugins which are activated by default in ReLaXed, since these can be considered "features" of relaxed.

Plugin activation and options

To activate plugins, create a config.yml in the same folder as your master document, with the following content:

plugins:
  - some-plugin-name
  - some-other-plugin

Some plugin may accept optional parameters, at which case you must add : after the plugin name, and then provide parameter values:

plugins:
  - some-plugin-name:
      parameter-one: 90
      parameter-two: Jean-Paul

For instance, here is how you activate the svg plugin, and specify that when optimizing pictures it should use a compression quality of 90:

plugins:
  - svg:
      jpeg-quality: 90

Note that when running in an interactive session, the plugins are reloaded automatically when the config.yml is updated.

Built-in plugins

ReLaXed has a few plugins "out of the box", such as mathjax for mathematical equations (see this section on how to use it). Note that some of these plugins may not be built-in in the future.

Installed plugins

External ReLaXed plugins are released on NPM under names such as relaxed-pluginName, for instance relaxed-svg. They can be installed via

npm install -g relaxed-pluginName

This provides the pluginName plugin which you can use in your config.yml file:

plugins:
  - pluginName

Note that plugins do not have to be installed via an online NPM repository, you can also have a plugin on your computer, installed globally using npm link (this isn't tested on every platform though, please open an issue if this doesn't work for you).

Local plugins

It is also possible to define a custom plugin as a standalone file for use in just one or two projects. Just have a file with a .plugin.js extension in the same directory as your master document. e.g. say-my-name.plugin.js and activate it in config.yml:

plugins:
  - say-my-name:
      name: Heisenberg

For illustration sake, assume that the say-my-name.plugin.js contains the following miminal plugin definition, which adds the variable name to the Pug environment.

exports.constructor = async function (pluginDefinition) {
  return {
    pugHeaders: [`- var name = "${pluginDefinition.name}"`]
  }
}

Then your master Pug document can use this variable

p Say my name ! #{name} // will print "Heisenberg"

the next section explains every possible actions offered by plugins.

Writing Plugins

Generalities

A ReLaXed Plugin is a Javascript module exporting a (possibly async) function constructor(parameters) => hooks, where the "hooks" are lists of routines that will be applied at various times of the document creation.

So the master file of your plugin will look something like this:

exports.constructor = async function (parameters) {
  var hooks = {
    watchers: [...],
    pugHeaders: [...],
    pugFilters: [...],
    htmlHead: [...],
    htmlModifiers: [...],
    pageModifiers: [...],
    postPDF: [...]
  }
  return hooks
}

See section Hooks below for a detailed description of the different kinds of hooks.

Packaging

As explained in the Using plugins section, a plugin can be either used by , or published online with NPM. To release the plugin on NPM, the package name must be prefixed by relaxed-, e.g. relaxed-pluginName.

Examples of plugins

If you need inspiration, have a look at:

• The ReLaXed built-in plugins, which are simple plugins like any other, except that they come packaged with ReLaXed.
• The relaxed-svg plugin.

This section describes in detail all the possible hooks.

Hooks

watchers

pugHeaders

pugFilters

htmlHead

htmlModifiers

pageModifiers

postPDF

Summary of all hooks during PDF creation: