Nuxtstop

For all things nuxt.js

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

#webdev #tutorial #eleventy #ssg
Let's Learn 11ty Part 3: Collections, Shortcodes, Macros
7 0

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 
---
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  • 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>
Enter fullscreen mode Exit fullscreen mode

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

New Navigation

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
Enter fullscreen mode Exit fullscreen mode
  • 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>
Enter fullscreen mode Exit fullscreen mode

post list

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",
    },
  };
};
Enter fullscreen mode Exit fullscreen mode

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

---
layout: base
title: Home
tags: page, add this
---

<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.
Enter fullscreen mode Exit fullscreen mode

shortcode

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 %}
Enter fullscreen mode Exit fullscreen mode

And it would be used like this:


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

{{ macro.pageHeading("Home", "Learn Eleventy")}}
Enter fullscreen mode Exit fullscreen mode

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:

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

Add comment