If you're like me, you've heard a lot about Eleventy, a static site generator that's been praised by a lot of really awesome people recently. However, if you're also like me, you found the documentation didn't map to how you liked to learn. It's very focused more on the tactical "what commands to run?", instead of on the "how does the system work?". I needed to understand the mental model, before getting lost in terminal.
Here's the guide I wish I had, and I hope it helps you!
I finally got a chance to use it for MakeSpace, as we were preparing the to grow the website from 2 static HTML pages to a blog with many other pages. I chose Eleventy because I liked a lot of the framing around their motivations:
The Overview page of the docs sold me, but after this page, I was completely lost, thrown into a sea of terminal commands.
At a very basic level, Eleventy works like other static site generators. It takes a folder of inputs, processes those input files, and spits out a folder of outputs, which is your final website.
Let's say you have a folder of HTML and Markdown files, like shown below. If you setup and run 11ty (I like npx @11ty/eleventy --serve, which will load up a hot reloading webserver — I recommend adding it to your package.json scripts ), it will convert each of those files into the final website, by default in a folder called _site.
Note that the non-index files have become folders, with an index.html inside, which provides cleaner URLs: makespacefoundation.org/team instead of makespacefoundation.org/team.html.
A diagram showing a folder of HTML and MD files, going through 11ty, and coming out with a _site folder.
That's basically how most static site generators work, but 11ty is different in that it's meant to be super customizable. You can change where it looks for inputs, what specific filetypes you want to process, what files to ignore, and where to export the final website. You can use a mix of templating engines. You can add "filters" to process content in the templates, like linkifying URLs in plain text. You can use JSON or Javascript functions to supply data (including fetching from APIs at build time) that generates page content. The list goes on, and having only spent a few hours with it, I'm sure there's lots more I don't know I don't know.
The docs got very confusing for me because it's generally unopinionated about how you should set up your website, and doesn't guide you through how you might think about customizing it to your needs, even though it does comes with some default behaviors. I'm going to walk you through, chronologically, how I ran into these default behaviors and changed them to suit my needs.
One of the first things I ran into was that my README.md in my Github repo was being processed into the final website as makespace.fun/readme. You can ignore specific files and folders just like .gitignore. Simply create a file named .eleventyignore and add the names of the files and folders inside the file, one on each line.
README.md
some_folder_i_want_to_ignore
I then noticed that 11ty didn't bring my styles and assets over to the final website. By default, it only looks for .html and .md files, and doesn't bring over some important things like a /css or /assets folders.
After a lot of clicking around, I found out about the .eleventy.js configuration file. You can create it pretty easily, and it's where you do a bulk of the customization.