Let's Learn 11ty Part 3: Collections, Shortcodes, Macros
Tags: webdev, tutorial, eleventy, ssg
Published: 2022-06-01 16:05:07

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

```md
---
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.

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

# Blog Home

```


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

```html
<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

![New Navigation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hbtng8rsu46156p9x3ab.png)

### 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:

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

# First Post
```

- Now modify  `blog.njk` to look like this:
```html
---
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>
```


![post list](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/anza7yonkts4yx40e2ua.png)

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](https://www.11ty.dev/docs/collections/)

---

## 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`:

```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:
```html
---
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.

```

![shortcode](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j55gisk4rkdsiisukum4.png)

## 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](https://www.11ty.dev/docs/shortcodes/)
	- I have an implementation of them on my site here: [James Midzi](https://github.com/Psypher1/eleventy-personal-site)
- 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

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

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

{% endmacro %}
```

And it would be used like this:
```html

{% 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: https://github.com/Psypher1/learneleventy
- 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**](https://twitter.com/Psypher1), [**Polywork**](https://www.polywork.com/psypher1) and [**LinkedIn**](https://www.linkedin.com/in/jamesmidzi/)