The _config file

The configuration file is the _config.ts or _config.js file saved in the project's root directory. If you don't have it yet, see the installation documentation to learn how to create it.

The minimal required code is:

import lume from "lume/mod.ts";

const site = lume();

export default site;

The lume() function creates an instance of Lume and exports it. This function accepts an object with the following configuration values:

Basic options

src

This is the directory containing the source files of your site. All files used to build your site must be here. Files and folders outside this directory will be ignored by Lume. The path is relative to cwd and by default is . (the same directory), but some people prefer to store the source files in a subfolder like src.

const site = lume({
  src: "./src",
});

dest

The path where the site is exported to. It's relative to cwd and by default is _site.

const site = lume({
  dest: "./dist",
});

emptyDest

By default, Lume will empty the dest folder before the build. You can prevent this by setting this option to false:

const site = lume({
  emptyDest: false,
});

This is useful if you want to combine two or more sites into the same folder. Other use case is for very big sites (with more than 100K pages) that may need to be built in several steps to prevent running out of memory.

location

This is the public URL of the site. It's useful to generate absolute URLs or fix the paths if your site is published under a subdirectory, for example: https://example.com/project-name/. It only accepts an URL object, for example:

const site = lume({
  location: new URL("https://example.com"),
});

prettyUrls

This option is enabled by default to generate pretty URLs, for example /about-us/ instead of /about-us.html. Set false to disable it.

const site = lume({
  prettyUrls: false, // Disable pretty urls
});

cssFile

Lume components and some plugins (like katex, prism, or google fonts) can generate CSS code. This option allows to configure globally the filename used to output that code.

const site = lume({
  cssFile: "/style.css", // This is the default value
});

jsFile

Lume components can generate JavaScript code. This option allows to configure globally the filename used to output that code.

const site = lume({
  jsFile: "/script.js", // This is the default value
});

fontsFolder

Some plugins like Google Fonts or Katex can output font files. This option allows to configure globally the folder where these files are saved.

const site = lume({
  fontsFolder: "/fonts", // This is the default value
});

caseSensitiveUrls

Lume prevents saving two pages with the same URL. By default pages with the same name but different case are considered the same page, for example /about-us/ and /About-Us/. This behavior matches Windows and MacOS' file systems, which are case insensitive. You can set this option to true to make it case sensitive, so both pages would be considered different. Note that this behavior is only compatible with Linux.

includes

It's a special folder used by default by the template engines and some plugins (like sass or postcss) to look for the included files. By default it's _includes and this path is relative to the src folder.

As an example, if the src folder is ./src and the includes folder is configured to _includes, Lume will look for the included files inside ./src/_includes/.

Server options

The server key contains the configuration for the local server. It has the following options:

root

Set the root folder for the server. It's relative to the dest folder and by default it's . (the same directory). The only use case in which you may want to change this is if your dest folder is, for example _site/blog and you want to expose the blog folder when serving the site because all urls start with /blog/.

port

By default, the local server uses the port 3000. Use this option to set a different port.

const site = lume({
  server: {
    port: 8000,
  },
});

page404

This option allows configuring the HTML page displayed for 404 errors. By default it is /404.html. If you are building a SPA with dynamic URLs, you may want to change it to /index.html.

open

Set true to automatically open the generated site in your default web browser after starting the local web server.

const site = lume({
  server: {
    open: true,
  },
});

middlewares

Use this option to add middlewares to the local web server. There are some common utilities available at lume/middlewares/*, but you can create custom middlewares easily. More info in the Server documentation.

import expires from "lume/middlewares/expires.ts";

const site = lume({
  server: {
    middlewares: [
      expires(),
    ],
  },
});

debugBar

The debug bar is a development toolbar that appears in your site while the dev server is running. Use this option to disable it.

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

Watcher options

The watcher key contains an object to configure the file watcher, used to watch file changes with lume --serve and lume --watch.

• debounce: The debounce interval (in milliseconds). By default is 100.
• ignore: An array of strings or functions to filter paths ignored by the watcher.
• dependencies: An object to manually map file dependencies. If the watcher detects that a dependency has changed, the dependent file will be considered as changed too.

const site = lume({
  watcher: {
    debounce: 10,
    ignore: [
      "./ignored-folder/",
      "./ignored-file.txt",
      (path) => path.endsWith(".foo"), // ignore extension
    ],
    dependencies: {
      // If dep-1.ts or dep-2.ts change, _data.js is reloaded too.
      "_data.js": ["dep-1.ts", "dep-2.ts"],
    },
  },
});

Components options

The components object allows to configure the output files of Lume components.

• cssFile: The file name to export the CSS code of the components.
• jsFile: The file name to export the JS code of the components.
• placeholder: A string used as placeholder to replace the content with the css or js code.

import lume from "lume/mod.ts";

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

export default site;