🔥 Updates

Lume 1.19.0 release notes

Mon, 25 Sep 2023 18:25:59 GMT

Lume 1.19.0 was released! Hopefully, it will be the last minor version of 1.x before the incoming Lume 2. This is a summary of the changes and new features.

Favicon plugin

The favicon is a common task we have to do every time we build a new website. It's not as easy as should be because there are different formats, sizes, resolutions, etc. The new favicon plugin was created to make it more simple.

You only have to specify an input file (by default favicon.svg) and the plugin automatically creates the files /favicon.ico, /favicon-16.png, /favicon-32.png and /apple-touch-icon.png and adds the elements needed in all HTML pages.

As any other Lume plugin, the installation can't be easier: just import the plugin and use it:

import lume from "lume/mod.ts";
        import favicon from "lume/plugins/favicon.ts";
        
        const site = lume();
        site.use(favicon());
        
        export default site;

See the favicon plugin documentation.

Reading info plugin

This plugin was created by Jrson and available in the experimental plugins repo since a time ago, under the name reading_time. It's a simple plugin to calculate the time required to read the content of a page.

Due the plugin is being used in several projects (among them, this blog), it was moved to Lume repo and renamed to reading_info. The reason of the new name is the plugin not only returns the time, but also other interesting info like the number of words. Maybe we can include more interesting info in the future, let me know your suggestions.

It uses the Int.Segmenter standard function to count the words, using the page variable lang to detect the language. The data is stored in the variable readingInfo, so you can use it in your templates in this way:

{{ title }}
        {{ readingInfo.words }} words / {{ readingInfo.minutes }} min read

See the reading_info plugin documentation

Improved the `picture` plugin

The picture plugin has received many improvements and bug fixes. The most notable:

Changed the `src` value of the original `img` element

In previous versions, the src value of the img element referred to the original image. But this image isn't always exported so it returns a 404 error. As of Lume 1.19, the last source element will be used as the value for the img:

Formats sorted automatically

In the previous version, the source elements were created in the same order as defined in the imagick attribute. For example:

This outputs the source elements in the same order (jpg, webp and avif):

Because jpg is a format widely supported, it will be choosen by all browsers because it's the first in the list, even if better formats like webp or avif are there. As of Lume 1.19 the formats are sorted automatically. By default the order is: jxl, avif, webp, png, jpg (from the most modern to the most supported). So the new output is:

Allow to define only formats

From now on, the imagick attribute can have only formats, sizes are no longer mandatory. It's useful if you don't want to resize the image, just provide different formats:

Don't create a new picture just for one source

If the image has only one format, no picture element will be created:

Support for `size` attribute

The plugin now supports the size attribute:

New functions to `site` instance

mergeKey

Lume allows to customize the way some keys are merged with the variable mergedKeys. You can see a detailed explanation of this feature in the documentation.

The function site.mergeKey() allows to define this value in the _config.ts file, which is more useful specially for plugins that register new merge strategies for some keys automatically.

For example, let's say you want to merge the keys categories using the stringArray strategy:

site.mergeKey("categories", "stringArray");

page

The site.page() function allows to create new pages dynamically from the _config.ts file, without having a page file in the disk. You only have to set the data object of the page, for example:

site.page(
        {
        url: "/about-me/",
        layout: "about-page.njk",
        content: "Hello, my name is Óscar",
        },
        );

By default, the context of the page is the root directory (/), so any shared data defined in _data files/folders is accessible to this page. You can change the scope of the page in the second argument:

site.page(
        {
        url: "/about-me/",
        layout: "about-page.njk",
        content: "Hello, my name is Óscar",
        },
        "/pages",
        );

Now the page is scoped to the /pages directory, so it can access to the data stored in the /pages/_data.yml file, for example.

Upgrade pagefind to v1.0

The great Pagefind library, used by the pagefind plugin is now 1.0🎉. This new version brings new awesome features, but also some changes:

The option to configure the binary file was removed. The plugin use the npm version that downloads the binary automatically in the Deno cache folder. No more _bin folders!
The option indexing.bundleDirectory was renamed to outputPath.
Added the option customRecords that allows to add additional records to the pagefind database in addition to those generated by the output pages.

See the CHANGELOG.md file for the full list of changes.

]]>

Improved plugins docs

Fri, 01 Sep 2023 13:54:48 GMT

Documentation is possibly one of the most important things for the adoption of any OSS project. No matter if your software is good and easy to use: if you don't communicate it well, most people won't spend time figuring out how to use it.

Lume was very clear about that from the beginning and a lot of effort was put into the documentation website. But one of the difficulties is to keep it updated with the new changes because wrong documentation is worse than no documentation.

Plugins documentation

Documentation is especially challenging for the plugins section: A lot of plugins, each one with its configuration, many of them depend on external libraries (like nunjucks, pug, etc.) which have more configuration, etc. Maintaining all this info up to date is a hard time-consuming job.

