Not anymore! As of version 3.2, Lume can also create books in EPUB format. That's why I wanted to dedicate this version to one of the most important figures of Galician literature of all time: Rosalía de Castro.

You may know Rosalía, the popular Spanish singer. But in Galicia, we have another Rosalía: Rosalía de Castro, probably our most important poet and novelist. She was a leading figure in the period of the resurgence and revitalization of the Galician language in literature during the 19th century (period known as Rexurdimento).

Some of her poems were set to music by several artists. Do you want an example? Enjoy "Negra sombra" (black shadow) interpreted by Luz Casal.

New plugin epub

EPUB is the standard format for ebooks. Technically, it's a zip file containing files in formats like XHTML, CSS, JPEG, PNG; and other xml files specific for ebooks (a container.xml manifest file, a content.opf with the book structure, etc). Robin Whittleton wrote a great article explaining how EPUB works.

Since EPUB is based on web standards that Lume understands, it seems feasible to use Lume to create EPUBs. The only problem was the requirement of XHTML (HTML is not valid for EPUBs), and this wasn't easy to do in previous versions of Lume. But in this version, Lume can output .xhtml files and treat them in the same way as .html, hence we also have an EPUB plugin to help you to generate EPUBs. What this plugin can do?

• Create the container.xml, encryption.xml, mimetype, and content.opf manifest files.
• Create the toc.ncx file with the book structure (using the nav plugin under the hood).
• Convert the code and change the extension of all .html pages to .xhtml.
• Compress all files and create the book.epub file in the dest folder.

This is an example of using the plugin:

import lume from "lume/mod.ts";
import epub from "lume/plugins/epub.ts";

const site = lume({
  prettyUrls: false, // prettyUrls don't make sense for ebooks
});

site.use(epub({
  // Book metadata
  metadata: {
    identifier: "unique identifier of your book",
    cover: "/images/cover.png",
    title: "My awesome book",
    subtitle: "History of my life",
    creator: ["Óscar Otero"],
    publisher: "Lume editions",
    language: "en-US",
    date: new Date("2026-01-31T12:18:28Z"),
  },
}));

export default site;

Note that the plugin cannot magically convert any website to an EPUB; you still need to have a proper structure, use some epub specific attributes, etc. But don't worry! the Simple ePub theme provides a nice boilerplate to start publishing books.

Learn more about this plugin on the documentation page.

New plugin image_size

This is a recurrent request, and finally, Lume has a plugin to add automatically the width and height values of the images.

The plugin uses the awesome image-dimensions library by Sindre Sorhus. To use it, just install it like any other plugin:

import lume from "lume/mod.ts";
import imageSize from "lume/plugins/image_size.ts";

const site = lume();

site.use(imageSize());

export default site;

Add the image-size attribute to the images you want the plugin to calculate the size:

<img src="/image.png" image-size>

And the plugin automatically adds the width and height attributes:

<img src="/image.png" width="600" height="300">

More info on the documentation page.

New plugin extract_order

Sometimes you have a list of pages that you want to show in a specific order. A common way to do that is to define an order variable in the front matter:

---
title: Article 3
order: 3
---

This is the article 3

Then, you only have to select the pages in this specific order:

{{ set pages = search.pages("type=article", "order=asc") }}

This works great, the only problem is that you can't see the pages in the same order in your code editor or file system because they are ordered alphabetically:

/article-three.md
/first-article.md
/other-article.md

With this plugin you can set the order in the filename, using the format {number}.filename, and this value will be used as the order variable. The plugin also removes this prefix from the final URL by default (configurable).

/1.first-article.md
/2.other-article.md
/3.article-three.md

This also works great for folders:

/1.articles/
   1.first-article.md
   2.other-article.md
   3.article-three.md
/2.notes/
   1.note-one.md
   2.note-two.md

To use it:

import lume from "lume/mod.ts";
import extractOrder from "lume/plugins/extract_order.ts";

const site = lume();

site.use(extractOrder());

export default site;

More info on the documentation page.

New plugin replace

This simple plugin allows to perform simple text replacements in the site, something especially useful for documentation sites. For example, let's say you want to display always the last version of your library in a website:

Welcome to Libros 2.3.0, the library to read ebook. To getting started, run the
following command:

deno install --global https://deno.land/x/libros@2.3.0/mod.ts

Instead of harcoding the version number everywhere in your site (and remember to update it after a new version), this plugin allows to use a placeholder:

Welcome to Libros $VERSION, the library to read ebook. To getting started, run
the following command:

deno install --global https://deno.land/x/libros@$VERSION/mod.ts

Now, configure the replacements in the plugin options:

import lume from "lume/mod.ts";
import replace from "lume/plugins/replace.ts";

const site = lume();

site.use(replace({
  replacements: {
    "$VERSION": "2.3.0",
  },
}));

export default site;

Now you have this value centralized in one place. This is the approach used in the Lume website to keep the versions of all packages up to date.

You can use this plugin for any constant value that you want to use globally, like a query parameter for caching CSS and JS files, the hash of the latest commit, the year in the copyright, etc.

More info on the documentation page.

parseBasename can access the parent values

The function site.parseBasename allows registering functions to extract values from files and folders. In fact, it's what the extract_order and extract_date plugins use under the hood.

As of Lume 3.2, the data from the parent folder is added as the second argument. This allows us to compose values contextually using the names of different folders. For example, let's say we have some files with the following paths:

/2026/01/01/happy-new-year.md
/2026/01/05/this-year-sucks.md

Now you can compose the final date of each file using the values of the directories and subdirectories. For example:

site.parseBasename((basename, parent) => {
  // Check if the name only contains numbers
  if (!/^\d+$/.test(name)) {
    return;
  }

  // 4 digits, it's the year
  if (basename.length === 4) {
    return { year: basename, basename }
  }

  // 2 digits, it's the month or day
  if (basename.length === 2) {
    // If the month isn't in the parent, this is the month
    if (!parent.month) {
      return { month: basename, basename }
    }

    // This is the day, generate the final date
    const { year, month } = parent;
    return {
      date: `${year}`-${month}`-${basename}`,
      basename,
    }
  }
})

watcher.dependencies option

The Lume file watcher detects changes in your files in order to rebuild the site with the new content. An important aspect is that only the changed files are reloaded, which is way faster than reloading all files every time something changed. This works great in 99% of the cases, but there are some edge cases where we need to say Lume to reload a file when another file has changed.

As an example, let's say you have some data stored in a SQLite database and you want to expose some of its data to your pages using a _data.ts file:

// _data.ts
import { DatabaseSync } from "node:sqlite";

const db = new DatabaseSync("database.db");

export const categories = db.prepare(`
  SELECT
    categories.id,
    categories.name
  FROM categories
`).all();

db.close();

As you can see, we are exporting the categories variable, and this will make it available to all pages. If we make changes in the database.db file, Lume will detect that the file has changed, but because _data.ts hasn't changed, Lume won't re-run this file, so the new changes won't be available. What we really want is to reload the _data.ts file every time the database.db file has changed. And now we can do it thanks to the new watcher.dependencies option:

import lume from "lume/mod.ts";

const site = lume({
  watcher: {
    dependencies: {
      "_data.ts": ["database.db-journal"],
    },
  },
});

export default site;

Here we are telling Lume that the file _data.ts depends on database.db-journal (the extension .db-journal is used by SQLite to create a temporary file during the data transactions). Now Lume knows that every time any of its dependencies change, _data.ts will be reloaded too.

Better logs

When Lume builds a site, the logger outputs messages to the terminal in the same order they are generated. One problem with this approach is that there are messages more important than others, and, especially if the site has a lot of pages, those messages can be lost among others. Another problem is that if the same error is produced by different pages, it's shown once per page, which produces a lot of noise and prevents seeing other important messages. Let's see an example:

