Let's Learn 11ty Part 3: Collections, Shortcodes, Macros

So far we have look at the basic aspects of Eleventy. Let's now delve deeper into more granular details of Eleventy

Collections

In my opinion, collections are the cornerstone of Eleventy. Collections allow you group pieces of content is varying ways. This is done by using tags.

Tags in Eleventy

Tags in Eleventy work differently from tags you might have seen elsewhere. They have one purpose - to create collections. Whereas in other places you may have seen them, they are used as a hierarchy of labels for the content.

if you recall, I mentioned that we would improve our navigation. We are going to do that by making use of collections.

We will start by adding tags to our pages' YAML data

---
layout: base
title: "Home"
tags: page 
---

Do the same for the about.md file. in addition, we will make a blog.md file in the same level as our other files - the src folder.

---
layout: base
title: Blog
tags: page
---

# Blog Home

• Now let's go into _navigation.njk and change it to this:

<nav>
    {%- for item in collections.page -%}
        <a href="{{ item.url }}">{{ item.data.title }}</a>
    {%- endfor -%}
</nav>

In the code above:

• From the collections we have made (In our pages), we loop over the collection
• Then we display data from the collections in an anchor tag:
  • item.url refers to the URL relating to the page
  • item.date.title accesses the title we set in the YAML

Listing Blog Posts on Blog Home

Let's use the same concept, make some blog posts and list them on the Blog Home Page

• We'll start by changing blog.md to blog.njk - this will be necessary for what we want to do.
• Then create a blog folder in src . In it, create a few posts in it like this:

---
title: First Post
layout: base
tags: post
---

# First Post

• Now modify blog.njk to look like this:

---
layout: base
title: Blog
tags: page
---

<h1>Blog Home</h1>

<ul>
    {% for post in collections.post %}
        <li>
            <a href="{{ post.url }}">{{ post.data.title }}</a>
        </li>
    {% endfor %}
</ul>

Pretty cool, huh?

This is just a small look into collections, there is so much more you can do with the. And various ways you can make use of them: Collections Docs

Shortcodes

Shortcodes are a way to make use of reusable blocks of code. Say for example, on your site there is a structure that repeats on your site you would use a shortcode to simplify the adding of that content.

In simplest terms, a shortcode is a function

Let's have a look and make our first shortcode. Say we wanted a title and subtitle on our main pages, we could make a shortcode, like this in .eleventy.js:

/* .eleventy.js */

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("src/assets/css/style.css");
  eleventyConfig.addPassthroughCopy("src/assets/images");

  // ADD THIS
  eleventyConfig.addShortcode(
    "headers",
    (title, subtitle) =>
      `<h1>${title}</h1>
        <p>${subtitle}</p>`
  );

  return {
    dir: {
      input: "src",
      data: "_data",
      includes: "_includes",
      layouts: "_layouts",
    },
  };
};

Now, we will change index.md to index.njk and change it's contents to this:

---
layout: base
title: Home
tags: page 
---

<img src="/assets/images/learn.png" alt="">

<!-- Shortcode in use -->
{% headers "Home", "Learning SSG"%}

<br>

I am a site built with <a href="https://www.11ty.io/">Eleventy</a>

This site is my effort to understand Eleventy. I am doing so by guiding others.

Together, we will Learn Eleventy.

Notes

• There is an addition/extension of shortcodes called a PairedShortcodes, where you can do more than just what we've done here. Shortcode Docs
  • I have an implementation of them on my site here: James Midzi
• Whenever you modify a shortcode, you need to restart your development server for the changes to take effect

Macros

Macros can be used in the same we use shortcodes, what differs is their implementaion. Take for example the shortcode we just made, the macro for it would look like this

<!-- _includes/macros/headers.njlk -->
{%  macro pageHeading(heading, subheading) %}

<h1>{{heading}}</h1>
<p>{{subheading}}</p>

{% endmacro %}

And it would be used like this:

{% import "macros/headers.njk" as macro %}

{{ macro.pageHeading("Home", "Learn Eleventy")}}

My Advice

Stick to shortcodes. Macros have a tendency of becoming complicated.

If you really have to, use the common tags package insted

Conclusion

Our site is coming along nicely.

• We improved our navigation
• We looked at a way to make use of reusable data
• We added a blog section to our site

As always:

• The working repo: Part 3: Collections and Shortcodes
• The docs: https://www.11ty.dev/docs/
• The discord: https://www.11ty.dev/blog/discord/

I'll catch you all in the next one :D

Thank you for reading, let's connect!

Thank you for visiting this little corner of mine. Let's connect on Twitter, Polywork and LinkedIn