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
toblog.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
Top comments (2)
Man, this is series is like a missing part of a book. Love it!
I'm glad you're finding it useful