Compilers

Night Owl has built‑in support for templates written in many languages. You can override these compilers or add new compilers for unsupported template languages.

Configuring a compiler

Use the compilers option in your Night Owl configuration to modify the built‑in compilers.

export default {
  compilers: {
    markdown: {
      options: { gfm: false },
      ext: [".custom.md"]
    }
  }
}

options

Provide options to the external library that compiles the template. The shape of this object depends on the options that the library supports. The table below has more information about which libraries are used by different compilers.

ext

An array of file extension strings associated with this compiler. Any template with a file extension included in this list will use this compiler.

compile

Override the default compiler function.

The function receives the template content and filename as arguments, as well as the compiler options.

The function should return an object with either a content string or a render function that will be called with the template data.

The returned object can provide additional data that is passed to the render function. Set the default file extension for generated files using ext. If the template should be recompiled when a dependency changes, add it to the dependencies array.

const compile = function (content, filename, options) {
  return {
    content: "Content string...",
    render: (data) => doSomethingWith(content, options)(data),
    data: { foo: "bar" },
    ext: ".js",
    dependencies: ["imported-file.js"],
  }
}

If a template has front‑matter data, it is extracted from the content before it is passed to the compile function.

Use content for templates that are not affected by data, and render for dynamic templates that depend on template data.

For example, you could replace marked with markdown-it for Markdown templates. Because the content is the same regardless of the template data, we use content, and not render.

import MarkdownIt from "markdown-it"
const md = new MarkdownIt()

export default {
  compilers: {
    markdown: {
      compile: function (content) {
        return { content: md.render(content) }
      },
    },
  },
}

Adding a new compiler

You can also add a completely new compiler using the same compilers option.

For example, you might want to add support for nunjucks templates. This compiler looks for any file that ends in the .html, .njk or .nunjucks extension in your src directory. When it finds one, it uses the nunjucks library to compile the template.

import nunjucks from "nunjucks"

export default {
  compilers: {
    nunjucks: {
      ext: [".html", ".njk", ".nunjucks"],
      compile: (content, filename, options) => {
        return {
          ext: ".html",
          render: nunjucks.compileString(content).render,
        }
      },
    },
  },
}

Built-in compilers

The built‑in compilers will generate HTML, CSS and JavaScript files depending on the file extension.

* For JavaScript templates, esbuild is used to reimport dependencies. This helps to avoid stale imports as you update your source files.