URLs

As explained in Page files, the output filename is generated using the original source file path:

posts/my-first-post.md  =>  /posts/my-first-post/index.html

By default, the pages are saved as "pretty URLs", using directories for the path and a index.html file. So the final URL is /posts/my-first-post/. To disable this behaviour, set the option prettyUrls to false in your _config.js file (see Configuration).

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

/posts/my-first-post.md  =>  /posts/my-first-post.html

The url variable

The variable url defined in a page allows customizing the output file individually. For example:

---
title: My first post
url: /posts/welcome/
---

In this example, the url value changes the output file name:

/posts/my-first-post.md  =>  /posts/welcome/index.html

Note that manually defining the URL of a page means that the prettyUrls option won't have any effect. For example:

# Use a trailing / to create pretty urls.
# For example, this outputs /posts/welcome/index.html
url: /posts/welcome/

# This outputs /posts/welcome (a file without extension)
url: /posts/welcome

# This outputs /posts/welcome.html
url: /posts/welcome.html

Relative URLs

If you only want to change the last part of the URL, you can use relative paths. For example:

---
title: My first post
url: ./welcome/
---

In this example, the page will be saved using the directory path where the source file is saved but adding welcome in the last part of the URL.

/posts/my-first-post.md  =>  /posts/welcome/index.html

Using ../welcome/ as URL will also remove the last directory.

/posts/my-first-post.md  =>  /welcome/index.html

URLs as functions

The variable url also accepts a function to generate the final value dynamically. This function has the current page object as the first argument.

For example, let's say that we want to automatically generate all URLs of our posts using the title value. We can create a _data.js file in the /posts/ directory with the following code:

export function url(page) {
  return `./${page.data.title}/`;
}

Now, all pages in this directory share the same url function. The function returns the title of the page as a relative URL, for example ,./My first post/ (See Shared data).

Because the URL is relative, the current directory is appended automatically (it will be resolved to /post/My first post/). And if you are using the slugify_urls plugin, all output paths are slugified automatically, so the final URL would be /post/my-first-post/.

Using functions as URLs gives a lot of flexibility to generate the URLs as you want.

Setting url to false

Setting the url variable to false prevents the page being processed by Lume.

---
title: This is a title
url: false # Ignore this page for now
---

Basename

As of Lume v2, the new variable basename is introduced to better customize the URL generation. It's a special value affecting to the page or directory where it's defined, and allows to change how the name of the file/directory is reflected to the final URL.

If the basename is defined in a _data.* file, it affects to the directory where the _data file is. For example, let's say we have the following file:

/blog/posts/hello-world.md

This file is exported with the URL /blog/posts/hello-world/. If we want to replace the part /posts/ to /articles/, we can create a _data.yml file in the /blog/posts folder with the following code:

basename: articles

Now, this folder will use the name articles for the URL generation, so the final URL of the file is /blog/articles/hello-world/.

You can set the basename variable to empty to don't use the folder name in the final URL:

basename: ""

The final URL of the file is now /blog/hello-word/, the /post/ part was removed. You can also remove the previous folder with:

basename: "../"

The final URL of the file is now /hello-world/.