Basename parsers

When Lume is scanning the source folder, it can automatically extract some info from the name of files and folders.

For example, let's say we have the variable order to sort pages in a menu.

---
title: Page title
order: 2
---

This is the second page!

A way to make this variable explicit is prepend its value to the filename:

├── 1.welcome.md
├── 2.introduction.md
├── 3.the-basics.md
└── 4.advanced.md

One of the advantages of making this variable explicit in the filesystem is that you can see the source files sorted the same way in your editor as well as on the final site.

In Lume, the filename is used by default to generate the final URLs (more info), so the page files above generates the following URLs:

/1.welcome/
/2.introduction/
/3.the-basics/
/4.advanced/

That works but it's ugly and if you decide to change the order of a page, you have to remember to change it in two places (the front matter and the filename). And this change affects also to the URL of the pages, that can create broken links. What we really want is to use the value from the filename to set it in the front matter. To do that, we can register a basename parser using the function site.parseBasename in our _config.ts file:

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,
    };
  }
});

The function receives the basename (the name of the file without the extension) and, if the regular expression matches, it returns an object with the parsed values. Note that the returned object contains the basename key with the original basename but without the prefix, that will be used to generate the final URL.

If the basename doesn't match the regular expression, it doesn't return anything, so nothing will be changed.

The parseBasename function is used for both files and folders. This allows extracting values from a folder name and storing them as shared data, so they are available to all pages inside.

Lume has some plugins that use parseBasename under the hood to extract dates and extract orders (the same example explained here).

Cascade behavior

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,
    }
  }
})