But Lume is built on top of Deno, and Deno is supposed to make our life better, right? (at least our life as developers). And it does! because Deno includes a Documentation generator thanks to deno doc, which can extract a lot of interesting info from TypeScript files. It's used to build automatically the modules' documentation in deno.land/x repository. Take a look at the options for the date plugin.

Deno Doc + Aldara

With this idea in mind, I started working on a tool to generate this kind of documentation automatically to be displayed inside the lume.land website. Most Lume plugins export the following two elements:

The Options interface with the types of plugin options
The defaults object with the default options.

The idea is to use these two elements to build automatically the documentation for every plugin. This not only saves time but also ensures the documentation is always up to date.

The command deno doc --json outputs the info in JSON format, perfect for processing. I've created the aldara library that gets the types from Deno Doc, transforms the JSON to a more easy-to-consume structure and even completes some missing info with any JsDoc content found. Then, it can set the default values from the defaults object exported by the plugin and that's all!

The code do all this stuff it is very simple:

import analyze, {
        mergeDefaults,
        } from "https://deno.land/x/aldara@v0.1.1/mod.ts";
        
        async function getScheme(mod: string) {
        const url = `https://deno.land/x/lume@v1.18.5/${mod}`;
        const { defaults } = await import(url);
        const { Options } = await analyze(url, { maxDepth: 2 });
        
        mergeDefaults(Options, defaults);
        return Options.children;
        }

You can see an example in the Minify HTML plugin documentation.

Future

This is only the first version, there's a lot of room for improvement. I've found some issues in deno doc that I hope they were fixed at some point soon:

npm: dependencies are not supported, so the types provided by NPM packages are not included.
There are memory issues with circular dependencies (issue #303), so private types (those that are not exported) cannot be displayed.

Anyway, even with these issues, I think the plugin documentation is now much better than it was. Please, let me know if you have any questions or have found any issues.

]]>

Lume 1.18.0 release notes

Thu, 22 Jun 2023 12:51:21 GMT

This is a summary of the new features introduced in Lume (1.18.0).

Picture plugin

Adding images to web pages is a hard task nowadays. There are new modern image formats like AVIF and JPEG XL with better quality and compression but they are not supported by all browsers.

In order to make this work more easy, Lume has the picture plugin that converts any regular element to a full featured element creating all needed to support all formats and resolutions. This plugin relies on the imagick plugin to make the transformations, so you need the two plugins installed in this exact order:

import lume from "lume/mod.ts";
        import picture from "lume/plugins/picture.ts";
        import imagick from "lume/plugins/imagick.ts";
        
        const site = lume();
        site.use(picture());
        site.use(imagick());
        
        export default site;

Once installed, the plugin will search for all HTML elements with the imagick attribute and will convert the images to the specified formats. For example:

The imagick attribute of this image contains the desired formats (avif, webp and jpg) and the different sizes (300 which means 300 pixels). The @2 suffix indicates that this size should support also the 2x resolution. The output HTML code is:

See the documentation for more info about this plugin.

Symlinks support

Lume 1.18.0 introduces symlinks support in the src directory. This means that you can include symlinks targeting files and folders outside of the src (for example a page or a folder with templates) and Lume will follow them and will use those files to build the site.

This can be useful if you want to reuse the same files for different projects. Instead of copying the files for each project, you can store them in a single place and add symlinks from the different projects.

Keep in mind that the Lume watcher doesn't detect changes in these files.

Vento plugin

Vento is a new template engine designed to use the best ideas from Nunjucks, Liquid, Eta/EJS and Mustache. Some highlighted features are:

Async friendly
Simple API
Allows to write JavaScript code in the templates

To use it, you must import it in the _config file:

import lume from "lume/mod.ts";
        import vento from "lume/plugins/vento.ts";
        
        const site = lume();
        site.use(vento());
        
        export default site;

Vento template engine has been created by me (Óscar Otero, also the Lume creator) and I'm thinking of making it the default engine (replacing Nunjucks) at some point. I would like to know your thoughts.

See more info about this plugin in the documentation.

LightningCSS bundler

Until now, the lightningcss plugin only transformed the CSS code but it couldn't bundle it (inline the @import'ed styles to output a single file with all the code). The reason is LightningCSS is an NPM package that didn't work properly on Deno due the lack of support of some NAPI functions so Lume had to use the WASM version that only transform the code but not bundle it.

Deno team finally improved support for NAPI and now it's possible to use the NPM version of lightningcss and bundle the code. In fact, as of Lume 1.18 the plugin bundles the CSS code by default.

If you want to disable the bundler and only transform the code (back to the previous behavior), just add a includes: false option in the _config file:

import lume from "lume/mod.ts";
        import lightningcss from "lume/plugins/lightningcss.ts";
        
        const site = lume();
        site.use(lightningcss({
        includes: false, // Disable the bundler
        }));
        
        export default site;

Support for JSONC and TOML

