Loaders and engines

Loaders are functions that read and return the content of files. There are different loaders for different formats, like json, yaml, JavaScript modules or plain text. Creating a custom loader is really easy, you only have to create a function that reads the content of a file and return an object with that content.

Let's say you want to add support for toml format, using the encoding/toml Deno std module:

import { parse } from "https://deno.land/std/encoding/toml.ts";

async function tomlLoader(path) {
  const content = await Deno.readTextFile(path);
  return parse(content);
}

If you want to use this loader to build your site, just register it in the _config.js file, specifying the file extensions to apply:

site.loadData([".toml"], tomlLoader);

Now you can use the TOML format to save data files (_data.toml or _data/*.toml).

To use this format to generate pages, use the loadPages function:

site.loadPages([".toml"], tomlLoader);

Now, any *.toml file in your site will be loaded and used to render a page. For example, the file /about-us.toml will be loaded and saved as /about-us/index.html (unless you configure a different name using the url value.

Instead of HTML pages, you may want to use this loader to load TOML files, process them and save with the same extension (like filename.toml instead of filename/index.html). To do that, you must register it with loadAssets:

site.loadAssets([".toml"], tomlLoader);

Now, the *.toml files are loaded and saved as toml. The function loadAssets is useful to load assets files, like css, js, svg, that you want to transform (bundle, minify...) and save them keeping the same extension, instead of renaming to html.

Note: you can't use the same extension to generate pages and assets, so a way to have support for both is adding a subextension (like tmpl) for pages. Example:

// Use *.html.toml extension for pages
site.loadPages([".html.toml"], tomlLoader);

// And any other *.toml files for assets
site.loadAssets([".toml"], tomlLoader);

This is the same strategy used for JavaScript/TypeScript modules (*.tmpl.js for pages and *.js for JavaScript assets).

Loading plain text

To load text files but without parsing the content, you don't need to pass any loader because the text loader is used by default:

// Load html pages
site.loadPages([".html"]);

// Load js and css files
site.loadAssets([".css", ".js"]);

Template engines

Lume supports several template engines to render your pages, like Nunjucks, Pug or Eta. It's easy to extend this support for more template engines: you only need to create a class extending the Engine interface. Let's see an example using handlebars:

import HandlebarsJS from "https://dev.jspm.io/handlebars@4.7.6";
import { Data, Engine } from "lume/core.ts";

export default class HandlebarsEngine implements Engine {
  /** Render the content */
  render(content: string, data: Data): string {
    const template = HandlebarsJS.compile(content);
    return template(data);
  }

  /** Register helpers */
  addHelper() {}
}

To use this template engine you have to set as third argument of the loadPages function:

import textLoader from "lume/loaders/text.ts";
import HandlebarsEngine from "./handlebars-engine.ts";

site.loadPages([".hbs"], textLoader, new HandlebarsEngine(site));

Now, all files with the .hbs extension will be loaded using the textLoader and rendered using the Handlebars engine.

Note: this is a very basic implementation only as a example. You can see the code of the available template engines in Lume for real examples.