--- title: Building a Blog with Eleventy (blind, any%) image: src: https://img.sebin-nyshkim.net/i/3163c7b0-4657-40bb-b08a-462a06d1fdd5 alt: Close-up of SVG code on a computer screen credit: Photo by Paico Oficial on Unsplash width: 1200 height: 630 type: 'image/png' tags: ["coding", "eleventy"] --- I recently felt like getting back into blogging. But setting up and maintaining WordPress felt like more than I was looking for. I was looking for something much simpler. Preferably file-based and with Markdown support. That was my introduction to Eleventy. > [!info] Update 2025-02-17 > Updated Tailwind instructions for Tailwind v4 Starting an Eleventy project is fairly straight-forward if you've ever worked with any Node.js package: 1. Create a project folder 1. Initialize a `package.json`: `npm init -y` 1. Install the package from npm: `npm install @11ty/eleventy` 1. Create a content file in [one of the supported template languages](https://www.11ty.dev/docs/languages/) 1. Run `npx @11ty/eleventy` to let Eleventy work its magic An `eleventy.config.js` file is entirely optional, but will become necessary for more complex setups down the line. But as a starter, it doesn't get any easier than this. No config, no build steps to set up, it just works(tm)! So with that in mind, let's go through the steps of learning how to go from the basics to a blog. ## Setting up `package.json` It's probably a good idea to add at least two entries to the `scripts` section of `package.json`. One is for starting the local development environment, to view the site live in a web browser and have it reload automatically after hitting save in your code editor. The other is for building a production ready build to put on a webserver. ```json "scripts": { "start": "eleventy --serve", "build": "eleventy" } ``` If you're using a code editor that has support for NPM built in (e.g. Visual Studio Code), you can easily start any entry with a simple click and get helpful debug output of what Eleventy is doing. ## Content I love Markdown as a document format! ❤️ Its syntax makes it easy to produce well-formatted documents, and it remains readable even when viewed in plain text. It has widespread support across the web and in development communities, so it was a no-brainer for me to want to write my blog posts in Markdown. Eleventy supports it as a content templating language. It's like a match made in heaven! Eleventy uses file names as basis for routing. So a file called `index.md` at the project root will become the `index.html` in the web root of the site. If you name the file something else, say `about.md`, Eleventy will output it as `about/index.html`. By default, most web servers are looking for an `index.html` file when a web browser just requests a path without an explicit file name. That's how I can have readable URLs and not having to worry about routing at the application level too much. Awesome! What I'm trying to achieve doesn't need a database, complex routing rules, or any big CMS in the backend. I just wanna put words on the internet and for that simple HTML is the best way to do that. After all the building blocks around that are put in place, I can just focus on writing the words. There's many apps on desktop and mobile that have Markdown formatting built in that allow me to work on posts at home and on the go. One such example would be Nextcloud's Notes app that uses Markdown for formatting notes. I can use something like [Iotas](https://flathub.org/apps/org.gnome.World.Iotas) or [Apostrophe](https://apps.gnome.org/Apostrophe/) on my GNOME Linux desktop to compose drafts or jot down something real quick in the [Nextcloud Notes app for Android](https://play.google.com/store/apps/details?id=it.niedermann.owncloud.notes), push the completed post written in Markdown to the Git repo, re-build the site and deploy it. It doesn't get any simpler than that! ## Layouts Markdown, as a simple markup language, is not intended to create fully compliant HTML documents however. This is where Eleventy layouts come in. Layouts can be written in [any template language Eleventy supports](https://www.11ty.dev/docs/languages/). Nunjucks (`*.njk`) seems to be a pretty popular choice in the Eleventy community, so I went with that. There's many languages available, but not as well documented as either Nunjucks or Liquid (the latter of which I've never heard of and its documentation seems equally sparse…) You can think of layouts as re-usable content wrappers. Which is great, since it spares me having to wrap all my Markdown files in the same boilerplate every time, which would be kind of a drag and detract from the whole putting my words on the internet with ease and such. Eleventy by default looks for layouts in a sub-directory called `_includes`. The naming for layout files is arbitrary, so I just went with a `base.njk` layout that holds all the default boilerplate HTML structure that will be common to all pages on the site. Since I'm using Nunjucks as my templating language for layouts, it offers me some variables inside the HTML and this is what makes this a whole lot more dynamic. ```twig {% raw %}{{ title }}{% endraw %} {% raw %}{{ content | safe }}{% endraw %} ``` The `safe` in this case is what Eleventy calls a "filter". It's basically just a JavaScript function that gets the value of the thing in front of the pipe as its first argument and does stuff to it. In this case it prevents escaping of `content` because it is already valid HTML from transforming the Markdown contents, so double-escaping that would create garbage. ## Linking content and layouts Creating a layout by itself does nothing yet, though. I have to somehow let Eleventy know that content and layout are somehow related. This is achieved by a block of YAML at the beginning of each file, which Eleventy calls *front matter*, where that information lives. In this case, any blogpost I write has to have at least a reference to a layout in the beginning: ```md --- layout: base.njk --- # Look ma! A blog post! Words words words words… ``` The path is always relative to the `layout` path variable configured in Eleventy, which by default points to `_includes`. This way {% raw %}`{{ content }}`{% endraw %} will receive the rendered output of that Markdown file. There's still one problem, though: What if not all pages on your site look exactly the same? What if you want some to look different from others? ## Layout-ception Eleventy doesn't really care what the {% raw %}`{{ content }}`{% endraw %} in a layout really is. It can even be another layout! This is what Eleventy calls "layout chaining": The rendered output of one layout becomes the content of another layout. This is what I'm doing with single blog posts (the one you're reading right now, in fact)! This allows for highly re-usable layouts and actually encourages modularity in your code structure. Suppose the layout to be chained is called `blogpost.njk` and will receive all the, well, blog posts. It could look something like this: ```twig --- layout: base.njk ---
{% raw %}{{ content | safe }}{% endraw %}
``` See what I did there? This is the whole thing! Now I just have to point every blog post to a different layout and I'm golden. ## Data files "But Sebin," I hear you say, "writing all that stuff in the beginning of each post is tedious! What if you forget to do it?" The authors of Eleventy probably thought the exact same, apparently. Introducing another Eleventy concept: **Data files!** Data files are just `*.json` files which can be used to set some or all of the common *front matter* data for every file in a directory, e.g. if all my blog posts live in a sub-directory `posts` I can put a data file in there named the same as the directory (i.e. `posts/posts.json`): ```json { "layout": "blogpost.njk" } ``` This applies the `blogpost.njk` layout to every file. But we can take this even further and do a lot more to free up some space in the actual blog post Markdown files. ```json { "layout": "blogpost.njk", "date": "Created", "permalink": "/posts/{% raw %}{{ title | slugify }}{% endraw %}/", "author": { "name": "Sebin Nyshkim", "href": "https://blog.sebin-nyshkim.net" }, "twitter": { "account": "@SebinNyshkim" }, "mastodon": { "fediverseCreator": "@SebinNyshkim@meow.social" } } ``` The `date` tells Eleventy how to resolve the date associated with a blog post, in this instance the date of when the file was created[^eleventydates]. The `permalink` variable allows me control where a post will be saved to, with the `slugify` filter taking the value of the `title` variable and making it URL friendly. And as you can see, you can add anything you want. [^eleventydates]: Specifically, the file system creation date. This can get a little tricky if you care about the accuracy of the post date, because if you were to create an empty file in the `posts` directory, Eleventy will take the exact date the file was written to disk, not the date the post was *actually published* to the site. You could get around that with `git Created` to instruct Eleventy to take the date the file was pushed to the Git repo instead, but this has [caveats](https://www.11ty.dev/docs/dates/). ## Data cascade Of particular note in this context is what Eleventy calls the *data cascade*, meaning data set earlier in the cascade gets overridden by later data. In the earlier example this would mean that if a blog post were to re-assign the `layout` variable, it would look different from any other post, even if the `*.json` data file said something else. That is because the post always comes last in the cascade. This opens up an interesting use-case, however. A friend asked me, if I'd allow guest articles on my blog and I told him I'd look into how to do that. I think this is a workable solution! If I set myself as default author in the data file, all my friend would have to do is override the author information in the blog post Markdown file: ```md --- title: How to have someone else write in your blog date: Created author: name: Not Sebin href: https://no-derg.zone twitter: account: "@FakeSebin42069" mastodon: fediverseCreator: "@FakeSebin@no-derg.zone" --- # There be no dragons here This post brought to you by the *Anti-Sebin Gang* ``` When using a more complex data structure like this, it's important to note that setting the top level object to something like `false` does not unset it. If I don't keep to the same data structure and set the individual properties to something *falsey* the data from earlier in the cascade will persist. Something worth keeping in mind! ## Styling Until now the site has no styles, which doesn't look particularly pretty. Adding styles isn't very complicated either, though. It's just one line to add to the `base.njk` layout in the page's `` section: ```twig ``` The `url` filter on the `href` attribute makes sure the resulting path will be dynamic enough that if the site were to move in a sub-directory nothing breaks. Eleventy does not process CSS files, however, so we need to tell it to do something with them. ## Configuring Eleventy Up until this point a config was entirely optional, but since we're bound to do something more mildly complex with Eleventy down the line, we might as well just add it. Eleventy's config file is named `eleventy.config.js` and the format should be immediately familiar to anybody having worked with Webpack, Vite, NextJS and the like[^eleventyconfig]: [^eleventyconfig]: Eleventy supports both CommonJS and ESM syntax. I'm using ESM syntax because it's widely adopted in the Node.js development world and is supported by Eleventy since v3 (which just so happens to have released shortly before I started this blog, fancy that) ```js export default async function(eleventyConfig) { // Access to the full `eleventyConfig` Configuration API }; ``` Unlike Webpack for example, however, the config format is pretty straight-forward. You get the entire Eleventy Configuration API interface to play with; no entire config format to figure out. With it, you can add watch targets, copy files to the output directory, add plugins, shortcodes, filters, collections and extend included libraries. This makes Eleventy extremely capable for a static site generator! ### Custom paths The config is also where the default paths of source and output directories can be adjusted. I like my work environment clean and tidy, so I'm giving the things I work with clear distinct names and places where they go: ```js export default async function(eleventyConfig) {}; export const config = { dir: { input: 'src', output: 'public', layouts: 'layouts', includes: 'includes' } }; ``` The Eleventy docs [recommend](https://www.11ty.dev/docs/config-shapes/) setting the paths outside of the callback function for order-of-operation reasons, which sounds like something I'd want to adhere to. ### Adding watch targets and pass-through copies To have Eleventy watch for changes in files and copy them over during serve and build we have the `addWatchTarget()` and `addPassthroughCopy()` helper functions. Pointing these at directories copies the entire content of that directory: ```js export default async function(eleventyConfig) { eleventyConfig.addWatchTarget('./src/css/'); eleventyConfig.addWatchTarget('./src/fonts/'); eleventyConfig.addWatchTarget('./src/img/'); eleventyConfig.addPassthroughCopy('./src/css/'); eleventyConfig.addPassthroughCopy('./src/fonts/'); eleventyConfig.addPassthroughCopy('./src/img/'); }; ``` Since Eleventy also uses `browsersync` it makes developing locally really comfortable, as the browser reloads the page automatically when I hit save in my code editor. ### Adding shortcodes Shortcodes are a really neat feature allowing me to have small reusable snippets I can call from anywhere in my templates: ```js export default async function (eleventyConfig) { eleventyConfig.addShortcode('year', () => `${new Date().getFullYear()}`); }; ``` Now I can just put {% raw %}`{% year %}`{% endraw %} anywhere and it will give me the current year for things like the copyright notice at the bottom of the page, it will update itself when the year changes. ### Adding filters You've seen filters being used with the {% raw %}`{{ content | safe }}`{% endraw %} variable in content files. The config is also where I can declare a couple of filters myself for text transformations I need in multiple places, e.g. the date on the top of posts. I can declare it with the `addFilter()` helper method: ```js export default async function (eleventyConfig) { eleventyConfig.addFilter('toDateObj', (dateString) => new Date(dateString)); eleventyConfig.addFilter('isoDate', (dateObj) => dateObj.toISOString()); eleventyConfig.addFilter('longDate', (dateObj) => dateObj.toString()); eleventyConfig.addFilter('readableDate', (dateObj) => dateObj.toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' }) ); }; ``` With this, I can now do things like {% raw %}`{{ date | readableDate }}`{% endraw %} to format a JavaScript date object instance as a nicely readable string. These are also chainable, so doing something like {% raw %}`{{ '2024-10-13' | toDateObj | readableDate }}`{% endraw %} gives me *Oct 13, 2024* from a date string the `Date()` constructor accepts[^jsdateobject]. [^jsdateobject]: The core JavaScript `Date` object is perfectly capable of formatting date and time strings. A library such as `luxon`, like it's mentioned in the Eleventy docs, is better suited when needing to do more complex things with dates like calculating durations and intervals, e.g. I wanted the post date to say something like "3 days ago" or something. ### Adding collections I like to have some tags on my posts to categorize them into topics. After all, that's what tags are for. One issue I encountered with the `tags` variable in *front matter*, however, is that it causes the tag "posts" to show up in the list of tags on every post, which feels kind of redundant. Of course it belongs to posts, that's the majority of the content on this site! Problem is, if I remove it from *front matter* data I lose the one mechanism that gives me all posts in a *collection* I can easily loop over for generating the post listing page. Bummer! 😖 That's when I discovered I can also define collections via the Configuration API in `eleventy.config.js`, which allows me to circumvent this issue. It's like I cat eat my cake and have it, too! ```js export default async function (eleventyConfig) { eleventyConfig.addCollection('posts', (collection) => collection.getFilteredByGlob('./src/posts/*.md')); }; ``` Adding collections via the config also has other benefits like being able to pre-filter and sort them. That way they're already the way they need to be at the time of consumption in templates and layouts[^jsarraymutate]. [^jsarraymutate]: In fact, the [docs](https://www.11ty.dev/docs/collections/#do-not-use-array-reverse()) specifically tell you to avoid calling array methods on collections that mutate arrays *in place* which can have undesirable side-effects and cause you a lot of headaches. So, yeah, don't do that! ## Turning it up to 11ty At this stage the blog really started to come together. However, I still had a few requirements that were not covered by the basic package. For one I really like having callouts in case I write up tutorials that could really benefit from some notes, warnings and such. Having footnotes also would be really nice, so side-thoughts don't clutter the main text. I thought it was covered by basic Markdown, but turns out it isn't or it's part of some flavor of Markdown that Eleventy doesn't do. Syntax highlighting in code blocks are also really good for code snippet readability! Also, since this is a blog after all, it would really benefit from having an RSS feed people can subscribe to. And even though I'll try not to go too crazy on images, whenever I do decide to add some to a post, it should be light on the bandwidth, so an image processing pipeline would be pretty dope! I found all of that possible with the help of plugins for Eleventy itself and the extensible parsers it uses! ### Extending Eleventy Although Eleventy is still relatively new (v1 was released in January 2022), there's already quite a few plugins from [its creators](https://www.11ty.dev/docs/plugins/official/) and [the community](https://www.11ty.dev/docs/plugins/community/). In addition to that, it also uses parsers which are themselves very extensible. For example, rendering Markdown is done via `markdown-it` and there exist [a plethora of plugins](https://www.npmjs.com/search?q=keywords:markdown-it-plugin) to extend the Markdown syntax available to me. The handy-dandy `addPlugin()` helper method adds plugins to Eleventy: ```js import { eleventyImageTransformPlugin } from '@11ty/eleventy-img'; import { feedPlugin } from '@11ty/eleventy-plugin-rss'; import eleventyPluginLucideIcons from '@grimlink/eleventy-plugin-lucide-icons'; import eleventyPluginNavigation from '@11ty/eleventy-navigation'; import eleventyPluginSyntaxHighlight from '@11ty/eleventy-plugin-syntaxhighlight'; export default async function (eleventyConfig) { eleventyConfig.addPlugin(eleventyPluginLucideIcons); eleventyConfig.addPlugin(eleventyPluginNavigation); eleventyConfig.addPlugin(eleventyPluginSyntaxHighlight); eleventyConfig.addPlugin(eleventyImageTransformPlugin, { // Plugin options go here }); eleventyConfig.addPlugin(feedPlugin, { // Plugin options go here }); }; ``` Most plugins for Eleventy still use CommonJS in their examples, but they're still easily added by treating them like default exports using regular ESM `import` statements. Only some plugins have named exports. Some also allow for configuration, like the image transform plugin, which accepts some parameters for image sizes, formats and default attributes on `` tags. The RSS feed plugin has some required options that must be set for it to work, like the type of feed, output file name, number of entries, which collection to include, etc. The plugin's documentation will likely tell if it's configurable and which options are required and which are optional. ### Adding navigation Eleventy offers a 1st party navigation plugin. It operates on collections to generate the navigation in templates via filters. The most simple way to add navigation to a site is: ```twig Document
``` This outputs an `