Thanks to @kwaa for working on the JSONC and TOML support for Lume. Now you not only can use YAML format in the front matter but also JSON and TOML formats.

To use JSON (or JSONC) in the front matter:

{
        "title": "Hello world"
        }
        
        Page content

To use TOML in the front matter:

+++
        title = Hello world
        +++
        
        Page content

JSONC is enabled by default for pages and data files. So any file with the extension .tmpl.jsonc or a data file _data.jsonc or _data/*.jsonc is loaded by default.

TOML files can also be used for pages and data files but this format is not enabled by default (probably it will in Lume 2.0). To enable it, just import the plugin in the _config file:

import lume from "lume/mod.ts";
        import toml from "lume/plugins/toml.ts";
        
        const site = lume();
        site.use(toml());
        
        export default site;

See the CHANGELOG.md file for the full list of changes.

]]>

Lume 1.17.0 release notes

Fri, 05 May 2023 00:00:00 GMT

This is a brief summary of the main changes introduced in Lume (1.17.0).

New plugin: `feed`

One of the most common things to do when developing a web site is the RSS feed. It's almost mandatory for blogs but it can also be useful for any website with some regular updates. In the same way that there was a sitemap plugin to build the sitemap of the site, Lume 1.17 introduces the new feed plugin to build a feed in RSS or JSON Feed format.

🔥🔥 Thanks to adb-sh for his initial pull request.

To use this plugin, just import it in your _config.ts and configure it:

import lume from "lume/mod.ts";
        import feed from "lume/plugins/feed.ts";
        
        const site = lume();
        
        site.use(feed({
        output: ["/posts.rss", "/posts.json"],
        query: "type=post",
        sort: "date=desc",
        limit: 10,
        info: {
        title: "My awesome blog",
        description: "Post updates of my blog",
        },
        items: {
        title: "=title",
        description: "=excerpt",
        },
        }));
        
        export default site;

In this example, Lume creates two Feed files defined in the output key: /posts.rss (in RSS format) and /posts.json (in JSON Feed format). The file extensions determines the format to use.

The query, sort and limit options are the same as you typically use in the search.pages() API.

The info object has the description of the Feed (like title, description, etc) and the items object the description of every item in the Feed. Both objects use the same aliases as metas plugin: any value starting with = represents a variable name that will be used to extract this info. In our example, the title and description is the same as the title and excerpt variables of the page.

It's also possible to extract the info using CSS selectors. For example, let's say we want to generate a RSS with the same content as the div .post-content. We just have to start the value of the code with $:

import lume from "lume/mod.ts";
        import feed from "lume/plugins/feed.ts";
        
        const site = lume();
        
        site.use(feed({
        output: ["/posts.rss", "/posts.json"],
        query: "type=post",
        sort: "date=desc",
        limit: 10,
        info: {
        title: "My awesome blog",
        description: "Post updates of my blog",
        },
        items: {
        title: "=title",
        description: "=excerpt",
        content: "$.post-content",
        },
        }));
        
        export default site;

If you want to create more than one feed, just use the plugin once per feed:

site.use(feed({
        output: "/posts.rss",
        // Posts feed configuration
        }));
        
        site.use(feed({
        output: "/articles.rss",
        // Articles feed configuration
        }));

SASS supports remote files

In this version, Lume got a big refactoring of how the files in the src directory are scanned, loaded and refreshed. This change fixed some existing bugs and open the door for new possibilities, because now it will be easier to implement new features.

Thanks to this refactoring, SASS plugin supports remote files, so you can load your variables and mixings from a remote URL to use them in your build:

import lume from "lume/mod.ts";
        import sass from "lume/plugins/sass.ts";
        
        const site = lume();
        site.use(sass());
        
        site.remoteFile(
        "/_includes/variables.scss",
        "https://example.com/theme/variables.scss",
        );
        
        export default site;

@import "variables.scss";
        
        body {
        color: $main-color;
        }

The're a breaking change in the SASS plugin: the includes option accepts only a string instead of an array of paths.

Allow to pass extra data to on demand pages

The on_demand plugin allows to render a page on request time, instead of build time. This is useful to insert dynamic content and reduce the build time specially for big sites. Lume 1.17 introduces a way to insert additional variables to the page before rendering.

The onDemand plugin has the new option extraData which accepts a function that must return an object with the extra data to be passed to the page. For example, let's say we want to pass the search parameters of the request's url:

import lume from "lume/mod.ts";
        import onDemand from "lume/plugins/on_demand.ts";
        
        site.use(onDemand({
        extraData(request: Request) {
        const searchParams = new URL(request.url).searchParams;
        const params = Object.fromEntries(searchParams.entries());
        
        return {
        params,
        };
        },
        }));
        
        export default site;

Now, the on demand pages will have the params key with the search params values. For example, in a Nunjucks page:

---
        layout: layout.njk
        ondemand: true
        url: /example/
        ---
        
        Hello {{ params.name }}

The URL /example/?name=Óscar will return Hello Òscar.

Note that on-demand pages works better on Deno CLI than Deno Deploy. There's a post explaining the current limitations on Deno Deploy, so you should consider this plugin as highly experimental.

Removed old code

A few versions ago, Lume removed the ability to be installed globally (with deno install ...) in benefit of deno task. Some old files were keept for backward compatibility when upgrading from an old version. Now these files were removed (ci.ts, install.ts). If you get any issue running Lume (specially in CI environments), please update your script to use deno task lume.

There are more changes in Lume 1.17, like bug fixes in some plugins, dependency updates, etc. See the CHANGELOG.md file for the full list of changes.

]]>

Lume 1.16.0 release notes

Tue, 21 Mar 2023 00:00:00 GMT

Hi everyone! This is a brief summary of what the new version of Lume (1.16.0) brings.

BREAKING CHANGE: `multilanguage` plugin refactor

The multilanguage plugin was created to simplify the creation of sites in multiple languages. But the way it worked so far was a bit confusing and not very practical. Lume 1.16 introduce some changes that (sadly) breaks some compatibility with the previous version. But I think the new behavior is much more clear and easy to use and understand. Some of the most important changes:

You need to specify the available languages in the _config file

In the old plugin, each page defined its own languages. There wasn't a place to specify the available languages for the whole site. This makes the plugin to work inconsistently for each page, because it depended on the number of languages defined in every case. The new version requires to specify the languages in the _config file, so it will work in the same way with all pages.

site.use(multilanguage({
        languages: ["en", "gl"],
        }));

The language prefix is automatically added to the urls.

The new plugin automatically prepend the /${lang}/ prefix to all urls. If you have the following page:

---
        lang: en
        url: /hello-world/
        ---
        
        # Hello world

The output file is /en/hello-world/. This ensure all pages in the same language are in the same subdirectory.

It's possible to define a language as default, so all pages in this language won't have this prefix. For example, let's say our site is in english and galician but we want to set english as the main language:

site.use(multilanguage({
        languages: ["en", "gl"],
        defaultLanguage: "en",
        }));

With this configuration, the english version of the page is /hello-world/ but the galician version is /gl/hello-world/.

Use `id` to relate pages in different languages

In the old version, to setup multiple versions of the same page in individual files, you had to follow some strict instructions:

All files must be in the same folder.
They must have the same name, suffixed with the language.

For example:

- /about-me_en.md
        - /about-me_gl.md

The new plugin removes this behavior. You have to use the id variable to relate different pages.

For example, the english version:

---
        lang: en
        url: /about-me/
        id: about
        ---
        
        # About me

The galician version:

---
        lang: gl
        url: /acerca-de-min/
        id: about
        ---
        
        # Acerca de min

The new plugin interprets these two pages as the same content but in different languages, because they have the same id (about). You don't need to have all files in the same folder with a specific name.

See the complete plugin documentation.

New `nav` plugin

The nav plugin builds automatically a menu of your site using the URLs to define the hierarchy. For example, let's say we have a site which exports the following pages:

/
/articles/
/articles/first-article/
/articles/second-article/chapter-1/
/articles/second-article/chapter-2/

This plugin register the nav variable in your templates, similar to search but intended for navigation stuff. The nav variable has some useful functions:

The nav.menu() function returns an object with the site structure, so you can build a tree menu:

const tree = nav.menu();
        
        console.log(tree);
        
        {
        slug: "",
        data: Data,
        children: [
        {
        slug: "articles",
        data: Data,
        children: [
        {
        slug: "first-article",
        data: Data,
        },
        {
        slug: "second-article",
        children: [
        {
        slug: "chapter-1",
        data: Data,
        },
        {
        slug: "chapter-2",
        data: Data,
        },
        ],
        },
        ],
        },
        ];
        }

The data property contains the page data object. So you can access to any page variable like data.title or data.url.
The item with the slug second-article doesn't have the data value because there isn't any page with the url /articles/second-article/. Note that there are pages inside this url (/articles/second-page/chapter-1/ and /articles/second-page/chapter-2/) that do have the data value.

The nav.breadcrumb() function returns all parent pages of a specific page. For example:

const breadcrumb = nav.breadcrumb("/articles/second-article/chapter-2/");
        
        console.log(breadcrumb);
        
        [
        {
        slug: "chapter-2",
        data: Data,
        },
        {
        slug: "second-article",
        children: ...
        },
        {
        slug: "articles",
        data: Data,
        children: ...
        },
        {
        slug: "",
        data: Data,
        children: ...
        },
        ]

You can see an example of the nav plugin in the Simple Wiki theme.

The lateral menu is built with nav.menu() (see the code)
The breadcrumb above the title is built with nav.breadcrumb() (see the code)

See the plugin documentation for more details.

New `copyRemainingFiles` function

Until now, the only way to copy static files was using the site.copy() function, that allows to specify a file/folder or an array of extensions. This works fine if you know in advance all files that must be copied, because they are in a specific folder like /static or have a known extension (.jpg, .png, etc).

But it's not practical when your static files are distributed in random folders or can have any extension. For example, imagine you have a website with articles, and every article is stored in it's folder that can contain static files of any extension:

|_ articles/
        |_ article-1/
        |   |_ index.md
        |   |_ picture.jpg
        |   |_ document.pdf
        |   |_ foo32.gif
        |_ article-2/
        |_ index.md
        |_ journey.mp4
        |_ download.zip

The site.copy() function it's not very helpful because if we copy the /articles/ folder, the index.md files won't be processed (they will be treated as static files). We can select the files by extension with site.copy([".jpg", ".pdf", ".gif", ".mp4", ".zip"]) but every time a new extension is uploaded, we have to remember to include it in the _config file.

The copyRemainingFiles() basically says: when you find a file and don't know what to do, just copy it. You can include a function to filter which files will be copied. For example:

site.copyRemainingFiles((path: string) => path.startsWith("/articles/"));

Now, only the remaining files inside the /articles/ folder will be copied.

`page.data.children` property

Let's say you have a blog and want to list all posts with their content. It's possible with this code:

{% for post in search.pages("type=post") %}
        {{ post.data.title }}
        {{ post.data.content | md | safe }}
        {% endfor %}

If the post are written in Markdown, the variable post.data.content of the page has the unrendered markdown code, so you have to use the md filter to render it to HTML. This has the drawback of every post need to be rendered twice, one to build the post page and other to build this list of posts.

If your posts are in MDX this is even worse, because there's no filter to convert mdx code to HTML. It's possible to get the rendered content of the page from post.content but it includes not only the HTML of the post but also the layout used in this page.

As of version 1.16, Lume will save the rendered content into the children property, so you can use it in other pages in this way:

{% for post in search.pages("type=post") %}
        {{ post.data.title }}
        {{ post.data.children | safe }}
        {% endfor %}

The content will be rendered only once and no filter is needed.

There are more interesting things in Lume v1.16.0. See the CHANGELOG.md file for the full list of changes.

]]>

Lume 1.15.0 - Release notes

Tue, 10 Jan 2023 00:00:00 GMT

The version 1.15.0 is full of exciting new features.

Archetypes

Hugo has a nice feature called archetypes, templates used when creating new content. The most obvious example is a post: instead of creating a new markdown file from scratch everytime you want to create a new post, you can run an archetype that creates the post file for you with a preconfigured front matter and content.

In Lume, an archetype is just a JavaScript or TypeScript file that export a function returning an object with the file path and the file content. The archetype must be saved in the _archetypes directory, inside the src folder. For example:

// _archetypes/example.js
        
        export default function () {
        return {
        path: "/pages/example.md",
        content: "Content of the file",
        };
        }

The archetypes are invoked with the command deno task lume new [archetype-name] (or lume new [archetype-name] with the new Lume CLI). If you run lume new example to run this archetype, the file /pages/example.md will be created.

See the archetypes documentation to learn more about how to generate different formats, pass arguments or create multiple files.

Tailwindcss

Tailwind support is a recurring request for Lume. Until now it was not possible to use Tailwind in Deno, so the only alternative available was Windi CSS.

The support of npm: packages in Deno allowed to use many NPM packages that until now only work on Node. Still, there were errors in Tailwind due the acorn-node dependency that doesn't work on Deno.

The @lumeland organization in NPM contains modified versions of the packages that don't work in Deno. @lumeland/tailwindcss is the same code as tailwindcss but replacing that dependency. When this is fixed in the official library, this modified version will be deprecated.

The Tailwindcss plugin depends on postcss, so you need to use both plugins in this exact order:

import lume from "lume/mod.ts";
        import tailwind from "lume/plugins/tailwindcss.ts";
        import postcss from "lume/plugins/postcss.ts";
        
        const site = lume();
        
        site.use(tailwind());
        site.use(postcss());
        
        export default site;

Context data

The function site.data() allows to insert arbitrary data in your site from the _config.ts file:

site.data("layout", "main.njk");

The context of this data is global: is available to all pages of the site. It's equivalent to having a _data.* file in the root of your site. As of Lume 1.15.0, it's possible to specify the directory of the data in the third argument, for example:

site.data("layout", "main.njk", "/posts");

Now, the layout value is available only to the pages inside the /posts directory. Equivalent to creating a /posts/_data.yml file with this value.

You can assign data not only to directories but also to specific files:

site.data("layout", "main.njk", "/posts/hello-world.md");

💣 Breaking changes in the plugin `date`

The date plugin use the Deno version of date_fns to transform the dates. That version wasn't updated in 2 years so I decided to switch to the Node version. Everything should work fine, the only difference is the locales configuration, that need to be imported from npm in the _config file. For example, if you have this configuration:

site.use(date({
        locales: ["gl", "pt"],
        }));

You need to change it to:

import gl from "npm:date-fns/locale/gl/index.js";
        import pt from "npm:date-fns/locale/pt/index.js";
        
        //...
        site.use(date({
        locales: { gl, pt },
        }));

Other changes

The sass plugin uses now a modified version of the official NPM package.
The relations plugin has been improved and there are some breaking changes in the configuration API. See the plugin page for the updated documentation.
Dependency update and bugfixes.

See the CHANGELOG.md file for the full list of changes.

]]>

Lume CLI

Fri, 06 Jan 2023 00:00:00 GMT

Happy new year, Lumers!

2022 was a great year for Lume, it reached to 1K stars in GitHub and many of you have collaborated in form of pull requests, promoting Lume in your blogs and social networks or even sponsoring me. I want to thank you and promise to keep working hard to make Lume even better.

🔥🔥🔥🔥🔥🔥🔥🔥🔥

Introducing Lume CLI

The best way to run Lume is using the Deno tasks. It's the most portable way to run Lume without installing anything else but Deno, and it ensures that the Lume version is the same as specified in the import_map.json file. In fact, there's a plan to remove the CLI interface completely.

The only drawback of using Deno tasks is they are more verbose to type. Instead of simply running lume -s or lume run my-script you have to type deno task lume -s and deno task lume run my-script.

In order to keep using tasks to run Lume and, at the same time, having a more ergonomic way to run the commands, I have released the new Lume CLI.

To install it, just run:

deno install --allow-run --name lume --force --reload https://deno.land/x/lume_cli/mod.ts

Lume CLI is just a small script to add the deno task words at the beginning of your lume commands. For example, if you run lume -s, the CLI will run deno task lume -s.

It's an independent module, separated from the Lume repository, so it's up to you to use it or not.

It also includes two additional commands:

lume init: To initialise Lume in the current directory. It's like running deno run -Ar https://deno.land/x/lume/init.ts.
lume ugrade-cli: As you may guess, it will upgrade the Lume CLI to the latest version.

Lume CLI combines the best of the two worlds and opens the door to removing the old CLI interface in the Lume repo sometime soon.

]]>

Lume 1.14.0 is out

Mon, 12 Dec 2022 00:00:00 GMT

Lume 1.14.0 was released. This is a list of the main changes and new features.

New functions to (pre)process all pages at the same time

The functions site.process() and site.preprocess() are used to modify pages after or before rendering. For example, to process the HTML pages, you can do:

site.process([".html"], (page) => my_processor(page));

This callback is executed once per page, so if you have 200 pages, the callback is executed 200 times.

This is great to transform pages individually, but sometimes it's better to run the function only once to all pages at the same time. Two new functions were added for this purpose: processAll() and preprocessAll(). They are similar to process() and preprocess() but will receive all matched pages in the first argument:

site.processAll([".html"], (pages) => {
        pages.forEach((page) => my_processor(page));
        console.log(`Processed ${pages.length} HTML pages!`);
        });

In previous versions, the only way to do something like that was through events like afterRender, beforeRender, beforeSave, etc. The advantage of using the new processAll and preprocessAll is they respect the order of the other processors:

site.process([".html"], first_processor);
        site.processAll([".html"], second_processor);
        site.process([".html"], third_processor);

In this example, second_processor is run after first_processor and before third_processor.

Introducing `hooks`

Hooks are functions registered by some plugins that can be invoked by other plugins or by yourself in the _config file. Hooks are stored in site.hooks and are useful to change a plugin configuration after the installation. For example, the postcss plugin sets the hook addPostcssPlugin. You can create a Lume plugin to, for example, minify the css code with CSS Nano:

import cssnano from "npm:cssnano@5.1.14";
        
        export default function () {
        return (site) => {
        if (!site.hooks.addPostcssPlugin) {
        throw new Error("This plugin depends on postcss");
        }
        
        site.hooks.addPostcssPlugin(cssnano);
        };
        }

Now, you can use this plugin in the _config.ts file:

import lume from "lume/mod.ts";
        import postcss from "lume/plugins/postcss.ts";
        import nanocss from "./plugins/nanocss.ts";
        
        const site = lume();
        
        site.use(postcss());
        site.use(nanocss());
        
        export default site;

Support for `splitting` mode for esbuild

Code splitting is a bundle technique that creates separate files with common code shared by multiple entry points. For example, if both entry points a.ts and b.ts imports c.ts, instead of including the c.ts code in both files (which would be duplicated), the code is saved into a chunk file that is imported by both files.

To generate the chunk files, we need to know all entry points first. But thanks to the implementation of processAll() function (previously explained) this is now possible in Lume. To enable the splitting mode, just need to configure the esbuild plugin in this way:

site.use(esbuild({
        options: {
        splitting: true,
        },
        }));

Improved `metas` plugin

A couple of improvements have been added to metas:

No need for `mergedKeys`

The metas plugin needs a mergedKeys to customise the merging mode of the metas key:

metas:
        site: Site title
        icon: /img/icon.png
        lang: en
        
        # Customise the merging mode of "metas"
        mergedKeys:
        metas: object

You no longer need to add this value manually. The plugin inserts it automatically for you.

Field aliases

Field aliases are the new way to reuse a value in the metas. For example:

title: This is the title
        
        metas:
        title: "=title" # Alias to the title value

Any value starting with = is considered an alias to another field. You can use dots for subvalues:

title: This is the title
        intro:
        text: Page description
        metas:
        title: "=title"
        description: "=intro.text"

Field aliases are way more powerful than the defaultPageData option of the plugin, which is deprecated and will be removed in the future.

Field aliases supports subvalues.
They can be configured at page or folder level with _data files.

Changes to `prism` plugin

The prism plugin now loads the Prism library from npm:. This change removes the languages option so if you need to load additional languages, you have to import them in your _config.ts file:

import lume from "lume/mod.ts";
        import prism from "lume/plugins/prism.ts";
        
        // Additional prism languages
        import "npm:prismjs@1.29.0/components/prism-less.js";
        import "npm:prismjs@1.29.0/components/prism-git.js";
        
        const site = lume();
        site.use(prism());
        
        export default site;

The good news is you can also load plugins.

New plugin `filter_pages`

This plugin is the first step to deprecate the --dev mode of Lume (that ignores the pages with draft=true). The new plugin filter_pages filters pages using a callback and provides more flexibility. For example, let's say you want to ignore the draft pages in the production environment:

import lume from "lume/mod.ts";
        import filter_pages from "lume/plugins/filter_pages.ts";
        
        const site = lume();
        const isProd = Deno.env.get("DENO_ENV") === "prod";
        
        site.use(filter_pages({
        fn: (page) => !isProd || !page.data.draft,
        }));
        
        export default site;

See the CHANGELOG.md file for the full list of changes.

]]>

How to use the "on demand" plugin in November 2022

Tue, 22 Nov 2022 00:00:00 GMT

The on_demand plugin is the attempt of Lume to provide some server-side rendering behaviour to a static site. The idea is simple: omit some pages in the build process (with ondemand: true) in order to build them when they are requested.

This allows insert dynamic content in the pages like in this example, a site with the pages showing the current time. You can see the code repository, where the current time is defined as a helper in the _config.ts file and then called in the Nunjucks layout used by both pages.

This plugin was tested only in Deno Deploy but it should work on any hosting with Deno. But it is not all rosy in the garden, because Deno Deploy has some limitations that makes more difficult to use this plugin, compared with the Deno CLI that you have installed locally:

No support for dynamic imports

One of the most requested features in Deno Deploy is the ability to import modules dynamically. One year and half since the issue was created, it's still not possible and looks like it won't be in the short term. Lume uses dynamic imports to load pages and data in JavaScript, JSX and TypeScript, so if your on demand pages use any of these formats, they will fail on Deno Deploy. The only way to skip this limitation is by generating a file that imports statically all files that, under normal conditions, would be imported dynamically (this file is generated automatically by the ondemand plugin). It's not an elegant solution but it's the only solution that works at this moment.

No support for NPM modules

As of version 1.12.0, Lume uses npm: modules for some dependencies. NPM especifiers are not yet supported in Deno Deploy. Fortunately we can use import maps to use the esm.sh version of the NPM packages. In the repository of the plugin demo, you can see the import_map.json file needed to map all NPM lume dependencies to the esm.sh equivalent.

And this is the state of the dynamic pages in Lume for now. I hope these limitations disappear in the short term (I guess NPM modules will be supported soon). If you know of other hosting providers with Deno support and you get the on demand plugin to work there, please, let me know.

]]>

Lume 1.13.0 is out

Wed, 16 Nov 2022 00:00:00 GMT

I'm happy to announce that Lume 1.13.0 was released with some interesting additions and changes. Let's see the highlights.

MDX support

MDX support for Lume was requested for a long time. Now that Deno can handle npm imports, it's more easy to bring support for this library. The new mdx plugin allows to create your pages in .mdx, so you can combine markdown and JSX components in a single file.

To enable MDX in your site, you only need to import the mdx plugin and any of the JSX plugins available (jsx to use React, jsx_preact to use Preact). This is an example with Preact:

import lume from "lume/mod.ts";
        import jsx from "lume/plugins/jsx_preact.ts";
        import mdx from "lume/plugins/mdx.ts";
        
        const site = lume();
        
        site.use(jsx());
        site.use(mdx());
        
        export default site;

Now you can create .mdx files that imports JSX components or use the Lume's components from the global comp variable:

---
        title: Hello world
        description: This is a description
        ---
        
        import Image from "./_includes/Image.tsx";
        
        
        
        ## Hello world
        
        This is a markdown file with the title **{ title }**.

See more info in the documentation

New `sitemap` plugin

The sitemap plugin was created by Jrson some time ago in the experimental plugins repo. It creates a sitemap.xml file and a robots.txt file with a link to the sitemap file.

This plugin is now included in Lume 1.13.0, so you can import it via lume/plugins/sitemap.ts.

See more info in the documentation

Improved the `multilanguage` plugin

The multilanguage plugin allows to create multiple language versions of the same page. In Lume v1.13.0 it's possible to save the language versions in different files. To be identified by the plugin as language versions of the same page, the files must fulfill the following requirements:

They must be saved in the same directory.
They must have the lang variable defined.
They must have the same filename ending with the _[lang] suffix.

For example:

|_ /posts
        |_ /my-first-post_en.md
        |_ /my-first-post_es.md

These two files contains the same post but in different languages and Lume will generate the pages /en/posts/my-first-post/ and /es/posts/my-first-post/.

It's possible to have one page without the language suffix, useful if you already have a site with only one language and want to add other languages progressively without affeting to the existing urls. For example:

|_ /posts
        |_ /my-first-post.md
        |_ /my-first-post_es.md

In this case, Lume detects they are the same posts but the URLs generated are /posts/my-first-post/ and /es/posts/my-first-post/.

Deprecated `page.dest` and `page.updateDest`

All pages in Lume have the property dest with info about the destination file.

The destination is calculated according to the page.data.url value (if defined) or the source file name. More info in the Lume docs.

The problem is whenever the URL of a page is changed, it's necessary to change the value in two places, page.data.url and page.dest. For example, a SASS plugin that modifies the extension of the files from .scss to .css:

// Extremely simplified code:
        site.process([".scss"], (page) => {
        page.content = processSASS(page.content);
        
        // Change the page URL
        page.data.url = page.data.url.replace(/\.scss$/, ".css");
        
        // Change the destination extension
        page.dest.ext = ".css";
        });

There's the page.updateDest function that changes the page.dest and page.data.url values accordingly, ensuring both properties are consistent:

// Extremely simplified code:
        site.process([".scss"], (page) => {
        page.content = processSASS(page.content);
        
        // Change the page URL and destination
        page.updateDest({ ext: ".css" });
        });

I never felt confortable with this, because it's duplicating the same value in two different places. Originally it has been created in this way because they have different purposes and they can have different values (like a page with the url /about-us/ but the destination file is /about-us/index.html).

In Lume 1.13.0 the page.dest and page.updateDest are deprecated (and probably removed in 1.14.0). Now you only have to change the value in one place: page.data.url.

More simple and intuitive.

New option `returnPageData` to `search` helper

The global helper search.pages() returns an array of pages. But in most cases you don't need the page instance, only its data. The new returnPageData option allows to change this behavior to return only the page.data object. This will be the default behavior in Lume 2.0, but for compatibility it's disabled by default. See more info in this issue.

To enable it, just configure the plugin in the _config.ts file.

import lume from "lume/mod.ts";
        
        const search = { returnPageData: true };
        
        const site = lume({}, { search });
        
        export default site;

Once configured, the following code:

{% for article in search.pages("type=article", "date=desc") %} 
        
        {{ article.data.title }}
        
        {% endfor %}

needs to be changed to:

{% for article in search.pages("type=article", "date=desc") %} 
        
        {{ article.title }}
        
        {% endfor %}

Removed `no-html-extension` option for prettyUrls

Pretty URLs configuration allowed the no-html-extension value. It exports the page as regular html (like /article.html) but the url of these pages are /article (without extension). You can see more info in this issue.

This option was removed in Lume 1.13.0 because it's not needed. If you want this functionality, just use the modify_urls plugin to remove the extension to the HTML links:

import lume from "lume/mod.ts";
        import modifyUrls from "lume/plugins/modify_urls.ts";
        
        const site = lume({
        prettyUrls: false, //To export the pages as example.html
        });
        
        site.use(modifyUrls({
        fn: (url) => url.replace(/\.html$/, ""),
        }));
        
        export default site;

New `emptyDest` option

Lume needs to load all pages in order to build the site. This may be a problem for large sites with 50K or more pages that cause out of memory issues.

A solution is to build these large sites in several steps, creating different builds exporting to the same dest directory, so the site can be built incrementally. Lume automatically empty the dest folder before any build, so the new emptyDest option allows to change this behavior:

const site = lume({
        emptyDest: false, // Don't empty the dest folder
        });

Removed timestamp detection in the filename

Lume can extract dates from the page's filename (for instance 2022-10-02_post-title.md).

If there's a number (like 23_post-title.md), it's interpreted as a timestamp. This behavior was removed because it's a too generical pattern (See this issue). If you need this feature back, you can create a preprocessor for that:

site.preprocess([".md"], (page) => {
        const [date, url] = myCustomFileParse(page.data.url);
        page.data.date = date;
        page.data.url = url;
        });

See the CHANGELOG.md file for a full list of changes.

]]>