Processors

A processor is a function to transform the content of pages just after the page is rendered. Let's see an example of a processor to minify HTML pages:

function minifyHTML(page) {
  page.content = minify(page.content);
}

If you want to use this processor to build your site, you can register it in the _config.js file:

site.process([".html"], minifyHTML);

Now, all HTML pages are minified.

The page object

As you can see in the previous example, the function receives an object with the page (or asset). This object has not only the page content but much more data:

function process(page) {
  page.content; // The content of the page
  page.document; // The parsed HTML code, to use the DOM API
  page.src; // The info about the source file of this page
  page.data; // All data available for this page (front matter merged with _data)
}

For example, let's say you only want to minify the pages where the value minify is true:

site.process([".html"], (page) => {
  if (page.data.minify) {
    page.content = minify(page.content);
  }
});

Using the DOM API

You can use the DOM API (provided by deno-dom) with methods like querySelector, setAttribute, etc to modify HTML code. For example, let's create a processor to add automatically the alt attribute to all images:

site.process([".html"], (page) => {
  page.document?.querySelectorAll("img").forEach((img) => {
    if (!img.hasAttribute("alt")) {
      img.setAttribute("alt", "This is a random alt");
    }
  });
});

Process assets

For non-HTML pages (like CSS or JavaScript files), you can use the processors to compile CSS, minify JavaScript code or minify images.

site.process([".js"], function (page) {
  page.content = myBundler(page.content);

  // Append .min to the filename
  // so it will be saved as example.min.js
  page.data.url = page.data.url.replace(/\.js$/, ".min.js");
});

Make sure the file extension that you want to process is previously loaded. See Loaders for more information about how to register a new loader.

Preprocess

If you need to execute a function before rendering (for example, to configure a custom template engine or add extra data to some pages), you can use a preprocessor. Preprocessors work like processors, but with they are executed before rendering.

Let's create a preprocessor to include a variable with the source filename:

site.preprocess(
  [".html"],
  (page) => page.data.filename = page.src.path + page.src.ext,
);

Create or remove pages dynamically

Some processors can generate additional pages (or remove them). The second argument of the (pre)processors contains an array with all pages that are being processed. You can modify this array to add pages dynamically. For example:

import { Page } from "lume/core/filesystem.ts";

site.process([".css"], (page, pages) => {
  // Minify the css content
  const { code, map } = myCssMinifier(page.content);

  // Update the page content
  page.content = code;

  // Create a new page with the source map
  const url = page.data.url + ".map";
  pages.push(Page.create(url, map));
});

Remove pages dynamically

If a processor returns false, the page is removed from the build process. This allows to creating a processor to filter only some pages:

// Remove all html pages with the language = "en"
site.process([".html"], (page) => {
  const language = page.data.lang;

  if (language === "en") {
    return false;
  }
});

How processors and preprocessors work

Both processors and preprocessors are tied to file extensions (.html, .js etc). To decide if a page must use a registered processor or preprocessor, Lume searches the extension of the input file (like .md or .njk) or the output file (like .html or .css).

Another interesting thing is they are executed in the same order as they are defined. This allows chaining different processors to the same file extension. For example: two processors for the .css extension, one to compile the code and another to minify.

Global (pre)processors

If you want to run a processor or preprocessor for all pages, use * in the first argument:

site.process("*", processAllPages);

Process all pages

site.process and site.preprocess functions works at page level. They only process a page each time. If you need to run the processor only once to all pages, there's the site.processAll and site.preprocessAll. They are very similar but they are executed only once and receives an array of all pages in the first argument:

site.processAll([".html"], (pages) => {
  pages.forEach((page) => my_processor(page));
  console.log(`Processed ${pages.length} HTML pages!`);
});