Lume 1.19.0 was released! Hopefully, it will be the last minor version of 1.x\nbefore the incoming Lume 2. This is a summary of the changes and new features.
\n\nThe favicon is a common task we have to do every time we build a new website.\nIt's not as easy as should be because there are different formats, sizes,\nresolutions, 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\nautomatically creates the files /favicon.ico, /favicon-16.png,\n/favicon-32.png and /apple-touch-icon.png and adds the <link> elements\nneeded in all HTML pages.
As any other Lume plugin, the installation can't be easier: just import the\nplugin and use it:
\nimport lume from "lume/mod.ts";\nimport favicon from "lume/plugins/favicon.ts";\n\nconst site = lume();\nsite.use(favicon());\n\nexport default site;\nSee the favicon plugin documentation.
\nThis plugin was created by Jrson and available in\nthe\nexperimental plugins repo\nsince a time ago, under the name reading_time. It's a simple plugin to\ncalculate 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\nmoved to Lume repo and renamed to reading_info. The reason of the new name is\nthe plugin not only returns the time, but also other interesting info like the\nnumber of words. Maybe we can include more interesting info in the future, let\nme know your suggestions.
It uses the\nInt.Segmenter\nstandard function to count the words, using the page variable lang to detect\nthe language. The data is stored in the variable readingInfo, so you can use\nit in your templates in this way:
<h1>{{ title }}</h1>\n<p>{{ readingInfo.words }} words / {{ readingInfo.minutes }} min read</p>\nSee\nthe reading_info plugin documentation
\npicture pluginThe picture plugin has received many\nimprovements and bug fixes. The most notable:
\nsrc value of the original img elementIn previous versions, the src value of the img element referred to the\noriginal image. But this image isn't always exported so it returns a 404\nerror. As of Lume 1.19, the last source element will be used as the value for\nthe img:
<!-- Source code -->\n<img src="/images/test.jpg" imagick="jpg webp 600">\n\n<!-- Previous output: -->\n<picture>\n <source srcset="/images/test-600w.webp" type="image/webp">\n <source srcset="/images/test-600w.jpg" type="image/jpeg">\n <img src="/images/test.jpg">\n</picture>\n\n<!-- New output: -->\n<picture>\n <source srcset="/images/test-600w.webp" type="image/webp">\n <img src="/images/test-600w.jpg">\n</picture>\nIn the previous version, the source elements were created in the same order as\ndefined in the imagick attribute. For example:
<img src="/images/test.jpg" imagick="jpg webp avif 600">\nThis outputs the source elements in the same order (jpg, webp and avif):
<picture>\n <source srcset="/images/test-600w.jpg" type="image/jpeg">\n <source srcset="/images/test-600w.webp" type="image/webp">\n <source srcset="/images/test-600w.avif" type="image/avif">\n <img src="/images/test.jpg">\n</picture>\nBecause jpg is a format widely supported, it will be choosen by all browsers\nbecause it's the first in the list, even if better formats like webp or avif\nare there. As of Lume 1.19 the formats are sorted automatically. By default the\norder is: jxl, avif, webp, png, jpg (from the most modern to the most\nsupported). So the new output is:
<picture>\n <source srcset="/images/test-600w.avif" type="image/avif">\n <source srcset="/images/test-600w.webp" type="image/webp">\n <img src="/images/test-600w.jpg">\n</picture>\nFrom now on, the imagick attribute can have only formats, sizes are no longer\nmandatory. It's useful if you don't want to resize the image, just provide\ndifferent formats:
<!-- Source code -->\n<img src="/images/test.jpg" imagick="avif jpg webp">\n\n<!-- Ouputs: -->\n<picture>\n <source srcset="/images/test.avif" type="image/avif">\n <source srcset="/images/test.webp" type="image/webp">\n <img src="/images/test.jpg">\n</picture>\nIf the image has only one format, no picture element will be created:
<!-- Source code -->\n<img src="/images/test.jpg" imagick="avif 300">\n\n<!-- Previous output: -->\n<picture>\n <source srcset="/images/test-300.avif" type="image/avif">\n <img src="/images/test.jpg">\n</picture>\n\n<!-- New ouput: -->\n<img src="/images/test-300.avif">\nsize attributeThe plugin now supports the size attribute:
<!-- Source code -->\n<img src="img.png" imagick="avif png 100@2" sizes="(width < 700px) 100px, 200px">\n\n<!-- Previous output: -->\n<picture>\n <source srcset="img-100w.avif, img-100w@2.avif 2x" type="image/avif">\n <source srcset="img-100w.png, img-100w@2.png 2x" type="image/png">\n <img src="img.png" />\n</picture>\n\n<!-- New output: -->\n<picture>\n <source srcset="img-100w.avif, img-100w@2.avif 2x" type="image/avif" sizes="(width < 700px) 100px, 200px">\n <img src="img-100w.png" srcset="img-100w@2.png 2x" sizes="(width < 700px) 100px, 200px">\n</picture>\nsite instanceLume allows to customize the way some keys are merged with the variable\nmergedKeys. You can see a\ndetailed explanation of this feature\nin the documentation.
The function site.mergeKey() allows to define this value in the _config.ts\nfile, which is more useful specially for plugins that register new merge\nstrategies for some keys automatically.
For example, let's say you want to merge the keys categories using the\nstringArray strategy:
site.mergeKey("categories", "stringArray");\nThe site.page() function allows to create new pages dynamically from the\n_config.ts file, without having a page file in the disk. You only have to set\nthe data object of the page, for example:
site.page(\n {\n url: "/about-me/",\n layout: "about-page.njk",\n content: "Hello, my name is Óscar",\n },\n);\nBy default, the context of the page is the root directory (/), so any shared\ndata defined in _data files/folders is accessible to this page. You can change\nthe scope of the page in the second argument:
site.page(\n {\n url: "/about-me/",\n layout: "about-page.njk",\n content: "Hello, my name is Óscar",\n },\n "/pages",\n);\nNow the page is scoped to the /pages directory, so it can access to the data\nstored in the /pages/_data.yml file, for example.
The great Pagefind library, used by the\npagefind plugin is now 1.0🎉. This new\nversion brings\nnew awesome features,\nbut also some changes:
\nnpm\nversion that downloads the binary automatically in the Deno cache folder. No\nmore _bin folders!indexing.bundleDirectory was renamed to outputPath.customRecords that allows to add additional records to the\npagefind database in addition to those generated by the output pages.See the\nCHANGELOG.md file\nfor the full list of changes.
\n","date_published":"Mon, 25 Sep 2023 18:25:59 GMT"},{"id":"https://aoba-test.netlify.app/posts/improved-plugins-docs/","url":"https://aoba-test.netlify.app/posts/improved-plugins-docs/","title":"Improved plugins docs","content_html":"Documentation is possibly one of the most important things for the adoption of\nany OSS project. No matter if your software is good and easy to use: if you\ndon't communicate it well, most people won't spend time figuring out how to use\nit.
\n\nLume was very clear about that from the beginning and a lot of effort was put\ninto the documentation website. But one of the difficulties is to keep it\nupdated with the new changes because wrong documentation is worse than no\ndocumentation.
\nDocumentation is especially challenging for the\nplugins section: A lot of plugins, each one with\nits configuration, many of them depend on external libraries (like nunjucks,\npug, etc.) which have more configuration, etc. Maintaining all this info up to\ndate is a hard time-consuming job.
\nBut Lume is built on top of Deno, and Deno is supposed to make our life better,\nright? (at least our life as developers). And it does! because Deno includes\na\nDocumentation generator\nthanks to deno doc, which can extract a lot of interesting info from\nTypeScript files. It's used to build automatically the modules' documentation in\ndeno.land/x repository. Take a look at\nthe options for the date plugin.
With this idea in mind, I started working on a tool to generate this kind of\ndocumentation automatically to be displayed inside the lume.land website. Most\nLume plugins export the following two elements:
\nOptions interface\nwith the types of plugin optionsdefaults object\nwith the default options.The idea is to use these two elements to build automatically the documentation\nfor every plugin. This not only saves time but also ensures the documentation is\nalways up to date.
\nThe command deno doc --json outputs the info in JSON format, perfect for\nprocessing. I've created the\naldara library that gets the types from\nDeno Doc, transforms the JSON to a more easy-to-consume structure and even\ncompletes some missing info with any JsDoc content found. Then, it can set the\ndefault values from the defaults object exported by the plugin and that's all!
The code do all this stuff it is very simple:
\nimport analyze, {\n mergeDefaults,\n} from "https://deno.land/x/aldara@v0.1.1/mod.ts";\n\nasync function getScheme(mod: string) {\n const url = `https://deno.land/x/lume@v1.18.5/${mod}`;\n const { defaults } = await import(url);\n const { Options } = await analyze(url, { maxDepth: 2 });\n\n mergeDefaults(Options, defaults);\n return Options.children;\n}\nYou can see an example in the\nMinify HTML plugin documentation.
\nThis is only the first version, there's a lot of room for improvement. I've\nfound 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\nare not included.Anyway, even with these issues, I think the plugin documentation is now much\nbetter than it was. Please, let me know if you have any questions or have found\nany issues.
\n","date_published":"Fri, 01 Sep 2023 13:54:48 GMT"},{"id":"https://aoba-test.netlify.app/posts/lume-1.18.0-release-notes/","url":"https://aoba-test.netlify.app/posts/lume-1.18.0-release-notes/","title":"Lume 1.18.0 release notes","content_html":"This is a summary of the new features introduced in Lume (1.18.0).
\n\nAdding images to web pages is a hard task nowadays. There are new modern image\nformats like AVIF and JPEG XL with better quality and compression but they are\nnot supported by all browsers.
\nIn order to make this work more easy, Lume has the picture plugin that\nconverts any regular <img> element to a full featured <picture> element\ncreating all <source srcset> needed to support all formats and resolutions.\nThis plugin relies on the imagick plugin to make the transformations, so you\nneed the two plugins installed in this exact order:
import lume from "lume/mod.ts";\nimport picture from "lume/plugins/picture.ts";\nimport imagick from "lume/plugins/imagick.ts";\n\nconst site = lume();\nsite.use(picture());\nsite.use(imagick());\n\nexport default site;\nOnce installed, the plugin will search for all HTML elements with the imagick\nattribute and will convert the images to the specified formats. For example:
<img src="/flowers.jpg" imagick="avif webp jpg 300@2">\nThe imagick attribute of this image contains the desired formats (avif,\nwebp and jpg) and the different sizes (300 which means 300 pixels). The\n@2 suffix indicates that this size should support also the 2x resolution.\nThe output HTML code is:
<picture>\n <source srcset="/flowers-300w.avif, /flowers-300w@2.avif 2x" type="image/avif">\n <source srcset="/flowers-300w.webp, /flowers-300w@2.webp 2x" type="image/webp">\n <source srcset="/flowers-300w.jpg, /flowers-300w@2.jpg 2x" type="image/jpeg">\n <img src="/flowers.jpg">\n</picture>\nSee the documentation for more info about\nthis plugin.
\nLume 1.18.0 introduces symlinks support in the src directory. This means that\nyou can include symlinks targeting files and folders outside of the src (for\nexample a page or a folder with templates) and Lume will follow them and will\nuse those files to build the site.
This can be useful if you want to reuse the same files for different projects.\nInstead of copying the files for each project, you can store them in a single\nplace and add symlinks from the different projects.
\nKeep in mind that the Lume watcher doesn't detect changes in these files.
\nVento is a new template engine designed\nto use the best ideas from Nunjucks, Liquid, Eta/EJS and Mustache. Some\nhighlighted features are:
\nTo use it, you must import it in the _config file:
\nimport lume from "lume/mod.ts";\nimport vento from "lume/plugins/vento.ts";\n\nconst site = lume();\nsite.use(vento());\n\nexport default site;\nVento template engine has been created by me (Óscar Otero, also the Lume\ncreator) and I'm thinking of making it the default engine (replacing Nunjucks)\nat some point. I would like to know your thoughts.
\nSee more info about this plugin in the\ndocumentation.
\nUntil now, the lightningcss plugin only transformed the CSS code but\nit couldn't bundle it (inline the\n@import'ed styles to output a single file with all the code). The reason is\nLightningCSS is an NPM package that didn't work properly on Deno due the lack of\nsupport of some NAPI functions so Lume had to use the WASM version\nthat only transform the code but not bundle it.
Deno team finally improved support for NAPI and now it's possible to use the NPM\nversion of lightningcss and bundle the code. In fact, as of Lume 1.18 the\nplugin bundles the CSS code by default.
If you want to disable the bundler and only transform the code (back to the\nprevious behavior), just add a includes: false option in the _config file:
import lume from "lume/mod.ts";\nimport lightningcss from "lume/plugins/lightningcss.ts";\n\nconst site = lume();\nsite.use(lightningcss({\n includes: false, // Disable the bundler\n}));\n\nexport default site;\nThanks to @kwaa for working on the JSONC and TOML\nsupport for Lume. Now you not only can use YAML format in the front matter but\nalso JSON and TOML formats.
\nTo use JSON (or JSONC) in the front matter:
\n{\n "title": "Hello world"\n}\n\nPage content\nTo use TOML in the front matter:
\n+++\ntitle = Hello world\n+++\n\nPage content\nJSONC is enabled by default for pages and data files. So any file with the\nextension .tmpl.jsonc or a data file _data.jsonc or _data/*.jsonc is\nloaded by default.
TOML files can also be used for pages and data files but this format is not\nenabled by default (probably it will in Lume 2.0). To enable it, just import the\nplugin in the _config file:
\nimport lume from "lume/mod.ts";\nimport toml from "lume/plugins/toml.ts";\n\nconst site = lume();\nsite.use(toml());\n\nexport default site;\nSee the\nCHANGELOG.md file\nfor the full list of changes.
\n","date_published":"Thu, 22 Jun 2023 12:51:21 GMT"},{"id":"https://aoba-test.netlify.app/posts/lume-1.17.0-release-notes/","url":"https://aoba-test.netlify.app/posts/lume-1.17.0-release-notes/","title":"Lume 1.17.0 release notes","content_html":"This is a brief summary of the main changes introduced in Lume (1.17.0).
\n\nfeedOne of the most common things to do when developing a web site is the RSS feed.\nIt's almost mandatory for blogs but it can also be useful for any website with\nsome regular updates. In the same way that there was a\nsitemap plugin to build the sitemap of\nthe site, Lume 1.17 introduces the new\nfeed plugin to build a feed in RSS or\nJSON Feed format.
🔥🔥 Thanks to\nadb-sh for his initial pull request.
\nTo use this plugin, just import it in your _config.ts and configure it:
import lume from "lume/mod.ts";\nimport feed from "lume/plugins/feed.ts";\n\nconst site = lume();\n\nsite.use(feed({\n output: ["/posts.rss", "/posts.json"],\n query: "type=post",\n sort: "date=desc",\n limit: 10,\n info: {\n title: "My awesome blog",\n description: "Post updates of my blog",\n },\n items: {\n title: "=title",\n description: "=excerpt",\n },\n}));\n\nexport default site;\nIn this example, Lume creates two Feed files defined in the output key:\n/posts.rss (in RSS format) and /posts.json (in\nJSON Feed format). The file extensions determines\nthe format to use.
The query, sort and limit options are the same as you typically use in the\nsearch.pages() API.
The info object has the description of the Feed (like title, description, etc)\nand the items object the description of every item in the Feed. Both objects\nuse the\nsame aliases as metas plugin:\nany value starting with = represents a variable name that will be used to\nextract this info. In our example, the title and description is the same as the\ntitle and excerpt variables of the page.
It's also possible to extract the info using CSS selectors. For example, let's\nsay we want to generate a RSS with the same content as the div .post-content.\nWe just have to start the value of the code with $:
import lume from "lume/mod.ts";\nimport feed from "lume/plugins/feed.ts";\n\nconst site = lume();\n\nsite.use(feed({\n output: ["/posts.rss", "/posts.json"],\n query: "type=post",\n sort: "date=desc",\n limit: 10,\n info: {\n title: "My awesome blog",\n description: "Post updates of my blog",\n },\n items: {\n title: "=title",\n description: "=excerpt",\n content: "$.post-content",\n },\n}));\n\nexport default site;\nIf you want to create more than one feed, just use the plugin once per feed:
\nsite.use(feed({\n output: "/posts.rss",\n // Posts feed configuration\n}));\n\nsite.use(feed({\n output: "/articles.rss",\n // Articles feed configuration\n}));\nIn this version, Lume got a big refactoring of how the files in the src\ndirectory are scanned, loaded and refreshed. This change fixed some existing\nbugs and open the door for new possibilities, because now it will be easier to\nimplement new features.
Thanks to this refactoring, SASS plugin supports\nremote files, so you can load your\nvariables and mixings from a remote URL to use them in your build:
\nimport lume from "lume/mod.ts";\nimport sass from "lume/plugins/sass.ts";\n\nconst site = lume();\nsite.use(sass());\n\nsite.remoteFile(\n "/_includes/variables.scss",\n "https://example.com/theme/variables.scss",\n);\n\nexport default site;\n@import "variables.scss";\n\nbody {\n color: $main-color;\n}\nThe're a breaking change in the SASS plugin: the includes option accepts only\na string instead of an array of paths.
The on_demand plugin allows to render a\npage on request time, instead of build time. This is useful to insert dynamic\ncontent and reduce the build time specially for big sites. Lume 1.17 introduces\na way to insert additional variables to the page before rendering.
\nThe onDemand plugin has the new option extraData which accepts a function\nthat must return an object with the extra data to be passed to the page. For\nexample, let's say we want to pass the search parameters of the request's url:
import lume from "lume/mod.ts";\nimport onDemand from "lume/plugins/on_demand.ts";\n\nsite.use(onDemand({\n extraData(request: Request) {\n const searchParams = new URL(request.url).searchParams;\n const params = Object.fromEntries(searchParams.entries());\n\n return {\n params,\n };\n },\n}));\n\nexport default site;\nNow, the on demand pages will have the params key with the search params\nvalues. For example, in a Nunjucks page:
---\nlayout: layout.njk\nondemand: true\nurl: /example/\n---\n\nHello {{ params.name }}\nThe URL /example/?name=Óscar will return Hello Òscar.
Note that on-demand pages works better on Deno CLI than Deno Deploy. There's a\npost explaining the current limitations on Deno Deploy,\nso you should consider this plugin as highly experimental.
\nA few versions ago, Lume removed the ability to be installed globally (with\ndeno install ...) in benefit of deno task. Some old files were keept for\nbackward compatibility when upgrading from an old version. Now these files were\nremoved (ci.ts, install.ts). If you get any issue running Lume (specially in\nCI 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\nupdates, etc. See the\nCHANGELOG.md file\nfor the full list of changes.
\n","date_published":"Fri, 05 May 2023 00:00:00 GMT"},{"id":"https://aoba-test.netlify.app/posts/lume-1.16.0-release-notes/","url":"https://aoba-test.netlify.app/posts/lume-1.16.0-release-notes/","title":"Lume 1.16.0 release notes","content_html":"Hi everyone! This is a brief summary of what the new version of Lume\n(1.16.0) brings.
\n\nmultilanguage plugin refactorThe multilanguage plugin was created to simplify the creation of sites in\nmultiple languages. But the way it worked so far was a bit confusing and not\nvery practical. Lume 1.16 introduce some changes that (sadly) breaks some\ncompatibility with the previous version. But I think the new behavior is much\nmore clear and easy to use and understand. Some of the most important changes:
In the old plugin, each page defined its own languages. There wasn't a place to\nspecify the available languages for the whole site. This makes the plugin to\nwork inconsistently for each page, because it depended on the number of\nlanguages defined in every case. The new version requires to specify the\nlanguages in the _config file, so it will work in the same way with all pages.
\nsite.use(multilanguage({\n languages: ["en", "gl"],\n}));\nThe new plugin automatically prepend the /${lang}/ prefix to all urls. If you\nhave the following page:
---\nlang: en\nurl: /hello-world/\n---\n\n# Hello world\nThe output file is /en/hello-world/. This ensure all pages in the same\nlanguage are in the same subdirectory.
It's possible to define a language as default, so all pages in this language\nwon't have this prefix. For example, let's say our site is in english and\ngalician but we want to set english as the main language:
\nsite.use(multilanguage({\n languages: ["en", "gl"],\n defaultLanguage: "en",\n}));\nWith this configuration, the english version of the page is /hello-world/ but\nthe galician version is /gl/hello-world/.
id to relate pages in different languagesIn the old version, to setup multiple versions of the same page in individual\nfiles, you had to follow some strict instructions:
\nFor example:
\n- /about-me_en.md\n- /about-me_gl.md\nThe new plugin removes this behavior. You have to use the id variable to\nrelate different pages.
For example, the english version:
\n---\nlang: en\nurl: /about-me/\nid: about\n---\n\n# About me\nThe galician version:
\n---\nlang: gl\nurl: /acerca-de-min/\nid: about\n---\n\n# Acerca de min\nThe new plugin interprets these two pages as the same content but in different\nlanguages, because they have the same id (about). You don't need to have all\nfiles in the same folder with a specific name.
See the\ncomplete plugin documentation.
\nnav pluginThe nav plugin builds automatically a menu of your site using the URLs to\ndefine the hierarchy. For example, let's say we have a site which exports the\nfollowing 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\nsearch but intended for navigation stuff.\nThe nav variable has some useful functions:
The nav.menu() function returns an object with the site structure, so you can\nbuild a tree menu:
const tree = nav.menu();\n\nconsole.log(tree);\n\n{\n slug: "",\n data: Data,\n children: [\n {\n slug: "articles",\n data: Data,\n children: [\n {\n slug: "first-article",\n data: Data,\n },\n {\n slug: "second-article",\n children: [\n {\n slug: "chapter-1",\n data: Data,\n },\n {\n slug: "chapter-2",\n data: Data,\n },\n ],\n },\n ],\n },\n ];\n}\ndata property contains the page data object. So you can access to any\npage variable like data.title or data.url.second-article doesn't have the data value because\nthere isn't any page with the url /articles/second-article/. Note that there\nare pages inside this url (/articles/second-page/chapter-1/ and\n/articles/second-page/chapter-2/) that do have the data value.The nav.breadcrumb() function returns all parent pages of a specific page. For\nexample:
const breadcrumb = nav.breadcrumb("/articles/second-article/chapter-2/");\n\nconsole.log(breadcrumb);\n\n[\n {\n slug: "chapter-2",\n data: Data,\n },\n {\n slug: "second-article",\n children: ...\n },\n {\n slug: "articles",\n data: Data,\n children: ...\n },\n {\n slug: "",\n data: Data,\n children: ...\n },\n]\nYou can see an example of the nav plugin in the\nSimple Wiki theme.
\nnav.menu()\n(see the code)nav.breadcrumb()\n(see the code)See the plugin documentation for more details.
\ncopyRemainingFiles functionUntil now, the only way to copy static files was using the site.copy()\nfunction, that allows to specify a file/folder or an array of extensions. This\nworks fine if you know in advance all files that must be copied, because they\nare in a specific folder like /static or have a known extension (.jpg,\n.png, etc).
But it's not practical when your static files are distributed in random folders\nor can have any extension. For example, imagine you have a website with\narticles, and every article is stored in it's folder that can contain static\nfiles of any extension:
\n|_ articles/\n |_ article-1/\n | |_ index.md\n | |_ picture.jpg\n | |_ document.pdf\n | |_ foo32.gif\n |_ article-2/\n |_ index.md\n |_ journey.mp4\n |_ download.zip\nThe site.copy() function it's not very helpful because if we copy the\n/articles/ folder, the index.md files won't be processed (they will be\ntreated as static files). We can select the files by extension with\nsite.copy([".jpg", ".pdf", ".gif", ".mp4", ".zip"]) but every time a new\nextension 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\nwhat to do, just copy it. You can include a function to filter which files\nwill be copied. For example:
site.copyRemainingFiles((path: string) => path.startsWith("/articles/"));\nNow, only the remaining files inside the /articles/ folder will be copied.
More info\nin the documentation site.
\npage.data.children propertyLet's say you have a blog and want to list all posts with their content. It's\npossible with this code:
\n{% for post in search.pages("type=post") %}\n <h1>{{ post.data.title }}</h1>\n {{ post.data.content | md | safe }}\n{% endfor %}\nIf the post are written in Markdown, the variable post.data.content of the\npage has the unrendered markdown code, so you have to use the md filter to\nrender it to HTML. This has the drawback of every post need to be rendered\ntwice, 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\nconvert mdx code to HTML. It's possible to get the rendered content of the\npage from post.content but it includes not only the HTML of the post but also\nthe layout used in this page.
As of version 1.16, Lume will save the rendered content into the children\nproperty, so you can use it in other pages in this way:
{% for post in search.pages("type=post") %}\n <h1>{{ post.data.title }}</h1>\n {{ post.data.children | safe }}\n{% endfor %}\nThe content will be rendered only once and no filter is needed.
\nThere are more interesting things in Lume v1.16.0. See the\nCHANGELOG.md file\nfor the full list of changes.
\n","date_published":"Tue, 21 Mar 2023 00:00:00 GMT"},{"id":"https://aoba-test.netlify.app/posts/lume-1.15.0-release-notes/","url":"https://aoba-test.netlify.app/posts/lume-1.15.0-release-notes/","title":"Lume 1.15.0 - Release notes","content_html":"The version 1.15.0 is full of exciting new features.
\n\nHugo has a nice feature called archetypes,\ntemplates used when creating new content. The most obvious example is a post:\ninstead of creating a new markdown file from scratch everytime you want to\ncreate a new post, you can run an archetype that creates the post file for you\nwith a preconfigured front matter and content.
\nIn Lume, an archetype is just a JavaScript or TypeScript file that export a\nfunction returning an object with the file path and the file content. The\narchetype must be saved in the _archetypes directory, inside the src folder.\nFor example:
// _archetypes/example.js\n\nexport default function () {\n return {\n path: "/pages/example.md",\n content: "Content of the file",\n };\n}\nThe archetypes are invoked with the command\ndeno task lume new [archetype-name] (or lume new [archetype-name] with the\nnew Lume CLI). If you run lume new example to run this\narchetype, the file /pages/example.md will be created.
See the archetypes documentation to\nlearn more about how to generate different formats, pass arguments or create\nmultiple files.
\nTailwind support is a recurring request for Lume.\nUntil now it was not possible to use Tailwind in Deno, so the only alternative\navailable was Windi CSS.
\nThe support of npm: packages in Deno allowed to use many NPM packages that\nuntil now only work on Node. Still, there were errors in Tailwind due the\nacorn-node dependency that doesn't\nwork on Deno.
The @lumeland organization in\nNPM contains modified versions of the packages that don't work in Deno.\n@lumeland/tailwindcss\nis the same code as tailwindcss\nbut replacing that dependency. When this is fixed in the official library, this\nmodified version will be deprecated.
The Tailwindcss plugin depends on postcss, so you need to use both plugins in\nthis exact order:
import lume from "lume/mod.ts";\nimport tailwind from "lume/plugins/tailwindcss.ts";\nimport postcss from "lume/plugins/postcss.ts";\n\nconst site = lume();\n\nsite.use(tailwind());\nsite.use(postcss());\n\nexport default site;\nThe function site.data() allows to insert arbitrary data in your site from the\n_config.ts file:
site.data("layout", "main.njk");\nThe context of this data is global: is available to all pages of the site. It's\nequivalent to having a _data.* file in the root of your site. As of Lume\n1.15.0, it's possible to specify the directory of the data in the third\nargument, for example:
site.data("layout", "main.njk", "/posts");\nNow, the layout value is available only to the pages inside the /posts\ndirectory. Equivalent to creating a /posts/_data.yml file with this value.
You can assign data not only to directories but also to specific files:
\nsite.data("layout", "main.njk", "/posts/hello-world.md");\ndateThe date plugin use the\nDeno version of date_fns to transform\nthe dates. That version wasn't updated in 2 years so I decided to switch to\nthe Node version. Everything should\nwork fine, the only difference is the locales configuration, that need to be\nimported from npm in the _config file. For example, if you have this\nconfiguration:
site.use(date({\n locales: ["gl", "pt"],\n}));\nYou need to change it to:
\nimport gl from "npm:date-fns/locale/gl/index.js";\nimport pt from "npm:date-fns/locale/pt/index.js";\n\n//...\nsite.use(date({\n locales: { gl, pt },\n}));\nsass plugin uses now a\nmodified version of the\nofficial NPM package.relations plugin has been improved and there are some breaking changes\nin the configuration API.\nSee the plugin page for the updated\ndocumentation.See the\nCHANGELOG.md file\nfor the full list of changes.
\n","date_published":"Tue, 10 Jan 2023 00:00:00 GMT"},{"id":"https://aoba-test.netlify.app/posts/lume-cli/","url":"https://aoba-test.netlify.app/posts/lume-cli/","title":"Lume CLI","content_html":"Happy new year, Lumers!
\n2022 was a great year for Lume, it reached to 1K stars in GitHub and many of you\nhave collaborated in form of pull requests, promoting Lume in your blogs and\nsocial networks or\neven sponsoring me. I want to thank\nyou and promise to keep working hard to make Lume even better.
\n🔥🔥🔥🔥🔥🔥🔥🔥🔥
\n\nThe best way to run Lume is using the Deno tasks. It's the most portable way to\nrun Lume without installing anything else but Deno, and it ensures that the Lume\nversion is the same as specified in the import_map.json file. In fact,\nthere's a plan to remove the CLI interface\ncompletely.
The only drawback of using Deno tasks is they are more verbose to type. Instead\nof simply running lume -s or lume run my-script you have to type\ndeno 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\nergonomic way to run the commands, I have released the new\nLume CLI.
\nTo install it, just run:
\ndeno install --allow-run --name lume --force --reload https://deno.land/x/lume_cli/mod.ts\nLume CLI is just a small script to add the deno task words at the beginning of\nyour lume commands. For example, if you run lume -s, the CLI will run\ndeno task lume -s.
It's an independent module, separated from the Lume repository, so it's up to\nyou to use it or not.
\nIt also includes two additional commands:
\nlume init: To initialise Lume in the current directory. It's like running\ndeno run -Ar https://deno.land/x/lume/init.ts.lume ugrade-cli: As you may guess, it will upgrade the Lume CLI to the\nlatest version.Lume CLI combines the best of the two worlds and opens the door to removing the\nold CLI interface in the Lume repo sometime soon.
\n","date_published":"Fri, 06 Jan 2023 00:00:00 GMT"},{"id":"https://aoba-test.netlify.app/posts/lume-1.14.0-release/","url":"https://aoba-test.netlify.app/posts/lume-1.14.0-release/","title":"Lume 1.14.0 is out","content_html":"Lume 1.14.0 was released. This is a list of the main changes and new features.
The functions site.process() and site.preprocess() are used to modify pages\nafter or before rendering. For example, to process the HTML pages, you can do:
site.process([".html"], (page) => my_processor(page));\nThis callback is executed once per page, so if you have 200 pages, the callback\nis executed 200 times.
\nThis is great to transform pages individually, but sometimes it's better to run\nthe function only once to all pages at the same time. Two new functions were\nadded for this purpose: processAll() and preprocessAll(). They are similar\nto process() and preprocess() but will receive all matched pages in the\nfirst argument:
site.processAll([".html"], (pages) => {\n pages.forEach((page) => my_processor(page));\n console.log(`Processed ${pages.length} HTML pages!`);\n});\nIn previous versions, the only way to do something like that was through events\nlike afterRender, beforeRender, beforeSave, etc. The advantage of using\nthe new processAll and preprocessAll is they respect the order of the other\nprocessors:
site.process([".html"], first_processor);\nsite.processAll([".html"], second_processor);\nsite.process([".html"], third_processor);\nIn this example, second_processor is run after first_processor and before\nthird_processor.
hooksHooks are functions registered by some plugins that can be invoked by other\nplugins or by yourself in the _config file. Hooks are stored in site.hooks\nand are useful to change a plugin configuration after the installation. For\nexample, the postcss plugin sets the hook addPostcssPlugin. You can create a\nLume plugin to, for example, minify the css code with\nCSS Nano:
import cssnano from "npm:cssnano@5.1.14";\n\nexport default function () {\n return (site) => {\n if (!site.hooks.addPostcssPlugin) {\n throw new Error("This plugin depends on postcss");\n }\n\n site.hooks.addPostcssPlugin(cssnano);\n };\n}\nNow, you can use this plugin in the _config.ts file:
import lume from "lume/mod.ts";\nimport postcss from "lume/plugins/postcss.ts";\nimport nanocss from "./plugins/nanocss.ts";\n\nconst site = lume();\n\nsite.use(postcss());\nsite.use(nanocss());\n\nexport default site;\nsplitting mode for esbuildCode splitting is a bundle technique\nthat creates separate files with common code shared by multiple entry points.\nFor example, if both entry points a.ts and b.ts imports c.ts, instead of\nincluding the c.ts code in both files (which would be duplicated), the code is\nsaved into a chunk file that is imported by both files.
To generate the chunk files, we need to know all entry points first. But\nthanks to the implementation of processAll() function (previously explained)\nthis is now possible in Lume. To enable the splitting mode, just need to\nconfigure the esbuild plugin in this way:
site.use(esbuild({\n options: {\n splitting: true,\n },\n}));\nmetas pluginA couple of improvements have been added to metas:
mergedKeysThe metas plugin needs a mergedKeys to customise the merging mode of the\nmetas key:
metas:\n site: Site title\n icon: /img/icon.png\n lang: en\n\n# Customise the merging mode of "metas"\nmergedKeys:\n metas: object\nYou no longer need to add this value manually. The plugin inserts it\nautomatically for you.
\nField aliases are the new way to reuse a value in the metas. For example:
title: This is the title\n\nmetas:\n title: "=title" # Alias to the title value\nAny value starting with = is considered an alias to another field. You can use\ndots for subvalues:
title: This is the title\nintro:\n text: Page description\nmetas:\n title: "=title"\n description: "=intro.text"\nField aliases are way more powerful than the defaultPageData option of the\nplugin, which is deprecated and will be removed in the future.
_data files.prism pluginThe prism plugin now loads the\nPrism library from npm:. This change removes the\nlanguages option so if you need to load additional languages, you have to\nimport them in your _config.ts file:
import lume from "lume/mod.ts";\nimport prism from "lume/plugins/prism.ts";\n\n// Additional prism languages\nimport "npm:prismjs@1.29.0/components/prism-less.js";\nimport "npm:prismjs@1.29.0/components/prism-git.js";\n\nconst site = lume();\nsite.use(prism());\n\nexport default site;\nThe good news is you can also load plugins.
\nfilter_pagesThis plugin is the first step to deprecate the --dev mode of Lume (that\nignores the pages with draft=true). The new plugin filter_pages filters\npages using a callback and provides more flexibility. For example, let's say you\nwant to ignore the draft pages in the production environment:
import lume from "lume/mod.ts";\nimport filter_pages from "lume/plugins/filter_pages.ts";\n\nconst site = lume();\nconst isProd = Deno.env.get("DENO_ENV") === "prod";\n\nsite.use(filter_pages({\n fn: (page) => !isProd || !page.data.draft,\n}));\n\nexport default site;\nSee the\nCHANGELOG.md file\nfor the full list of changes.
\n","date_published":"Mon, 12 Dec 2022 00:00:00 GMT"},{"id":"https://aoba-test.netlify.app/posts/ondemand-plugin-november-2022/","url":"https://aoba-test.netlify.app/posts/ondemand-plugin-november-2022/","title":"How to use the \"on demand\" plugin in November 2022","content_html":"The on_demand plugin is the attempt of\nLume to provide some server-side rendering behaviour to a static site. The idea\nis simple: omit some pages in the build process (with ondemand: true) in order\nto build them when they are requested.
This allows insert dynamic content in the pages like\nin this example, a site with the pages\nshowing the current time. You can see the\ncode repository, where the\ncurrent time is defined as a\nhelper in the _config.ts file\nand then\ncalled in the Nunjucks layout\nused by both pages.
This plugin was tested only in Deno Deploy but it should work on any hosting\nwith Deno. But it is not all rosy in the garden, because Deno Deploy has some\nlimitations that makes more difficult to use this plugin, compared with the Deno\nCLI that you have installed locally:
\nOne of the\nmost requested features\nin Deno Deploy is the ability to import modules dynamically. One year and half\nsince the issue was created, it's still not possible and looks like it won't be\nin the short term. Lume uses dynamic imports to load pages and data in\nJavaScript, JSX and TypeScript, so if your on demand pages use any of these\nformats, they will fail on Deno Deploy. The only way to skip this limitation is\nby generating a file that imports statically all files that, under normal\nconditions, would be imported dynamically (this file is generated automatically\nby the ondemand plugin).\nIt's not an elegant solution but it's the only solution that works at this\nmoment.
\nAs of version 1.12.0, Lume uses npm: modules for some dependencies. NPM\nespecifiers\nare not yet supported in Deno Deploy.\nFortunately we can use import maps to use the esm.sh version of the NPM\npackages. In the repository of the plugin demo, you can\nsee the import_map.json file\nneeded 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\nlimitations disappear in the short term (I guess NPM modules will be supported\nsoon). If you know of other hosting providers with Deno support and you get the\non demand plugin to work there, please, let me know.
I'm happy to announce that Lume 1.13.0 was released with some interesting\nadditions and changes. Let's see the highlights.
MDX support for Lume was requested for a long time. Now\nthat Deno can handle npm imports, it's more easy to bring support for this\nlibrary. The new mdx plugin allows to create your pages in .mdx, so you can\ncombine 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\nthe JSX plugins available (jsx to use React, jsx_preact to use Preact). This\nis an example with Preact:
import lume from "lume/mod.ts";\nimport jsx from "lume/plugins/jsx_preact.ts";\nimport mdx from "lume/plugins/mdx.ts";\n\nconst site = lume();\n\nsite.use(jsx());\nsite.use(mdx());\n\nexport default site;\nNow you can create .mdx files that imports JSX components or use the Lume's\ncomponents from the global comp variable:
---\ntitle: Hello world\ndescription: This is a description\n---\n\nimport Image from "./_includes/Image.tsx";\n\n<comp.Header title={title} description={description}/>\n\n## Hello world\n\nThis is a markdown file with the title **{ title }**.\n\n<Image alt="foo" />\nSee more info in the documentation
\nsitemap pluginThe sitemap plugin was created by Jrson some\ntime ago in the\nexperimental plugins repo.\nIt creates a sitemap.xml file and a robots.txt file with a link to the\nsitemap file.
This plugin is now included in Lume 1.13.0, so you can import it via\nlume/plugins/sitemap.ts.
See more info in the documentation
\nmultilanguage pluginThe multilanguage plugin allows to create multiple language versions of the\nsame page. In Lume v1.13.0 it's possible to save the language versions in\ndifferent files. To be identified by the plugin as language versions of the same\npage, the files must fulfill the following requirements:
lang variable defined._[lang] suffix.For example:
\n|_ /posts\n |_ /my-first-post_en.md\n |_ /my-first-post_es.md\nThese two files contains the same post but in different languages and Lume will\ngenerate 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\nalready have a site with only one language and want to add other languages\nprogressively without affeting to the existing urls. For example:
\n|_ /posts\n |_ /my-first-post.md\n |_ /my-first-post_es.md\nIn this case, Lume detects they are the same posts but the URLs generated are\n/posts/my-first-post/ and /es/posts/my-first-post/.
page.dest and page.updateDestAll 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\ndefined) or the source file name. More info\nin the Lume docs.
The problem is whenever the URL of a page is changed, it's necessary to change\nthe value in two places, page.data.url and page.dest. For example, a SASS\nplugin that modifies the extension of the files from .scss to .css:
// Extremely simplified code:\nsite.process([".scss"], (page) => {\n page.content = processSASS(page.content);\n\n // Change the page URL\n page.data.url = page.data.url.replace(/\\.scss$/, ".css");\n\n // Change the destination extension\n page.dest.ext = ".css";\n});\nThere's the page.updateDest function that changes the page.dest and\npage.data.url values accordingly, ensuring both properties are consistent:
// Extremely simplified code:\nsite.process([".scss"], (page) => {\n page.content = processSASS(page.content);\n\n // Change the page URL and destination\n page.updateDest({ ext: ".css" });\n});\nI never felt confortable with this, because it's duplicating the same value in\ntwo different places. Originally it has been created in this way because they\nhave different purposes and they can have different values (like a page with the\nurl /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\nprobably removed in 1.14.0). Now you only have to change the value in one place:\npage.data.url.
More simple and intuitive.
\nreturnPageData to search helperThe global helper search.pages() returns an array of pages. But in most cases\nyou don't need the page instance, only its data. The new returnPageData option\nallows to change this behavior to return only the page.data object. This will\nbe the default behavior in Lume 2.0, but for compatibility it's disabled by\ndefault. See\nmore info in this issue.
To enable it, just configure the plugin in the _config.ts file.
import lume from "lume/mod.ts";\n\nconst search = { returnPageData: true };\n\nconst site = lume({}, { search });\n\nexport default site;\nOnce configured, the following code:
\n{% for article in search.pages("type=article", "date=desc") %} \n<a href="{{ article.data.url }}">\n <h1>{{ article.data.title }}</h1>\n</a>\n{% endfor %}\nneeds to be changed to:
\n{% for article in search.pages("type=article", "date=desc") %} \n<a href="{{ article.url }}">\n <h1>{{ article.title }}</h1>\n</a>\n{% endfor %}\nno-html-extension option for prettyUrlsPretty URLs configuration allowed the no-html-extension value. It exports the\npage as regular html (like /article.html) but the url of these pages are\n/article (without extension). You can see more info\nin this issue.
This option was removed in Lume 1.13.0 because it's not needed. If you want this\nfunctionality, just use the modify_urls plugin to remove the extension to the\nHTML links:
import lume from "lume/mod.ts";\nimport modifyUrls from "lume/plugins/modify_urls.ts";\n\nconst site = lume({\n prettyUrls: false, //To export the pages as example.html\n});\n\nsite.use(modifyUrls({\n fn: (url) => url.replace(/\\.html$/, ""),\n}));\n\nexport default site;\nemptyDest optionLume needs to load all pages in order to build the site. This may be a problem\nfor large sites with 50K or more pages that cause out of memory issues.
\nA solution is to build these large sites in several steps, creating different\nbuilds exporting to the same dest directory, so the site can be built\nincrementally. Lume automatically empty the dest folder before any build, so\nthe new emptyDest option allows to change this behavior:
const site = lume({\n emptyDest: false, // Don't empty the dest folder\n});\nLume can\nextract dates from the page's filename\n(for instance 2022-10-02_post-title.md).
If there's a number (like 23_post-title.md), it's interpreted as a timestamp.\nThis behavior was removed because it's a too generical pattern\n(See this issue). If you need\nthis feature back, you can create a preprocessor for that:
site.preprocess([".md"], (page) => {\n const [date, url] = myCustomFileParse(page.data.url);\n page.data.date = date;\n page.data.url = url;\n});\nSee the\nCHANGELOG.md file\nfor a full list of changes.
\n","date_published":"Wed, 16 Nov 2022 00:00:00 GMT"}]}