menu

Build your own Blog from Scratch using Eleventy

Does the command line stress you out? Have you been burned one too many times by confusing error messages and unintuitive syntax? Don’t worry, that’s pretty common. If you invest a little time learning about the command line, you can educate yourself out of those feelings and unlock a new tier of productivity.

Eleventy is a beginner-friendly static site generator that runs on the command prompt and using it will make you more productive. (A static site generator is a program that combines templates and data to create HTML.) Today we’re going to use Eleventy to build a blog web site that lets us write our content in Markdown.

Eleventy doesn’t lock you into one specific template language. Out of the box, Eleventy works with HTML, Markdown, Liquid, Nunjucks, Handlebars, Mustache, EJS, HAML, and JavaScript files. You can use one or more of these. You can mix them together.

Eleventy is gently iterative. You can migrate your existing content slowly over to use Eleventy. You can use Eleventy to migrate your content to a new template language, one template at a time.

But before we get too far along we need to have Node installed. Node comes as an installable program you can download from the web. Bask in the safety of this GUI installer and comfortably click through each wizard step with confidence.

Before we lull ourselves into a false sense of security, let’s hop on this bull and ride. We need to open our terminal, command line, or command prompt window. On a Mac this means finding the Terminal.app (usually in /Applications/Utilities/Terminal.app) and opening it. On Windows this is called cmd.exe (found in the Start Menu under Start > Program Files > Accessories > Command Prompt).

Make sure Node is installed correctly by running node --version. Eleventy requires Node 8. You’ll know if you have Node 8 or higher if the first number after the v is greater than or equal to 8. For example, if node --version returns v8.11.3, you have Node 8.

To install Eleventy, you’ll need to enter the following command in your command prompt and press enter to execute it:

If this is the first time you’ve seen a liquid template and are not familiar with the syntax, you may want to take a second and head over to the Shopify Liquid documentation to learn more. There is one main idea on display here: Double curly braces are used to output a variable (e.g. {{ pageTitle }}).

In our layout example we use {{ content }} to denote where our markdown template content will go.

Now we need to tell our blog-post.md file to use the layout. Let’s add something to the top of our file to do just that:

---layout: layout.liquid---# This is my TitleThis is a paragraph of text.

This section between (and including) the two --- marks is called YAML Front Matter. It’s a way to write data into our template file that can be used by Liquid templates. If you’ve used Jekyll this may look familiar.

The layout key tells Eleventy to look for files inside of the _includes folder to wrap around the content of the template. Specifically, we want our blog post to use the _includes/layout.liquid file as a wrapper layout.

Now, let’s move our title text into our pageTitle front matter so that it can be used in our layout file. Now our blog-post.md looks like this:

---layout: layout.liquidpageTitle: This is my Title---This is a paragraph of text.

Let’s run Eleventy again to generate our output:

eleventy

Open the output file at _site/blog-post/index.html to see what happened:

<!doctype html><htmllang="en"><head><metacharset="utf-8"><title>My Blog</title></head><body><h1>This is my Title</h1><p>This is a paragraph of text.</p></body></html>

Why not? We’re actually pretty close to making a simple blog! Let’s take it a little further, shall we? Let’s make a posts folder for our blog posts and move our blog-post.md file in there. Then add a posts/posts.json file with the following content:

{"layout":"layout.liquid"}

Instead of requiring us to edit everything in our posts folder using YAML Front Matter, this data file will apply the data inside to all of the files in our posts folder. This will work for any .json file name that matches its parent folder name (e.g. posts/posts.json or pictures/pictures.json). Read more about Template and Directory Data Files. If you use both data files and front matter, any duplicate keys in the front matter will take precedence over the data file entries.

Now try making another blog post in posts/blog-post-2.md:

---pageTitle: This is my other Title---This is another paragraph of text.

Our layout is being applied from posts/posts.json so we don’t need that in our front matter any more. We do want a pageTitle though!

Doing great so far. We have two blog posts. But if we go to the root of our site (http://localhost:8080/) there’s nothing there! Let’s add a home page that lists all of our lovely blog posts.

Open up your posts/posts.json and add a tags array to our posts data:

{"layout":"layout.liquid","tags":["posts"]}

Any time you use tags, Eleventy will make a new collection of all the pieces of content that use the same tag. Now our blog posts will be available as a collection, specifically under the data collections.posts. Read more about Eleventy Collections.

Front matter: We’re using the same layout and assigning a pageTitle used in the layout file.

Iterate over our blog posts collection using the Liquid for tag (note the new syntax using %’s): {% for post in collections.posts %} Read more about Liquid for tags.

post.url has the URL string of each blog post entry.

post.data has all the data (from all data sources including front matter and data files) used in each blog post (e.g. post.data.pageTitle)

post.date has each blog post’s file creation date. (Read more about Content Dates)

This outputs the following:

<!doctype html><htmllang="en"><head><metacharset="utf-8"><title>My Blog</title></head><body><h1>Welcome to my blog</h1><h2><ahref="/posts/blog-post/">This is my Title</a></h2><em>2018-12-28</em><h2><ahref="/posts/blog-post-2/">This is my Title 2</a></h2><em>2018-12-28</em></body></html>

You did it! It’s a blog!

To take this a bit further, check out the eleventy-base-blog project, which is a full starter project for a blog site including RSS feeds, tag pages, syntax highlighting, custom markdown plugins, and more!

You can use Netlify to very quickly put this on the web. Register and/or Log in to app.netlify.com and drag and drop our _site folder onto the web browser window to upload the contents live to the web!