WARN [esbuild plugin] No TS, JS, TSX, JSX files found. Use site.add() to add files. For example: site.add("script.js")
ERROR SourceError: Unclosed tag
/_includes/templates/blocks.vto:4:3
 1 | {{ for block of blocks }}
 2 |   {{ if !block.hide }}
 3 |     {{ await comp[block.type]({ block, lang, url }) }}
 4 |   {{ /if }
   |   ^ Unclosed tag
ERROR SourceError: Unclosed tag
/_includes/templates/blocks.vto:4:3
 1 | {{ for block of blocks }}
 2 |   {{ if !block.hide }}
 3 |     {{ await comp[block.type]({ block, lang, url }) }}
 4 |   {{ /if }
   |   ^ Unclosed tag
🔥 /docs/configuration/env-variables/ <- /docs/configuration/env-variables.md
🔥 /docs/configuration/config-file/ <- /docs/configuration/config-file.md
🔥 /docs/configuration/add-files/ <- /docs/configuration/add-files.md
🔥 /img/extend.svg <- /img/extend.svg
🔥 /img/deploy.svg <- /img/deploy.svg
...
🔥 /img/http-imports.svg <- /img/http-imports.svg
🔥 /init.ts <- /static/init.ts
🔥 /img/gradient.png <- /img/gradient.png
🔥 /img/zero-runtime.svg <- /img/zero-runtime.svg
🔥 /logo.png <- /static/logo.png
WARN [validate_html plugin] 512 HTML error(s) found. Setup an output file or check the debug bar.
WARN [seo plugin] 45 SEO error(s) found. Setup an output file or check the debug bar.
🍾 Site built into ./_site
  188 files generated in 6.28 seconds

In the example, the Vento error shown twice because it occurred on two pages. There are some WARN errors at the start and others at the end, and a long list of generated pages in the middle.

In order to make the logs clearer, two changes were introduced in this version of Lume:

• Messages of type WARN, ERROR, and FATAL are shown at the end, sorted by severity (WARN first, FATAL last). Other levels (TRACE, DEBUG, and INFO) are still shown as they were produced.
• Duplicated logs are removed.

The example above is shown as follows in the new version:

...
🔥 /img/http-imports.svg <- /img/http-imports.svg
🔥 /init.ts <- /static/init.ts
🔥 /img/gradient.png <- /img/gradient.png
🔥 /img/zero-runtime.svg <- /img/zero-runtime.svg
🔥 /logo.png <- /static/logo.png
🍾 Site built into ./_site
  188 files generated in 6.28 seconds
WARN [validate_html plugin] 512 HTML error(s) found. Setup an output file or check the debug bar.
WARN [seo plugin] 45 SEO error(s) found. Setup an output file or check the debug bar.
WARN [esbuild plugin] No TS, JS, TSX, JSX files found. Use site.add() to add files. For example: site.add("script.js")
ERROR SourceError: Unclosed tag
/_includes/templates/blocks.vto:4:3
 1 | {{ for block of blocks }}
 2 |   {{ if !block.hide }}
 3 |     {{ await comp[block.type]({ block, lang, url }) }}
 4 |   {{ /if }
   |   ^ Unclosed tag

This hopefully ensures that you won't miss anything important during the build process!

Other changes

This version also includes some minor changes and several bugfixes. Some of them:

• katex plugin supports mhchem extension and includes an option to disable the download of CSS and fonts.
• The date filter registered by date plugin detects the language of the current page.
• Some improvements to the LumeCMS integration.
• If you have a script.ts file, it no longer conflicts with the script.js file generated by components.
• Fix globbing on npm/gh specifiers.
• And many more changes that you can see in the CHANGELOG.md file.

Finally, I'd like to thank all contributors for helping make Lume so great with PR or supporting the project with sponsoring and donations. 🫶

I've wanted to change the logo for a long time, and finally, I could manage some time to work on that. There are many reasons for this change:

• The Lume logo is based on the original logo of Deno, which has changed twice since then.
• Some people think Lume is a Deno product.
• The logo doesn't work for small sizes.

The vagalume

For the new logo, I wanted to focus on the main concept of Lume: the fire. I didn't want to create yet another logo with a flame. Instead, I still wanted a pet, but a firefly instead of a dinosaur.

Interestingly enough, in Galician, a firefly is called vagalume, which makes sense for a project called Lume.

Logo design

The new logo is more geometric, created with a leaf shape repeated five times, and a head with two antennae. This simple design makes it work better at small sizes.

The red color is used to represent the fire that emits light (using a gradient). It also works in dark and light contexts, just inverting the black and white colors:

The font family used didn't change. It's still Epilogue, a beautiful sans-serif font with a great x-height. I only made some kerning tweaks and the name is now "Lume" (with upper case L) instead of "lume".

Thanks to José Luis Antúnez for the feedback and suggestions, and to Studio Ghibli for the film Grave of the Fireflies from which I got some inspiration.

[...] I will die peacefully; I trust that I will be received where we all want to get together, and I do it with joy and entrust to God this sacrifice. I wanted to do good, I worked for Pontevedra, for Galicia, and for the Republic, and the flawed judgment of men (which I forgive and you all must forgive) condemns me.

Be more of a man now than ever because this is when you should be the most, for our elderly and for the children, to whom, without expecting it, you are going to be a little father. Comfort them all and try to always be good. Don't regret how much good you have done and can still do. [...]

Alexandre is not only a Galician martyr but also a demonstration that there have always been good people in the world. Now, more than ever, we have to remember that.

Lume is moving to jsDelivr

For the past 5 years, Lume's main distribution channel has been deno.land/x, the CDN created by Deno to distribute packages using HTTP imports. This package registry has been deprecated in favor of JSR, a new registry that doesn't support HTTP. Since Deno doesn't want people to use deno.land/x (as indicated in the two big yellow banners in the page to add new modules) and migration to JSR is not an option, we decided to switch to a different CDN.

jsDelivr is the obvious choice for many reasons:

• It's supported by Deno without any configuration.
• It's already used to publish LumeCMS, deliver the development versions of Lume, and fetch some assets like icons or CSS code, needed by some plugins.
• It has a nice landing page for each package, where you can see all the files, and statistics, something not possible in deno.land/x. We can even see statistics per file, which lets us know the plugins most frequently used.
• The traffic is balanced by different CDN sponsors like Cloudflare, Fastly, Bunny.net, etc, which ensure performance and reduce risks of relying on a single CDN.
• All content is permanently cached to ensure reliability. Even if the files get deleted from GitHub, they will continue to work on jsDelivr without breaking anything.

Lume will still be published on deno.land/x; the only difference is that the script to update or initialize a new Lume project will choose jsDelivr by default. That's one of the many benefits of using HTTP imports: its decentralized nature allows you to change the CDN at any moment with zero impact.

Improved deno.json file

Deno added some great improvements to deno.json in recent versions that Lume has adopted for the init and upgrade script:

lume task uses bare specifier

Deno 2.4 added support for bare specifiers in deno run. In older versions, the only way to use a specifier defined in the import map was using deno eval or the ugly:

{
  "tasks": {
    "lume": "echo \"import 'lume/cli.ts'\" | deno run -A -"
  }
}

But now, this is supported:

{
  "tasks": {
    "lume": "deno run -A lume/cli.ts"
  }
}

lume tasks have descriptions

To improve the UX, the tasks created by Lume include a description. Run deno task to see all available tasks with the description:

{
  "tasks": {
    "lume": {
      "description": "Run Lume command",
      "command": "deno run -A lume/cli.ts"
    },
    "build": {
      "description": "Build the site for production",
      "command": "deno task lume"
    },
    "serve": {
      "description": "Run and serve the site for development",
      "command": "deno task lume -s"
    }
  }
}

Permissions

Deno 2.5 allows to configure permissions in the deno.json file, and Lume adopted this nice feature. Now you have the lume permission preset that is used when running the lume task (previously, it used the -A flag, which disables the permissions). This will improve the security of your builds and will make it easy to edit the permissions to adapt to your needs. This is the default configuration:

{
  "permissions": {
    "lume": {
      "read": true,
      "write": [
        "./"
      ],
      "import": [
        "cdn.jsdelivr.net:443",
        "jsr.io:443",
        "deno.land:443",
        "esm.sh:443"
      ],
      "net": [
        "0.0.0.0",
        "jsr.io:443",
        "cdn.jsdelivr.net:443",
        "data.jsdelivr.com:443",
        "registry.npmjs.org:443"
      ],
      "env": true,
      "run": true,
      "ffi": true,
      "sys": true
    }
  }
}

As you can see, Deno only has writing permissions for the current folder, net permissions to localhost (to run the local server), and net and import permissions for JSR, NPM, esm.sh and JsDelivr (to import dependencies). The other permissions are granted by default because they are needed for some plugins, but you can edit this configuration to make it more restrictive or relaxed.

Better integration with LumeCMS

One of the main challenges with LumeCMS has been integrating it smoothly with Lume or other static site generators. Previously, LumeCMS relied on Hono to run both the CMS and the page preview, which could lead to inconsistencies: a page served by Lume (deno task serve) might differ from one served by LumeCMS, since Hono's static server doesn't exactly match Lume's. For example, middlewares configured for Lume are not available in the CMS, and this affects features like live reload, debugbar, etc.

Moved to middleware

With version 0.13, LumeCMS introduces significant changes. Now, LumeCMS is a middleware on top of Lume's server, handling only requests that start with /admin/* while delegating page previews to Lume's server. This makes the integration easier, eliminating the need for separate commands (deno task serve and deno task cms).

This means that the cms task was removed. Just run deno task serve and, if the _cms.ts file is present, the CMS is automatically initialized.

Improved VPS configuration

When LumeCMS is running on a VPS, it requires two processes:

• The main process is an HTTP server that is always listening.
• The secondary process runs Lume and LumeCMS.

The main process starts the secondary process on demand and works as a reverse proxy. This allows restarting Lume and LumeCMS after some changes (for example, when updating the changes with git pull or after changing the git branch) without closing the server.

Until now, you needed to use an external package to setup it. Now it's much easier since Lume's main repo includes a module to run the CMS in production: You only need to run deno serve -A lume/serve.ts and that's all!!

New plugin: validate_html

This plugin checks the HTML code of your site and validates it using html-validate, a fast NPM package that works offline.

The plugin was originally created by dish and now it's an official Lume plugin, integrated with the Debug bar and with different options to export the report.

The easiest way to use it is to import it into the _config.ts file:

import lume from "lume/mod.ts";
import validateHtml from "lume/plugins/validate_html.ts";

const site = lume();
site.use(validateHtml());

export default site;

Now you will see a new tab in the Debug bar with all HTML errors detected in the site:

I hope this plugin will help you to create more standard and bug-free websites.

New plugin: partytown

Partytown is a JavaScript library to run third-party scripts in a web worker. The goal is to dedicate the main thread to your code, and move other resource-intensive third-party scripts, like analytics or tracking services to a different thread, making the website faster and more secure.

The plugin was created originally by kwaa 2 years ago as an experimental plugin, and now it has moved to the main repo. To use it, you have to register it in the _config.ts file:

import lume from "lume/mod.ts";
import partytown from "lume/plugins/partytown.ts";

const site = lume();
site.use(partytown());

export default site;

And now add the type="text/partytown" attribute to all scripts that you want to run from the web worker:

<script type="text/partytown">...</script>

New plugin: seo

This plugin was created by Tim Post with the help of Rick Cogley for the Japanese language support (thanks so much, guys!). It's a really interesting plugin that not only can check the SEO basics (titles, descriptions, alt text in images, etc) but also other not very common checks like common words percentage.

Since Tim couldn't maintain it, we decided to port it to the Lume repo and convert it to an "official plugin". It was modified in order to align with the style and conventions of other plugins, and it was simplified a bit to make it more maintainable in the long run (originally, the project was more ambitious).

The installation is not different from other plugins, just import it into the _config.ts file:

import lume from "lume/mod.ts";
import seo from "lume/plugins/seo.ts";

const site = lume();
site.use(seo());

export default site;

Like other validator plugins (check_urls, validate_html, etc), it creates a new tab in the debug bar with all SEO issues found in all pages. It also has an option to export the report to a JSON file or any other format by providing a custom export function.

The plugin is highly customizable. The default options are enough for most cases, but you can change how to validate titles, H1 tags, meta descriptions, heading orders, duplicated titles, etc. Definitely, this plugin will help you to create more successful websites!

Improved remote files

The function remoteFile allows the use of URLs to download the content of a file if it doesn't exist locally. For example:

site.remoteFile("/styles/styles.css", "https://example.com/styles/styles.css");

If the file /styles/styles.css doesn't exist locally, the content of the URL will be used in place. This is very useful for themes because it allows for placing all templates and styles used by a theme remotely.

The only problem with this function is that it only works for single files. If you have several files, you need to call the function once per file:

const files = [
  "styles.css",
  "components/button.css",
  "components/alert.css",
  "components/icons.css",
];

for (const file of files) {
  site.remoteFile("/styles/" + file, "https://example.com/styles/" + file);
}

New site.remote() function

Lume 3.1 includes the new function site.remote() similar to site.remoteFile() but allows to register more than one file:

const files = [
  "styles.css",
  "components/button.css",
  "components/alert.css",
  "components/icons.css",
];

site.remote("/styles/", "https://example.com/styles/", files);

Okay, you may think this isn't a big improvement, it's just a bit simpler. But the good news is that you can use some specifiers that are compatible with glob patterns:

• npm: to use NPM packages (like npm:lucide-static@0.544.0)
• gh: to use GitHub repositories (like gh:lumeland/theme-simple-wiki)
• file: to use local files
• All URLs starting with https://cdn.jsdelivr.net/.

For example, let's say the CSS files are stored in a GitHub repository:

const files = [
  "/styles/**/*.css",
];

site.remote("/styles/", "gh:username/repo@tag", files);

That's better now! Under the hood, this is possible thanks to the API of JsDelivr. Any compatible specifier is converted to JsDelivr equivalent.

For example, gh:lumeland/theme-simple-wiki@0.14.3 is converted to https://cdn.jsdelivr.net/gh/lumeland/theme-simple-wiki@0.14.3/. And using the JsDelivr API, we can know the paths of all files in the repository (example), so we can filter them using the glob pattern.

Create themes is now easier

Thanks to this new function, it's easier to create Lume themes, since you don't have to worry about forgetting to include a new file that was recently created. Let's see this example:

const themeFiles = [
  "/_includes/**",
  "/*.css",
  "/*.js",
  "/*.vto",
];

site.remote("/", import.meta.resolve("./"), themeFiles);

In local development, import.meta.resolve("./") resolves to a file://... url, so the glob patterns work great. If this package is published and imported from JsDelivr, it's resolved to https://cdn.jsdelivr.net/gh/user/repo@tag, and the glob patterns are still supported thanks to the JsDelivr API. This is another reason to recommend distributing Deno packages on JsDelivr over deno.land/x.

Inline plugin works with CSS files

As of Lume 3.1, the inline plugin not only processes HTML files but also CSS. This allows for inlining background images easily. To use it, just append the ?inline parameter to the file URL. For example:

.warning {
  background-image: url("/icons/warning.svg?inline");
}

Is converted to:

.warning {
  background-image: url("data:image/svg+xml;utf8,<svg...</svg>");
}

Picture plugin allows to crop images

Until now, the picture plugin has only allowed the width value to resize images. For example, this configuration transforms the image to 300px and 600px, with versions for 2x resolutions and formats AVIF, WebP, and JPG:

<img src="/flowers.jpg" transform-images="avif webp jpg 300@2 600@2">

Now it's possible to specify a height to crop the images to a specific aspect ratio:

<img src="/flowers.jpg" transform-images="avif webp jpg 300x150@2 600x300@2">

The image will be cropped to 300x150 and 600x300, with a version for 2x resolutions. For now, there isn't any way to configure the origin of the crop (it's always centered), but this option can be added in future versions.

See the CHANGELOG.md file to see a complete list of all changes.

During this time, the project was improved in many ways: more field formats, more customization options, light/dark mode, etc.

But, like many projects in their earlier phases, LumeCMS was a bit "tricky" to run. It was created as a framework-agnostic solution, but in practice, it wasn't easy to set up for other frameworks than Lume.

Version 0.13 has received a lot of changes in order to address this issue, among others. Some of these changes are BREAKING CHANGES (hopefully they are only a few). And even though it's still a development version (the version starts with v0.* yet), I think it's an important step towards the future v1.0 version.

New router

Since the beginning, LumeCMS has used Hono under the hood. Although Hono is a very powerful and popular framework, I found it a bit complicated to work with. The way to pass data (or contexts) to routers and middlewares, the rendering system or the use of the custom class HonoRequest for the request instead of the standard Request (that is also available but hidden) made me spend more time trying to figure out how to do something in "Hono way" than just doing it. In addition to that, it's becoming a full-featured framework with even a client-side JSX library.

That's why Galo was created. It's a fast and minimalist router that embraces web standards and simplicity without sacrificing flexibility. The change from a framework approach to a library like this made LumeCMS much easier to embed in any application running Deno. In fact, LumeCMS is now a middleware for your application without any side effects or interference with your existing code.

Document types

LumeCMS was created assuming that all data would be stored in an object. Let's see this example:

cms.collection({
  name: "notes",
  storage: "src:notes/*.json",
  fields: [
    "title: text",
    "text: textarea",
  ],
});

This stores every note in a JSON file in the notes/ directory. The stored notes have a structure like this:

{
  "title": "Note title",
  "text": "This is the note"
}

If you want to store all notes in a single JSON file, you can use an object-list field to store an array of objects:

cms.document({
  name: "notes",
  storage: "src:notes.json",
  fields: [
    {
      name: "notes",
      type: "object-list",
      fields: [
        "title: text",
        "text: textarea",
      ],
    },
  ],
});

This configuration produces the following data structure:

{
  "notes": [
    {
      "title": "First note",
      "text": "Text of the first note"
    },
    {
      "title": "Second note",
      "text": "Text of the second note"
    }
  ]
}

As you can see, the root of the data is still an object with the notes property to hold the array of notes. But what we really want is to store the array of notes as the root element. Until now, the solution was to change the name of the root value from notes to []:

cms.document({
  name: "notes",
  storage: "src:notes.json",
  fields: [
    {
      name: "[]",
      type: "object-list",
      fields: [
        "title: text",
        "text: textarea",
      ],
    },
  ],
});

LumeCMS detected the special name "[]" as an instruction to ignore the element and store its content directly. This allows us to store the data as an array:

[
  {
    "title": "First note",
    "text": "Text of the first note"
  },
  {
    "title": "Second note",
    "text": "Text of the second note"
  }
]

The problem with this solution is that it's a bit hacky, verbose, and not very flexible. That's why in version 0.13 this feature was replaced with the new type option:

cms.document({
  name: "notes",
  storage: "src:notes.json",
  type: "object-list",
  fields: [
    "title: text",
    "text: textarea",
  ],
});

As you may guess, this option configures the field type used to store the root data. If it's not defined, the default value is object, but other available values are object-list (to store an array of objects) and choose (to allow the user to choose one structure among a list of options). More types can be added in future versions.

New previewUrl and sourcePath options

One of the great features of LumeCMS is the ability to preview the changes while editing the data. To provide this, we need two things:

• A way to know the URL generated by a file. For example, if we know that the file /posts/hello-world.md produces the URL /posts/hello-world/, we can display this URL in the preview panel when the file is being edited.
• A way to know the source file of a URL. If we know that the URL /posts/hello-world/ is generated by /posts/hello-world.md, we can create a "Edit this page" link to go directly to the edit form.

Until now, the way to get this info was a bit obscure and undocumented. In version 0.13, this is fully configurable, which makes the CMS easier to adapt for other static site generators:

const cms = lumeCMS({
  previewUrl(path: string, content: Lume.CMS.Content, changed: boolean) {
    // Return the URL generated by this file
 },
  sourcePath(url: string, content: Lume.CMS.Content) {
    // Return the file path that generates this URL
 }
});

The previewUrl is also customizable at the document or collection level, useful if you're editing a file that doesn't directly produce a URL but can affect it (like a _data file):

cms.document({
  name: "Common data",
  storage: "src:_data.yml",
  previewUrl: () => "/", // preview the homepage
  fields: [
    "title: text",
    "description: textarea",
  ],
});

User-level permissions

In previous versions, you could configure the permissions to create, edit, rename, or delete documents globally. For example, let's say we have a collection of countries that we don't want to remove or create new ones, just edit them:

cms.collection({
  name: "countries",
  storage: "src:countries/*.json",
  fields: [
    "name: text",
    "description: textarea",
  ],
  create: false,
  delete: false,
  rename: false,
});

With this configuration, all users can edit the countries, but cannot create, delete, or rename files. In version 0.13.0, we can override this configuration for some users:

cms.auth({
  user1: {
    password: "password1",
    name: "Admin",
    permissions: {
      "countries": {
        create: true,
        delete: true,
        rename: true,
      },
    },
  },
  user2: "password2",
});

In previous versions, the auth configuration was simply an object with names and passwords. Now, we can also use an object to include more options. In this example, the "user1" has a password, the name "Admin" (which is used to show it in the interface instead of "user1"), and some special permissions that override the permissions assigned to documents and collections: this user can create, rename, and delete files of the countries collection, unlike "user2".

Improved documentLabel

If you see the list of documents in a collection, LumeCMS only displays the file names. Since it doesn't load the documents data, it can't use any value inside them (like title or date properties). The option documentLabel allows customization of how this document is shown in the interface. For example, it can transform the name my-first-post.md to a more human My First Post. In fact, LumeCMS comes with this especific behavior by default, but you can customize it with your own tranformer:

cms.collection({
  documentLabel: (filename) => filename.replace(".json", ""),
  // More options...
});

As of version 0.13, this function can return an object with the properties label, icon, and flags to extract and show more info in the list view.

Let's say our collection of countries is a folder with the following files:

/en-spain.json
/pt-portugal.json
/fr-france.json
/it-italy.json

We can configure the collection to show only the country name, and use the flag icon (from Phosphor) instead of the default document icon. The country code is the code is saved in the flags object:

cms.collection({
  documentLabel: (filename) => {
    const [code, name] = filename.replace(".json", "").split("-");
    return {
      label: name,
      icon: "flag"
      flags: { code }
    }
  },
  // ...more options
});

New relation and relation-list fields

This feature is related to the improvements on documentLabel explained above. Now that we can extract more info from the filename, we can use this info to link a document to another. For example, let's say we have the "people" collection and we want to assign a country to each person:

cms.collection({
  name: "people",
  storage: "src:people/*.md",
  fields: [
    "name: text",
    {
      name: "country",
      type: "relation",

      // The collection name that we want to relate
      collection: "countries",

      // A function to return a label and value for each option
      option: ({ label, flags }) => { label, value: flags.code }
    }
  ]
});

Now, this field shows a selector to pick one of the countries and use the code flag as the value (en for Spain, pt for Portugal, etc). The relation-list field is similar but allows for storing an array of values.

Better git commits

The git commits created by LumeCMS now include the current user name as the author. It's also possible to include the email by adding the email property to the user settings:

cms.auth({
  user1: {
    password: "password1",

    // name & email are included in the commits created by this user.
    name: "Admin",
    email: "user@example.com",
  },
});

Allow to edit raw files

Now it's possible to configure a document without fields, to show a code editor instead of a form to edit it. It's useful to edit code directly from the CMS:

cms.document({
  name: "Custom styles",
  storage: "src:style.css",
});

Removed timezone from Date and Datetime fields

From now on, date and datetime fields don't include the timezone in the YAML files. Hopefully, it will fix a lot of problems related to unexpected dates due to different time zones.

# before
date: 2025-01-11T00:00:00.000Z

# after
date: 2025-01-11 00:00:00

And more changes

There are more changes in this version, like UI improvements, ability to show EXIF data from uploaded images, the new cssSelector option to highlight an element in the previewer related with a field, etc.

Take a look at the CHANGELOG.md file to see the complete list of changes.

Lume compability

This version isn't compatible with Lume 3.0.x, but it will be in Lume 3.1.

If you want to try it, upgrade Lume to the latest development version with:

deno task lume upgrade --dev

Then, run deno task serve and the CMS is automatically created if a _cms.ts file is detected. You won't need to run deno task cms anymore!

Vento was born two years ago as an experiment to create a modern, ergonomic, and async-friendly template engine for JavaScript. Initially, it was a Deno-only project, intended to become the default template engine for Lume. But as soon as the NPM package was available, other projects started to use it.

During this period, a number of people got involved in the development.

• wrap made a wonderful work implementing and maintaining a JavaScript analyzer to automatically resolve the global variables (so you can type {{ somevariable }} instead of {{ it.somevariable }}. She's also responsible for the tree-sitter parser to bring support for Neovim and similar editors.
• Noel Forte created the 11ty plugin that made Vento popular in the 11ty ecosystem.
• Deniz Akşimşek created the Zed plugin.
• Illyrius brought support for WebStorm.

Vento wouldn't be so awesome without the help of these contributors and many other that improve it with their selfless work. THANK YOU SO MUCH!

Why create a version 2?

Everything started with this post where vrugtehagel exposed some issues detected in Vento. He was kind enough to send me an email to let me know about the post whose constructive feedback was very helpful and several issues mentioned were addressed in Vento 1.

However, vrugtehagel not only limited himself to providing feedback, but he also started to get involved in the Sublime Text plugin and created a bunch of pull requests to the Vento repository, leading to some interesting discussions about Vento's philosophy and its implementation approach. The most demanding challenge, for which we made different proofs of concept, was to find an alternative way to analyze the JavaScript code without using meriyah or any other dependency. This would make the compilation faster and remove all Vento dependencies.

Thanks to this change, the local footprint was reduced from 1.8MB to less than 80Kb (18KB bundled and minified).

The next step was to convert Vento in an isomorphic library, which makes it to work on browsers and on Node-like runtimes (Node, Deno, Bun) without changes or the need for a compilation step.

And finally, one of the pain points of Vento, error reporting, was also addressed thanks to the initial work of vrugtehagel and some subsequent changes by me.

Vento is now a modern, lean, and powerful template engine that can be used on any JavaScript runtime and embedded on any framework easily.

Main changes

After upgrading to Vento 2, almost everything in your .vto files should continue working as usual without changes, although there might be some edge cases that now have a different behavior.

New variable resolution

In Vento 1, when you run Hello {{ name }}, the compiler converts it automatically to Hello {{ it.name }}. This means that, technically, you could define a variable directly in the it global variable and it would be accessible without the prefix. For example, the following code would print "Hello World":

{{> it.name = "World" }}
Hello {{ name }}

Vento 2 uses a different approach. When Vento compiles the following template:

Hello {{ name }}

all variables used are initialized preventively at the begining like this:

var { name } = it;

The variable is not replaced with it.name automatically everywhere but the real variable name is created instead. If you edit the value of it.name in your code directly, it won't affect name. However, this is more a Vento's internals change and it's unlikely to affect to final users since they never should edit the it variable directly, but use the code {{ set name = "other value" }}.

New error handler

Any error produced while compiling or running the templates is now converted to a VentoError class. This class contains all the information required to report the exact point where the error originates. For example, the following template produce an error because we are invoking a function from a null variable:

{{ set name = null }}
{{ name.foo() }}

In order to run and pretty-print errors, you can use the printError helper:

import vento from "vento/mod.ts";
import { printError } from "vento/core/error.js";

const env = vento();

try {
  const result = await env.run("my-template.vto");
} catch (err) {
  console.error(await printError(err));
}

This outputs the following:

TypeError: Cannot read properties of null (reading 'foo')
test/main.vto:2:1
 1 | {{ set name = null }}
 2 | {{ name.foo() }}
   | ^
   | __exports.content += (name.foo()) ?? "";
   |                              ^ Cannot read properties of null (reading 'foo')

The error displays the tag where the error occurs and it can show also the error in the compiled code (the final JavaScript code) to give more context.

Note that the error handler doesn't work consistently accross all runtimes, due their differences providing useful data from the error stack. For example, it works pretty well on Deno, but Node and Bun cannot recover the exact location of some errors so it's not possible to provide detailed info in some cases. There may be also some differences between browsers.

I hope this feature can be improved in next versions. PR are very appreciated!

Removed sync mode

Vento is async by default, it's one of its main selling points. In Vento 1 there was also the function runStringSync to run arbitrary code in a synchronous context. For example: env.runStringSync("Hello {{ name }}", { name: "World"}).

This mode was originally created because Lume needed it. However, the synchronous mode doesn't fit well with how Vento works internally. Having both sync and async modes makes everything more complicated, and the sync mode breaks if your template has async tags, like {{ include }}, or runs any async function or filter.

Since Lume no longer needs this feature, the function was removed in Vento 2, and now all templates are run consistently in an async context.

New slot tag

The layout tag allows to render a template passing extra content. This is great for layouts expecting only one piece of content. But if the layout requires more pieces, you have to pass them as variables:

{{ layout "article.vto" { header: "<h1>This is the title</h1>" } }}
  <p>This is the content</p>
{{ /layout }}

The new slot tag allows to capture and store the content in different variables, similar to what web components do.

{{ layout "article.vto" }}
  {{ slot header }}
    <h1>This is the title</h1>
  {{ /slot }}

  <p>This is the content</p>
{{ /layout }}

Learn more about slots in the documentation site.

Browser support

As said, Vento 2 works also on browsers, without any compilation step, thanks to not having dependencies and the use of standard APIs. You can download the NPM package or use a CDN like jsDelivr:

import vento from "https://cdn.jsdelivr.net/npm/ventojs@2.0.0/web.js";

const env = vento({
  includes: import.meta.resolve("./templates"),
});

const result = await env.run("main.vto");
console.log(result.content);

Note that instead of importing the mod.js module, you have to import web.js. The only difference is that web.js uses the URL loader by default to load templates using fetch. The includes option defines the base URL to load all templates.

Benchmarks

Vento 1 was already quite fast, but version 2 is even faster thanks to the new compiler.

Vento 1 vs Vento 2

The compiler in Vento 2 is almost 200% faster as you can see in the following benchmark:

When comparing the rendering performance of Vento 1 and Vento 2, there are no significant differences. Vento 1 may be slightly faster, but the difference is minimal and not easily noticeable.

Comparing compilation and rendering performance, Vento 2 demonstrates a 180% speed improvement. Even if a few milliseconds are lost during rendering, the overall performance gain more than compensates for it.

Comparison with other libraries

To compare the performance of Vento with other template engines, you can run the bench code in Vento's repository. As of writing this post, the benchmark data is:

Vento delivers exceptional rendering performance. While Eta and EJS offer faster compilation speeds, they struggle with delimiter handling. For example, <%= '%>' %> throws an error in EJS, but Vento handles the equivalent, {{ '}}' }}, perfectly fine.

Update now

Vento 2 is available on NPM (for Node-like runtimes) and HTTP imports (for browsers and Deno). See the CHANGELOG file for the full list of changes.

This version is dedicated to all Galician cantareiras and pandereteiras—women who sing and play the tambourine (or pandeireta), one of the most important instruments in Galician traditional music. One of these cantareiras was Adolfina Casás Rama (1912-2009), an ancestor of my friend Miriam Casás. She worked in agriculture, where she often sang. She was known for her wit and the variety of styles employed.

Thanks to the recollidas, where musicians and musicologists recorded these traditional songs sung by anonymous women, we can now enjoy this musical heritage performed by contemporary musicians with innovative arrangements.

Some examples include Xabier Díaz & Adufeiras de Salitre, Xosé Lois Romero & Aliboria, and Berrogüetto (apologies for the video quality, but I really love that song).

For more disruptive artists, check out Tanxugueiras or Baiuca.

Why Lume 3?

To many developers, including myself, breaking changes can be frustrating. Software updates that force you to revisit a project just to ensure it continues working as before often feel like a waste of time. This is one of the reasons I enjoy working with Web APIs—they are stable, reliable, and designed to just work without introducing unnecessary disruptions.

I strive to bring a similar philosophy to Lume by minimizing breaking changes whenever possible. In fact, I initially had no plans to release a new major version of Lume. However, after receiving numerous reports about certain behaviors and limitations, I realized it was necessary to revisit some design decisions. This effort aims to finally deliver the simple, intuitive static site generator I have always envisioned, hoping that Lume 4 won't be necesary in a long time, or never.

The main problem

The site.copy() function allows you to copy files from the src folder without reading the content, which is faster and consumes less memory. But it has one big drawback: the files are not processed.

For example, let's say you have the following configuration:

site.copy("/assets");
site.use(postcss());

When Lume builds your site, the files inside the /assets folder are copied as-is. If the folder contains CSS files, they won't be processed by Postcss. Learn more about this issue on GitHub.

This behavior is confusing and many people reported this as a bug. And they are right: Lume should be clever enough to not delegate the decision of whether a file must be loaded or copied.

The solution: site.add()

In Lume 3, the site.loadAssets(), site.copyRemainingFiles() and site.copy() functions were removed, and now there is a single function for everything: site.add().

The add() function simply tells Lume that you want to include some files in your site, but without specifying how this file must be treated. Lume will load the file if it needs to (for example, if it needs to be processed), or will copy it if no transformations are needed.

site.add("/assets");
site.use(postcss()); // CSS files in /assets will be processed too!

To upgrade from Lume 2 to Lume 3, just replace the site.loadAssets(), site.copyRemainingFiles(), and site.copy() functions with site.add().

For example:

// Lume 2
site.loadAssets([".css"]);
site.copy("/assets", ".");
site.copyRemainingFiles(
  (path: string) => path.startsWith("/articles/"),
);

// Lume 3
site.add([".css"]);
site.add("/assets", ".");
site.add("/articles");

Update: Some users have reported that site.copy() remains useful in specific scenarios. For instance, if you need to copy a CSS file without processing it. As a result, the site.copy() function was reintroduced in Lume 3.0.1 to address these edge cases.

Copy remote files

site.add() can add files from the src folder as well as remote files. In Lume 2, this was possible with the remoteFile function:

// Lume 2
site.remoteFile("styles.css", "https://example.com/theme/styles.css");
site.copy("styles.css");

Lume 3 makes this use case easier:

// Lume 3
site.add("https://example.com/theme/styles.css", "styles.css");

The site.add() function also accepts npm specifiers:

site.add("npm:normalize.css", "/styles/normalize.css");

Internally, this uses jsDelivr to download the file. In this example, npm:normalize.css is transformed to https://cdn.jsdelivr.net/npm/normalize.css. Note that only one file is copied, not all package files.

More info in the documentation page.

Plugins no longer load files automatically

In Lume 2, some plugins configure Lume to load files with a certain extension automatically. For example, Postcss not only processes the CSS code but also configures Lume to load all CSS files:

// All .css files are loaded and processed
site.use(postcss());

In some cases, this is what you want. But if you don't want to load all CSS files, this behavior makes Lume load everything, and you have to use the site.ignore() function or move the unwanted files to a folder starting with _.

In addition to that, this behavior is not fully transparent. You have to read the documentation to know what the plugin is doing.

In short, this approach causes more harm than good.

In Lume 3, thanks to the site.add() function, it's very easy to add new files (and only the files that you want), so plugins no longer load files by default. You have to explicitly add them, which is more intuitive:

// Lume 2
site.use(postcss());

// Lume 3
site.add([".css"]);
site.use(postcss());

Another benefit is you have better control of all entry points of your assets. For example, for esbuild:

// Lume 3
site.add("main.ts");
site.use(esbuild()); // Only main.ts is bundled

This change affects the svgo, transform_images, picture, postcss, sass, tailwindcss, unocss, esbuild and terser plugins.

JSX

One JSX plugin

Lume started supporting JSX as a template engine thanks to the jsx plugin that uses React under the hood. Later, the jsx_preact plugin was added to use Preact, a smaller and more performant alternative to React.

Having two JSX plugins for the same purpose is useless and adds unnecessary complexity (for example, combined with the MDX plugin).

Moreover, both libraries are frontend-first libraries, with features like hooks, event callbacks, hydration, etc, that are not supported at build time, so some people were confused about what they can or cannot do in Lume.

Lume 3 has only one JSX plugin, and it doesn't use React or Preact but SSX, a TypeScript library created specifically for static sites which is faster than React and Preact and more ergonomic. It allows creating asynchronous components, inserting raw code like <!doctype html>, and comes with great documentation including all HTML elements and attributes, with links to MDN.

Lume 3 uses lume/jsx-runtime import source for all JSX and MDX files. So you only have to configure the compilerOptions setting of deno.json as following (other options have been omited for brevity):

{
  "imports": {
    "lume/jsx-runtime": "https://deno.land/x/ssx@v0.1.8/jsx-runtime.ts"
  },
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "lume"
  }
}

This allows to upgrade the library (or even replace it with something else) easily.

.page Subextension for JSX and TSX Pages

Lume requires the .page subextension for certain file types like .ts, .js, or .json to distinguish between files used to generate pages and those intended for browser execution. For instance, index.page.js generates the index.html page, while index.js is a JavaScript file executed by the browser.

Starting with Lume 3, the .page subextension is also applied to .jsx and .tsx files. This change allows the .jsx and .tsx extensions to be exclusively used for browser-side code (after processing with the esbuild plugin).

Lume 2:
- /index.jsx

Lume 3:
- /index.page.jsx

If you prefer the Lume 2 behavior (where this differentiation is not required), you can configure the plugin to remove the .page subextension:

site.use(jsx({
  pageSubExtension: "", // Reverts to Lume 2 behavior
}));

More info in the plugin documentation.

Improved Lume components

Async components

One of the main limitations of Lume 2's components was that they were synchronous. This was to support JSX components that were synchronous with React and Preact. With SSX, we don't have this limitation anymore, and all components are async.

For example, you can create a component in JSX that returns a promise:

// _components/salute.jsx

export default async function ({ id }) {
  const response = await fetch(`https://example.com/api?id=${id}`);
  const data = await response.json();
  return <strong>Hello {data.name}</strong>;
}

This component can be used in any other template engine, like JSX:

export default async function ({ comp }) {
  return (
    <p>
      <comp.Salute id="23" />
    </p>
  );
}

Or Vento:

<p>{{ comp.Salute({ id: 23}) }}</p>

Folder components

Lume components not only generate HTML code but can also export the CSS and JS code needed to run it on the browser. The code must be exported in the variables css and js. For example:

---
css: |
  .mainTitle {
    color: red;
  }
---

<h1 class="mainTitle">{{ name }}</h1>

The problem with this approach is the CSS and JS code is not treated as CSS and JS code by your code editor, so there's no syntax highlighting.

In Lume 3, it's possible to create a component in a folder, with the CSS and JS code in different files. To do that, you use the following structure:

|_ _components/
    |_ button/
        |_ comp.vto
        |_ style.css
        |_ script.js

Any folder containing a comp.* file will be loaded as a component using the folder name as the component name, and the style.css and script.js files will be loaded as the CSS and JS code for the component. This makes the creation of components more ergonomic, especially for cases with a lot of CSS and JS code.

Additionally, it's possible to add a script.ts file instead script.js to use TypeScript. Lume will compile it to JavaScript automatically.

Better interoperability

In Lume 2 components created with text-based engines, like Vento didn't work well for JSX templates. For example, let's say we have the following Vento component:

<button>{{ content }}</button>

and we want to use it in a JSX page:

export default function ({ comp }) {
  return <comp.Button>Click here</comp.Button>;
}

Due JSX escapes the string values, the output code is this:

<button>Click here</button>

To fix it, we need to create a container element with the dangerouslySetInnerHTML attribute:

export default function ({ comp }) {
  return (
    <div
      dangerouslySetInnerHTML={{
        __html: <comp.Button>Click here</comp.Button>,
      }}
    />
  );
}

In Lume 3, thanks to SSX this is no longer necessary. Components are fully interoperable and you can insert JSX components in Vento and viceversa. And to make them even more interchangeable, the content and children variables are equivalent.

export default function ({ comp }) {
  return (
    <>
      // This works
      <comp.Button>Click here</comp.Button>

      // This also works
      <comp.Button content="Click here" />
    </>
  );
}

Default data in components

In Lume 3, components can have extra data that will be used as default values. This data is like layout data but applied to components.

Let's see the following _components/title.vto component as an example :

---
title: Hello world
---

<h1>{{ title }}</h1>

Now you can use the component with the default title.

{{ await comp.title() }}
<!-- <h1>Hello world</h1> -->

Or with a custom title

{{ await comp.title({ title: "New title" }) }}
<!-- <h1>New title</h1>  -->

Global cssFile, jsFile and fontsFolder

As mentioned, Lume components can output CSS and JS code. However, some plugins output code too. For example, google_fonts generates the CSS code needed to load the fonts, prism and code_highlight export the CSS code with the themes, and katex (that didn't generate CSS code in Lume 2) now generates the CSS code automatically so you don't need to copy manually the CSS code.

Additionally, some plugins download also font files (specifically, google_fonts and katex).

In Lume 2, you have to configure how to export the generated code for every plugin individually. In Lume 3 there are three global options that will be used by default by all plugins and components:

const site = lume({
  cssFile: "/style.css", // default value
  jsFile: "/script.js", // default value
  fontsFolder: "/fonts", // default value
});

All extra code generated by components and the plugins code_highlight, google_fonts, prism, katex and unocss will be stored there.

Of course, you can still change the code destination for a specific plugin:

site.use(unocss({
  cssFile: "/unocss-styles.css",
}));

Tailwind 4

The tailwindcss plugin was upgraded to use Tailwind 4. The new version is faster than v3 and no longer needs Postcss to work. There are many changes in the configuration (especially the CSS-first configuration) so take a look at the upgrade guide if you want to upgrade your projects from v3 to v4.

// Lume 2
site.use(tailwindcss());
site.use(postcss());

// Lume 3
site.use(tailwindcss());
site.add("style.css");

If you don't want to upgrade to v4, it's still possible to continue using Tailwind 3 with the postcss plugin:

import tailwind from "npm:tailwindcss@^3.4";

site.use(
  postcss({
    plugins: [tailwind()],
  }),
);

More info in the plugin documentation.

Processors improvements

site.process() and site.preprocess() are among Lume's most used features. Lume 3 brings some improvements here to make them easier to use.

page.document no longer returns undefined

One of the many uses of processors is to manipulate HTML pages using the page.document property. But this property can return undefined if the page is not HTML or cannot be parsed, so you have to check the variable type before using it:

site.process([".html"], (pages) => {
  for (const page of pages) {
    const document = page.document;
    if (!document) {
      continue;
    }
    const title = document.querySelector("title");
  }
});

In Lume 3, page.document always returns a Document instance or throws an exception if the page cannot be parsed. This allows us to omit the type check:

site.process([".html"], (pages) => {
  for (const page of pages) {
    const title = page.document.querySelector("title");
  }
});

New page properties

The page.content variable containing the content of the page can be a string or a Uint8Array, depending on how this page has been loaded. For example, HTML, CSS or JS pages have the content as a string, but images or other binary files are loaded as Uint8Array.

To process these files in Lume 2 you have to check the content type:

site.process([".css"], (pages) => {
  for (const page of pages) {
    const content = page.content;

    if (typeof content === "string") {
      page.content = "/* © 2025 */" + content;
    }
  }
});

In Lume 3, pages have two new properties: page.text and page.bytes (inspired by the same properties of the Request object). As you may guess, page.text allows to work with the page content as strings, making the conversions automatic, and page.bytes does the same but for Uint8Array.

site.process([".css"], (pages) => {
  for (const page of pages) {
    page.text = "/* © 2025 */" + page.text;
  }
});

Omit * wildcard

In Lume 2, the * wildcard allows you to process all pages:

site.process("*", (pages) => {
  // Process all pages
});

In Lume 3, the first argument can be omitted:

site.process((pages) => {
  // Process all pages
});

The order of some plugins is now more important

In Lume 2, the order in which some plugins are registered doesn't matter. Let's see this example from the sitemap plugin:

site.use(sitemap()); // Generate the sitemap file
site.use(basePath()); // Add the base path to all URLs

The sitemap plugin is registered before basePath, so you may think the sitemap file is generated before adding the base path prefix to all URLs. But internally, the sitemap plugin is executed using the "beforeSave" event, which is triggered at the end, just before saving all files to the _site folder. So internally the basePath plugin is executed before.

This was designed so you don't have to think about the order of the plugins when using them. But this behavior has two problems:

• There are many plugins in which the order matters. For example, if you combine SASS and Postcss you have to process the SCSS files first and pass the result to Postcss. This inconsistency makes you wonder in which plugins the order is important or not.
• It's not possible to use a processor to modify the output of these plugins. For example, if you want to compress the sitemap file with brotli or gzip, is not possible because the sitemap will be always generated at the end.

To make Lume more transparent and intuitive, many plugins using events were changed to use processors, which respect the order in which they are registered in the _config.ts file.

The affected plugins are: code_highlight, decap_cms, favicon, feed, google_fonts, icons, prism, robots, sitemap, and slugify_urls.

To help with this transition, Lume 3 comes with a lint plugin that warns you when the order of some plugins is not correct.

esbuild uses esbuild-deno-loader to resolve dependencies

Deno is becoming a complicated runtime, especially for everything related to module resolution. It supports three completely different types of packages (HTTP, NPM, and JSR), with different behaviors, inconsistencies, and incompatibilities between them. In addition to the usual complexity of NPM, in Deno a package can be located in different places, depending on the variable nodeModulesDir, if the file package.json is found, if the node_modules folder exists, etc. JSR is not much better, because the resolution of a package depends on the combination of imports, exports, and patch keys in different deno.json and deno.jsonc files. And the addition of workspaces adds a new layer of complexity.

In Lume 2, the esbuild plugin delegates all this complexity to esm.sh, which transforms any NPM or JSR package to simple HTTP imports that are easier to manage. But this solution has its problems with multiple configuration options (deps, pin, alias, standalone, exports, etc) and there are many packages that don't work well after passing them through esm.sh.

In Lume 3 the esbuild plugin uses the esbuild-deno-loader plugin created by Luca Casonato, a member of the Deno team. This will make your bundled code more reliable and compatible with how Deno works.

basename improvements

In Lume 2, the basename variable allows changing the name of a file or directory. When missing, it's automatically defined by Lume using the page filename. For example, the page /posts/first-post.md has the basename first-post.

In Lume 3 this variable uses the final URL of the page, instead of the source filename. For example, if the /post/first-post.md page generates a different URL (say /post/other-name/) the basename is other-name.

Additionally, the basename no longer accepts "index" as a value. For example, the basename for the /post/hello-world/index.md is hello-world (the folder name) instead of index (the filename).

These changes will make this variable more consistent across all pages, no matter how the URL is generated. It's especially important for the nav plugin that uses this variable to sort pages alphabetically.

Date detection from filepath is disabled by default

Lume 2 detects automatically the date value from the files and folders paths and remove it. For example, the file /posts/2020-06-21_hello-world.md outputs the page /posts/hello-world/ (without the date).

Some people don't want this behavior and prefer to keep the date in the output URL. Following the Lume's philosophy of having a light core and provide extra features through plugins, this feature was removed from the core and the new extract_date plugin was created to enable it.

import lume from "lume/mod.ts";
import extractDate from "lume/plugins/extract_date.ts";

const site = lume();

site.use(extractDate());

export default site;

By default the plugin provides the same behavior of Lume 2, but it's possible to extract the date without removing it from the URL:

import lume from "lume/mod.ts";
import extractDate from "lume/plugins/extract_date.ts";

const site = lume();

site.use(extractDate({
  remove: false, // Keep the date
}));

export default site;

Removed plugins

In addition to jsx_preact, two more plugins were removed in Lume 3: liquid and on_demand.

Liquid lets you using LiquidJS as a template engine to build pages. The syntax is very similar to Nunjucks and the library is actively maintained but it has a big limitation: it's not possible to invoke functions. This makes this template engine useless in Lume because it's not possible to use helpers like search or nav to search pages or build the navigation. The plugin has been deprecated for a while, and it was removed in Lume 3.

The on_demand plugin was mainly an experiment to see if it was possible to add some dynamic behavior to Lume sites. But it never worked well, the implementation was a bit hacky to make it work on Deno Deploy, and it was too limited. Lume has the router for simple use cases, and for complex cases, maybe you have to use a different framework. The purpose of Lume never was to become into one-size-fits-all solution.

Removed some customization

The following removals aim to improve the stability and interoperability between plugins.

extensions option

In Lume 2, some plugins have the extensions option to configure which files you want to process. You rarely need to modify this option because Lume provides sensible defaults. For example, the default value for Postcss plugin is [".css"]:

site.use(postcss({
  extensions: [".css"], // <- You don't need this
}));

In most cases, this option doesn't make sense, because you can set any value but the plugin expects a specific format, like HTML pages to use DOM API or CSS code to process:

site.use(postcss({
  extensions: [".html"], // <- This breaks the build
}));

In Lume 3, this option was removed in many plugins:

• purgecss, postcss, and lightningcss always process .css files.
• sass always processes .scss and .sass files.
• svgo always processes .svg files.
• check_urls, base_path, relative_urls and modify_urls process .css and .html files.
• filter_pages processes all extensions.
• code_highlight, fff, inline, json_ld, katex, metas, multilanguage, og_images, and prism always process .html pages.

Name option

There are other plugins that register filters or helpers that you can use in your pages. In Lume 2 you could customize the name of these elements. For example, it's possible to use a different key to store the data for the metas plugin:

site.use(metas({
  name: "opengraph",
}));

Or the filter name of the date plugin:

site.use(date({
  name: "get_date",
}));

Changing the default name of the plugins have two problems:

• The types declared by the plugin don't change, so even if you change the key metas to opengraph, Lume.Data.metas still exist.
• This breaks the interoperability between plugins. For example, picture and transform_images depend on the same key name. If you change it for only one plugin, the other won't work.

In Lume 3, the name option was removed in the following plugins, so it's no longer possible to change it to something else: date, json_ld, metas, nav, paginate, picture, reading_info, search, transform_images, url and postcss.

Other options removed

• cache option in transform_images, favicon and og_images
• attribute option in inline.
• Components are always in the comp variable. The option to customize this variable name has been removed.

Most Lume users don't change these options, so most likely these removals don't affect your upgrade to Lume 3.

Other changes

Temporal API enabled by default

The Temporal proposal provides standard objects and functions for working with dates and times. It's being implemented in all browsers and it's supported by Deno with the unstable-temporal flag. Lume 2 uses a polyfill, but Lume 3 uses the Deno implementation, which requires to enable it in deno.json file:

{
  "unstable": ["temporal"]
}

Deno LTS support

As of version 3, Lume will support at least the most recent Deno LTS version (and probably some older versions too). Lume 3.0 supports Deno 2.1 and greater. More info about Deno LTS releases.

Removed automatic doctype

Lume 2 automatically added <!doctype html> to any HTML pages that were missing it. The original reason was because JSX doesn't allow adding this directive, so it was difficult to create HTML pages with only JSX. However, some users don't want this behavior because they create files with fragments of HTML. In Lume 3, it is possible to add the doctype directive in JSX (thanks to SSX) so this behavior is no longer needed and was removed.

More changes

As always, you can see the CHANGELOG.md file for a complete list of all changes with more details.

One last thing

While the development server is running, Lume 3 features a debug bar that provides valuable insights, including warnings and issues flagged by plugins.

The Lume debug bar can be extended easily by plugins or directly in the _config.ts. For example, let's create a simple tab to list all pages without title:

function createTab() {
  // Create a collection in the debug bar
  const collection = site.debugBar?.collection("Pages without title");

  // The debug bar is enabled if the collection was created
  if (collection) {
    collection.icon = "file";

    // Add items to the collection
    collection.items = site.pages
      .filter((page) => page.outputPath.endsWith(".html")) // Only HTML pages
      .filter((page) => !page.data.title) // No title
      .map((page) => ({
        title: page.data.url,
        actions: [
          {
            text: "Visit",
            href: page.data.url,
          },
        ],
      }));
  }
}

// Run this function after building and updating the site
site.addEventListener("afterBuild", createTab);
site.addEventListener("afterUpdate", createTab);

That's it! Our custom tab is now part of the Lume debug bar, and it has already identified two pages without titles!

The Lume debug bar is still an experimental feature, but it has been very well received since its introduction in our Discord community. Developers are already working on plugins to enhance the debug bar with features like HTML validator reports, accessibility checks, and SEO analysis.

Keep in mind that the debug bar is only visible when running Lume with deno task serve. It is not included in production builds. If you wish to disable this feature completely, you can do so by editing the _config.ts file:

const site = lume({
  server: {
    debugBar: false, // disable the debug bar
  },
});

Thanks!

All this work wouldn't be possible without the help from all people that contribute to Lume. Thanks to everyone that sponsor Lume or directly me. Thanks also to people that have been testing Lume 3 in the latest months or even using it in real projects, reporting bugs and providing feedback (specially Tim Post and Rick Cogley), and thanks to Pyrox for reviewing the grammar of this post.

New year and new Lume version! This time, I'd like to dedicate it to Pedro Días and Muño Vandilaz, who married on April 16, 1061, almost a thousand years ago. This is the first same-sex marriage documented in Galicia (and the rest of Spain).

The wedding took place in a small Catholic chapel. It's surprising to see how homophobic prejudices have changed since then. If you want to read more about this event take a look at this Qnews article (English) or gCiencia post (Galician).

New plugin json_ld

JSON-LD (JSON for Linking Data) is a way to provide structured data to web pages using JSON format, which is easier to parse and doesn't require to modify the HTML code. It's defined with a <script type="application/ld+json"> element containing the JSON code. For example:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "WebSite",
    "url": "https://oscarotero.com/",
    "headline": "Óscar Otero - Web designer and developer",
    "name": "Óscar Otero",
    "description": "I’m just a designer and web developer",
    "author": {
      "@type": "Person",
      "name": "Óscar Otero"
    }
  }
</script>

The json_ld plugin, created by Shuaixr, makes easier to work with this structured data. Edit your _config file to install it:

import lume from "lume/mod.ts";
import jsonLd from "lume/plugins/json_ld.ts";

const site = lume();
site.use(jsonLd());

export default site;

Then, you can create the jsonLd variable in your pages. For example:

jsonLd:
  "@type": WebSite
  url: /
  headline: Óscar Otero - Web designer and developer
  name: Óscar Otero
  description: I’m just a designer and web developer
  author:
    "@type": Person
    name: Óscar Otero

Note the following:

• The plugin automatically adds the @context property if it's missing
• URLs can omit the protocol and host. The plugin automatically resolves all URLs based on the location of the site.

Like with other similar plugins like metas, you can use field aliases:

title: Óscar Otero - Web designer and developer
header:
  title: Óscar Otero
  description: I’m just a designer and web developer

jsonLd:
  "@type": WebSite
  url: /
  headline: =title
  name: =header.title
  description: =header.description
  author:
    "@type": Person
    name: =header.title

TypeScript

If you want to use TypeScript, there's the Lume.Data["jsonLd"] type (powered by schema-dts package):

export const jsonLd: Lume.Data["jsonLd"] = {
  "@type": "WebSite",
  url: "/",
  headline: "Óscar Otero - Web designer and developer",
  description: "I’m just a designer and web developer",
  name: "Óscar Otero",
  author: {
    "@type": "Person",
    name: "Óscar Otero",
  },
};

More info in the plugin documentation page.

New plugin purgecss

PurgeCSS is a utility to remove unused CSS code, making your CSS files smaller to improve the site performance. The tool provides a Postcss plugin so, in theory, it can also be used in Lume. Now it has its own plugin (big thanks to into-the-v0id) which has some advantages:

• Scan generated HTML pages by Lume
• Scan bundled JS dependencies (bootstrap, etc)
• Only include CSS that is necessary (don't include drafts or conditional HTML that does not make it into the build)

import lume from "lume/mod.ts";
import purgecss from "lume/plugins/purgecss.ts";

const site = lume();
site.use(purgecss());

export default site;

Go to the plugin documentation page for more info.

New router middleware

Lume is a static site generator (and always will be). But sometimes you need some server-side logic to handle small things. For example, to handle the data a user sends from an HTML form, or maybe you need a small API to provide dynamic data.

For sites requiring front and back, you have great options like Fresh, Astro or Hono. But if you only need a couple of entry points, you may consider using something simpler like router middleware, which is a minimal router that works great with Lume's server.

import Server from "lume/core/server.ts";
import Router from "lume/middlewares/router.ts";

// Create the router
const router = new Router();

router.get("/hello/:name", ({ name }) => {
  return new Response(`Hello ${name}`);
});

// Create the server:
const server = new Server();

server.use(router.middleware());

server.start();

That's all. Now the /hello/laura request will return a Hello laura response!

The router uses the standard URLPattern under the hood that creates an object with all variables captured in the path and passes it as the first argument of the route handler.

In addition to the captured variables, you have the request property with the Request instance:

router.get("/search", ({ request }) => {
  const { searchParams } = new URL(request.url);

  const query = searchParams.get("query");
  return new Response(`Searching by ${query}`);
});

Note that to use this middleware in production, you need a hosting service running Deno like Deno Deploy or similar.

New plaintext plugin

Sometimes you have your content in Markdown or HTML, but also need a plain text version. Let's see the following example:

---
title: Welcome to **my site**
---
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title }}</title>
  </head>

  <body>
    <h1>{{ title |> md(true) }}</h1>
  </body>
</html>

The title variable uses Markdown syntax to render Welcome to <strong>my site</strong>. But this also affects the <title> element of the page which contains the asterisks.

The new plaintext plugin registers the plaintext filter, that not only removes any Markdown and HTML syntax but also linebreaks and extra spaces:

---
title: Welcome to **my site**
---
<!DOCTYPE html>
<html>
  <head>
    <title>{{ title |> plaintext }}</title>
  </head>

  <body>
    <h1>{{ title |> md(true) }}</h1>
  </body>
</html>

The plugin is disabled by default so you need to import it to your _config.ts file:

import lume from "lume/mod.ts";
import plaintext from "lume/plugins/plaintext.ts";

const site = lume();
site.use(plaintext());

export default site;

More info in the plugin documentation page.

Better control of the generated CSS code

Some plugins like google_fonts, prism or code_highlight can generate CSS code. The way this code is generated is different for each plugin.

Google Fonts plugin has the cssFile option to configure the filename to output the CSS code. If the css file doesn't exist, it's created. If it already exists, the code is appended at the end. You can use the placeholder option to insert the code at some point in the middle of the file.

site.use(googleFonts({
  cssFile: "styles.css",
  placeholder: "/* insert-google-fonts-here */",
  // ...more options
}));

Prism and Code Highlight plugins output the theme's CSS code differently. The theme option has the path property but it's not the output css file but the source file:

site.use(prism({
  theme: {
    name: "funky",
    path: "/_includes/css/code_theme.css",
  },
}));

This means that if you set the path as /_includes/css/code_theme.css, this file must be imported somewhere in your CSS code in order to be visible:

@import "css/code_theme.css";

The problem with this approach is it requires two steps: first, configure the source file name in the plugin, and then import the file in your CSS file (or copy it with site.copy()).

The Google fonts approach is more straightforward.

In order to make Lume more consistent across all plugins, I want to unify the way the CSS code is generated everywhere. That's why the theme.path option of Prism and Code Highlight plugins are now deprecated and the new theme.cssFile and theme.placeholder options were added.

site.use(prism({
  theme: {
    name: "funky",
    cssFile: "styles.css",
    placeholder: "/* prism-theme-here */",
  },
}));

This change is also aligned with the components.placeholder option introduced in Lume 2.4.

Other changes

• Added subset options to Google fonts plugin.
• Added ui.globalVariable option to Pagefind plugin to store the pagefind instance in a global variable for future manipulation.
• Hot reload inline script includes the integrity hash, to avoid CSP issues.
• Files with extension .d.ts are ignored by Lume, to avoid generating empty files.
• Updated the default browser versions supported by LightningCSS plugin.

See the CHANGELOG.md file to see a list of all changes with more detail.

This new version of Lume is dedicated to Maruja Mallo, an extraordinary surrealist painter born in Galicia in 1902 who gained international fame. Learn more about Maruja.

New plugin: check_urls

Broken links are one of the biggest issues on the Web. A recent study detected that 27.6% of the top 10 million sites are dead. And for those sites that are still alive, they are likely to change the URLs at some point, after a redesign or content updates, causing a lot of broken links.

The new plugin check_urls will help you to keep your links healthy, by checking all links in your website (not only to HTML pages but also files like images, JavaScript or CSS). This plugin already existed for some time as experimental plugin thanks to iacore, but it was moved to the main Lume repo and was improved with additional features.

The basic way to use it is like any other plugin. No big surprises here!

import lume from "lume/mod.ts";
import checkUrls from "lume/plugins/check_urls.ts";

const site = lume();
site.use(checkUrls());

export default site;

The default configuration will check all your internal links and warns you when a broken link is found. This plugin is compatible with redirects: when a link to a non-existing page is found, but it redirects to an existing page, the url is valid.

Strict mode

There's a mode for a more strict detection:

site.use(checkUrls({
  strict: true,
}));

In the strict mode the redirects are not allowed, all links must go to the final page. This also affects to the trailing slashes: for example /about-me is invalid but /about-me/ is valid.

External URLs

By default, the plugin only checks internal links. But you can configure it to check links to external domains:

site.use(checkUrls({
  external: true,
}));

Learn more about this plugin in the documentation page.

New plugin: icons

Nowadays, most websites are using icons to a greater or lesser extent. The icons plugin allows to use some of the most popular SVG icon libraries. The installation can't be easier:

import lume from "lume/mod.ts";
import icons from "lume/plugins/icons.ts";

const site = lume();
site.use(icons());

export default site;

To import an icon, just use the icon filter which returns the path of the icon's svg file.

<img src="{{ "acorn" |> icon("phosphor") }}">

Lume will download the "acorn" icon from the popular Phosphor library into /icons/phosphor/acorn.svg (the output folder is configurable) and return the path.

Some icons have different variations that you can configure with the name:variation syntax:

<img src="{{ "acorn:duotone" |> icon("phosphor") }}">

Alternatively, you can set the variation in the second argument of the filter:

<img src="{{ "acorn" |> icon("phosphor", "duotone") }}">

You can use inline plugin to inline the SVG code in the HTML.

<img src="{{ "acorn" |> icon("phosphor") }}" inline>

The icon plugin supports the following icon collections and it's easily extensible with more.

• Ant
• Bootstrap
• Boxicons
• Fluent
• Heroicons
• Iconoir
• Lucide
• Material Icons
• Material Symbols
• Mingcute
• Myna
• Octicons
• Openmoji
• Phosphor
• Remix icons
• Sargam
• Simpleicons
• Tabler

Learn more about this plugin in the documentation page.

New plugin google_fonts

Another common asset used to build sites is webfonts. Google Fonts is a fantastic resource for open source fonts, but loading the fonts from the Google Fonts CDN is not the best option, not only for privacy and GDPR compliance, but also for performance.

The google_fonts plugin downloads the optimized font files from Google fonts automatically into the /fonts directory (configurable) and generates the /fonts.css file (also configurable) with the @font-face declarations.

To use it, just register the plugin passing the sharing URL of your font selection. For example, let's say we want to use Playfair Display:

import lume from "lume/mod.ts";
import googleFonts from "lume/plugins/google_fonts.ts";

const site = lume();

site.use(googleFonts({
  fonts:
    "https://fonts.google.com/share?selection.family=Playfair+Display:ital,wght@0,400..900;1,400..900",
}));

export default site;

It's possible to rename the fonts, useful if you want to change a font without changing the code:

site.use(googleFonts({
  fonts: {
    display: "https://fonts.google.com/share?selection.family=Playfair+Display:ital,wght@0,400..900;1,400..900",
    text: "https://fonts.google.com/share?selection.family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900"
}));

In the example above, the Playfair Display font is renamed to "display" and Roboto to "text", so this allows the use of the fonts in the CSS code with these names:

h1 {
  font-family: display;
}
body {
  font-family: text;
}

Go to the documentation page to learn more about the Google Fonts plugin!

New plugins brotli and gzip

Thanks to Into the V0id for adding these two plugins to Lume. They are useful for compressing text-based files (like HTML, JavaScript, SVG, or CSS files) using the Gzip and Brotli algorithms and output files with the same name but with .gz or .br extensions. For example, in addition to the /index.html page, the plugins generate also /index.html.gz (for Gzip) and /index.html.br (for Brotli).

I think it's not necessary to show how to activate the plugin, but just to demonstrate how predictable and "boring" Lume is:

import lume from "lume/mod.ts";
import brotli from "lume/plugins/brotli.ts";

const site = lume();

site.use(brotli());

export default site;

New precompress middleware

brotli and gzip plugins can be combined with the new precompress middleware if you're using Lume server to serve your static files (for example in Deno Deploy). This middleware checks the Accept-Encoding header and if the browser accepts br or gzip values, it will serve the precompressed file.

import Server from "lume/core/server.ts";
import precompress from "lume/middlewares/precompress.ts";

const server = new Server();

server.use(precompress());

server.start();

Learn more about these plugins in the brotli and gzip documentation pages.

modify_urls supports CSS files

The modify_urls plugin now can search and modify urls in CSS files. This is not important only for this plugin but also for other plugins that use modify_urls under the hood, like base_path and relative_urls.

Example with base_path

base_path is one of Lume's most useful plugins because it adds a prefix to all absolute URLs of your site. This is important if your site is hosted in a subdirectory.

For example, let's say you want to host your blog in the location https://my-site.com/blog/ and you have this HTML code:

<a href="/posts/hello-world/">Hello world</a>

The plugin automatically fixes the URL to add the /blog/ prefix:

<a href="/blog/posts/hello-world/">Hello world</a>

Until now, the plugin only transformed URLs in HTML pages. If your site has this CSS code:

.background {
  background-image: url("/img/bg.png");
}

The background image will fail because the /blog/ prefix is missing. As of Lume 2.4.0, this plugin can transform also CSS files. This option is disabled by default, it requires to configure it in the _config.ts file:

site.use(basePath({
  extensions: [".html", ".css"],
}));

Now not only HTML pages but also CSS files will be processed:

.background {
  background-image: url("/blog/img/bg.png");
}

Fallbacks for metas and feed plugins

Some plugins like metas and feed allow to define aliases to other variables. For example, if we want to use the variable title inside metas.title:

title: Page title
metas:
  title: =title

As of Lume 1.4, it's possible to define fallbacks to other variables or provide a default variable:

metas:
  title: =title || =header.title || Default title

In this example, the title used in metas is the title variable. If it's not defined, the header.title variable is used. And if it's doesn't exist, the string "Default title" will be used.

Support for author in feed plugin

In addition to fallbacks, the feed plugin has added support for the author name and author URL variables:

site.use(feed({
  output: ["/posts.rss", "/posts.json"],
  query: "type=post",
  info: {
    title: "=site.title",
    description: "=site.description",
    authorName: "=site.author.name",
    authorUrl: "=site.author.url",
  },
  items: {
    title: "=title",
    description: "=excerpt",
    authorName: "=author.name",
    authorUrl: "=author.url",
  },
}));

Other changes

• Several improvements to esbuild plugin by Into the V0id.
• Added the new variable fediverse to the metas plugin, to generate the <meta name="fediverse:creator" content="..."> tag added to Mastodon.
• Fixed some bugs related to Windows support and CJK characters.
• New option placeholder in the unocss plugin to insert the generated code in a specific place.
• New option placeholder in the components configuration to insert the generated CSS and JavaScript code in a specific place.
• Updated all dependencies to their latest version.

And more changes. See the CHANGELOG file for more details.

Happy Luming!

TL/DR

If you are using the nav plugin, see this.

New function parseBasename

When Lume loads a page file, the basename (the filename after removing the extension) is parsed to extract additional data. This feature makes it possible that, for instance, if the basename starts with yyyy-mm-dd_*, Lume extracts this value to set the page date, and remove it from the final name, so the file /2020-06-21_hello-world.md generates the page /hello-world/.

As of Lume 2.3.0, you can add additional parsers with the new function site.parseBasename.

Let's say we want to use a variable named order to sort pages in a menu, and we want to extract this value from the file name. For example the file /12.hello-world.md outputs the page /hello-world/ and sets 12 as the order variable. We can achieve this with the following function:

site.parseBasename((basename) => {
  // Regexp to detect the order pattern
  const match = basename.match(/(\d+)\.(.+)/);

  if (match) {
    const [, order, basename] = match;

    // Return the order value and the new basename without the prefix
    return {
      order: parseInt(order),
      basename,
    };
  }
});

As you can see, the function is simple: it receives the basename and return an object with the parsed values. Note that the returned object contains the basename without the prefix, in order to be removed from the final URL.

See more info in the documentation page.

Restart after modifying the _config.ts and _cms.ts files

Until now, if you modify the _config.ts file during the server mode, you must stop the process and start it again to see the changes. This is very inconvenient, especially in the early phases of development, when you may want to try different plugins or make changes to the Lume configuration.

From now on, the building process is run inside a Worker. This change allows us to stop the build and restart it again without stopping the main process (under the hood, it is done by closing the Worker and creating a new one).

For now, the rebuild is triggered every time a change in the _config file is detected. In the next versions, we can add additional triggers.

In CMS mode (with deno task cms), the process is also restarted if the _cms.ts file is modified, which is useful when you are configuring the documents and collections.

New sorting methods asc-locale and desc-locale

When searching pages using the search helper, you can sort them by any field, for example, the title:

const pages = search.pages("type=post", "title=asc");

Under the hood, Lume sorts the pages with array sort using basic comparison operators (> and <):

pages.sort((a, b) => a == 0 ? 0 : a.title > b.title ? 1 : -1);

This works fine in many cases, but not when you have strings with accents, different cases, etc. In these cases localeCompare works much better. In this version, we have introduced two new locale methods: asc-locale and desc-locale. So the previous example can be improved with:

const pages = search.pages("type=post", "title=asc-locale");

New plugin SRI

SRI (Subresource Integrity) is a browser feature to protect your site and your users from compromised code loaded from external CDN. It verifies the code loaded by the browser is exactly the same code that you got during the build process, without unexpected manipulations. You can learn more about SRI in the MDN article.

Lume had an experimental SRI plugin that has been moved to the main repo, so now it's part of the official plugins collection:

import lume from "lume/mod.ts";
import sri from "lume/plugins/sri.ts";

const site = lume();
site.use(sri());

export default site;

The plugin searches for <script> and <link rel="stylesheet"> elements in your pages that load resources from other domains and add the integrity and crossorigin attributes automatically. For example, if you have this code:

<script src="https://code.jquery.com/jquery-3.7.0.slim.min.js"></script>

The plugin outputs the following:

<script
  src="https://code.jquery.com/jquery-3.7.0.slim.min.js"
  integrity="sha256-tG5mcZUtJsZvyKAxYLVXrmjKBVLd6VpVccqz/r4ypFE="
  crossorigin="anonymous"
></script>

See more info in the plugin documentation page.

nav plugin changes

The nav plugin is useful for creating menus at multiple levels.

BREAKING CHANGE: Changed the tree data interface

The nav.menu() function returns an object tree using the pages' URL. Every object in the tree is a page or a directory and in previous Lume versions, it could have the following properties:

• item.slug The name of the page or folder.
• item.data If the element is a page, this is the data object of the page. If it's a folder, this value is undefined.
• item.children An array of sub-pages and sub-folders.

These properties didn't fit well to order the elements, especially the sub-folder items. In the new structure, the slug property has been removed (Edit: it was restored in Lume 2.3.1 due some bugs) and this value is stored in data.basename.

This change affects to how this tree is iterated in your template. For instance, if in Lume 2.2 we have the following code:

if (item.data) {
  // item.data exists, it's a page
  return `<a href="{{ item.data.url }}">{{ item.data.title }}</a>`;
} else {
  // It's a folder
  return `<strong>{{ item.slug }}</strong>`;
}

With the changes in Lume 2.3, the code must be changed to:

if (item.data.url) {
  // item.data.url exists, it's a page
  return `<a href="{{ item.data.url }}">{{ item.data.title }}</a>`;
} else {
  // It's a folder
  return `<strong>{{ item.slug }}</strong>`;
}

Now both pages and folder items store the basename in the same place (data.basename), and it's easy to sort the elements alphabetically:

const menu = nav.menu("/", "", "basename=asc");

And even use the new locale sorting methods:

const menu = nav.menu("/", "", "basename=asc-locale");

Added functions to get the next and previous pages

In this version the functions nav.nextPage() and navPreviousPage() have been added, to ease the navigation to the next and previous pages.

For example, let's say we have created the following tree structure with the function nav.menu():

docs
  |__ getting-started
        |__ installation
        |__ configuration
  |__ plugins
        |__ prettier

The new function nav.nextPage returns the next page relative to the provided URL. For example:

const nextPage = nav.nextPage("/docs/getting-started/installation/");
console.log(nextPage.url); // /docs/getting-started/configuration/

If the page is the last sibling of the current section, it returns the first page of the next section:

const nextPage = nav.nextPage("/docs/getting-started/configuration/");
console.log(nextPage.url); // /docs/plugins/

If the current section has children, it returns the first child:

const nextPage = nav.nextPage("/docs/plugins/");
console.log(nextPage.url); // /docs/plugins/prettier/

The nav.previousPage() works similarly but in reverse order.

Other changes

• Plugins and middlewares can be imported using named imports, in addition to the default exports:

  import basePath from "lume/plugins/base_path.ts";
  // it's the same as
  import { basePath } from "lume/plugins/base_path.ts";
  

• Several bug fixes and improvements have made to the watcher and live reload.

And there are many more changes that you can see in the CHANGELOG file.

TL/DR

Cases requiring some manual changes after updating to Lume 2.2:

• If you have a _cache folder in your src directory, see this.
• If you importing LumeCMS from /lume/cms.ts, see this.

Esbuild improvements

The Esbuild plugin got the following improvements:

• JSR support: Now you can use jsr: specifiers in your code. They are handled using esm.sh (the same as npm: specifiers).

• Fixed npm: resolution. In previous versions, importing a bare specifier mapped to npm: like the following would fail:

  {
    "imports": {
      "bar": "npm:bar"
    }
  }
  

  import foo from "bar";
  

  This has been fixed and it works fine now.

• Using esbuild without bundler: Let's say you want to compile the following code with the bundle option to false:

  import foo from "./bar.ts";
  

  Esbuild converts bar.ts to bar.js, but it doesn't change the file extension in the import. The Lume plugin tries to fix this. More info.

CMS import changes

LumeCMS is a simple CMS to manage the content of the sites. To configure it, you have to create the _cms.ts file and import the CMS from the lume/cms.ts specifier:

import lumeCMS from "lume/cms.ts";

const cms = lumeCMS();

// Configuration here

export default cms;

The file lume/cms.ts, provided by Lume, exports everything you need from LumeCMS. But this has also the following issues:

• Lume and LumeCMS have different update paces. It's not easy to update LumeCMS if it's coupled to Lume.
• Providing everything in a single file makes Deno download all LumeCMS modules even those that you don't need. For example, GitHub storage has some NPM dependencies like Octokit that you may not need.

The best way to import LumeCMS is using the import map. This is something that the init script has been doing for a while. For example:

{
  "imports": {
    "lume/": "https://deno.land/x/lume@v2.2.0/",
    "lume/cms/": "https://cdn.jsdelivr.net/gh/lumeland/cms@0.4.1/"
  }
}

import lumeCMS from "lume/cms/mod.ts";

const cms = lumeCMS();

// Configuration here

export default cms;

This allows you to import only the specific modules of Lume that you need and update LumeCMS at your own pace.

I know this is a BREAKING CHANGE and sorry for that 🙏. But I believe the current situation wasn't easy to maintain.

New middleware shutdown

If you have a site on Deno Deploy that you want to shut down for reasons, this new middleware can be useful:

• All HTML requests will return the content of the /503.html page with the 503 status code.
• It also sends the Retry-After header with the default value of 24 hours (customizable).

import Server from "lume/core/server.ts";
import shutdown from "lume/middlewares/shutdown.ts";

const server = new Server();
server.use(shutdown());

server.start();

New theme option for Prism and Highlight.js

The plugins prism and code_highlight highlight the syntax of your code automatically using the libraries Prism and Highlight.js respectively. These libraries provide some nice premade themes that you can use but need to be loaded manually.

A new option theme was introduced to ease this step, so the themes are downloaded automatically. The option works the same for both plugins, this is an example with prism:

site.use(prism({
  theme: {
    name: "funky",
    path: "_includes/css/code_theme.css",
  },
}));

The CSS file for the Funky theme is downloaded automatically (using remoteFile under the hood) with the local path _includes/css/code_theme.css so you can import it in your CSS file with:

@import "css/code_theme.css";

site.use(prism({
  theme: {
    name: "funky",
    path: "/css/code_theme.css",
  },
}));

// Copy the file
site.copy("/css/code_theme.css");

Extra meta tags

The metas plugin allows to include custom meta tags. Useful to insert metas like twitter:label1, twitter:data1, etc.

In addition to the regular values, the metas object accepts additional values that are treated as custom meta tags. Example:

title: Lume is awesome
author: Dark Vader
metas:
  title: =title
  "twitter:label1": Reading time
  "twitter:data1": 1 minute
  "twitter:label2": Written by
  "twitter:data1": =author

This configuration generates the following code:

<meta name="title" content="Lume is awesome" />
<meta name="twitter:label1" content="Reading time" />
<meta name="twitter:data1" content="1 minute" />
<meta name="twitter:label2" content="Written by" />
<meta name="twitter:data2" content="Dark Vader" />

Feed plugin accepts images

The feed plugin has been extended with the new image key that allows one to place an image per item. For example:

site.use(feed({
  output: "/feed.xml",
  query: "type=articles",
  items: {
    title: "=title",
    description: "=excerpt",
    image: "=cover",
  },
}));

Liquid deprecation

Liquid plugin allows to use Liquidjs library as a template engine in Lume.

Liquidjs is a great library but it has a limitation incompatible with Lume: it's not possible to invoke functions. This is very unfortunate because it's not possible to use the search helper inside a liquid template to loop through the pages. For example, the following code doesn't work:

<ul>
  {% for item in search.pages('post') %}
  <li>{{item.title}}</li>
  {% endfor %}
</ul>

Lume has support for Nunjucks which is a good replacement because has a very similar syntax to Liquid and allows you to run functions, so I decided to deprecate the Liquid plugin and recommend Nunjucks instead. It will still be available in Lume 2 but probably be removed in Lume 3 (in the distant future).

_cache folder relative to root directory

The _cache folder is created by some plugins like transform_images in the source folder. For example, if your source folder is ./src/ the cache folder is ./src/_cache/.

As of Lume 2.2.0, this folder is created in the root directory (the same directory where the _config.ts file is). This makes its location more predictable, especially to add it to .gitignore.

After updating Lume, if you are using a subdirectory as the source folder, the _cache folder should be moved to the root.

Removed nesting plugin in PostCSS

The postcss plugin comes with the plugins postcss-nesting and autoprefixer enabled by default.

CSS nesting is now available in all browsers and this plugin is no longer needed, so it's no longer enabled by default in Lume.

If you still want to use it, you have to import it in the _config.ts file:

import lume from "lume/mod.ts";
import postcss from "lume/plugins/postcss.ts";
import nesting from "npm:postcss-nesting";

const site = lume();

site.use(postcss({
  plugins: [nesting()],
}));

export default site;

And there are many more changes that you can see in the CHANGELOG file.