TutorialBuild a blog

Unit 5: Data and collections

Use data files for site settings and navigation, list posts with collections, generate tag pages with pagination, an RSS feed and a sitemap.

In this unit you will:

  • move the site's settings and its navigation to data files,
  • list the posts with collections.post, newest first, on a blog page and on the home page,
  • generate a page per topic with pagination,
  • generate an RSS feed and a sitemap from templates.

Step 1: add the site's settingsLink to this heading

The title "My blog" and the author "Ada" are written in several files. Move them to a data file: create _data/site.yml:

_data/site.yml
title: Ada's blog
description: Notes from a web developer who is learning Douze.
author: Ada
url: https://example.com

Like _data/layout.yml in unit 4, the file is a variable named after it: site, so templates read {{ site.title }} and {{ site.description }}. site.url is the address where the site is published: the feed and the sitemap need it to write absolute links. Replace https://example.com with yours when you deploy in unit 6.

Step 2: build the navigation from dataLink to this heading

Create _data/navigation.yml, a list of links:

_data/navigation.yml
- label: Home
  url: /
- label: Blog
  url: /blog/
- label: About
  url: /about/
- label: Projects
  url: /projects/

Then replace the header and the footer with versions that read the data files:

_includes/header.html
{%- assign current = url | replace: "index.html", "" -%}
<header>
  <a class="site-title" href="/">{{ site.title }}</a>
  <nav>
    {%- for item in navigation %}
    <a href="{{ item.url }}"{% if item.url == current %} aria-current="page"{% endif %}>{{ item.label }}</a>
    {%- endfor %}
  </nav>
</header>
_includes/footer.html
<footer>
  <p>Written by {{ site.author }}. This page changed on {{ page.date | date: "%B %-d, %Y" }}.</p>
  <p><a href="/feed.xml">RSS feed</a></p>
</footer>

url is a variable of every page: its output path, such as /about/index.html. The header removes index.html to compare it with the links, and marks the link of the current page with aria-current="page".

Add the site's title and description to the base layout, and a link to the feed you will create in step 6:

_includes/base.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ title }} | {{ site.title }}</title>
    <meta name="description" content="{{ description | default: site.description }}">
    <link rel="alternate" type="application/rss+xml" title="{{ site.title }}" href="/feed.xml">
    <link rel="stylesheet" href="/styles/global.css">
  </head>
  <body>
    {% include "header.html" %}
    <main>
      {{ content }}
    </main>
    {% include "footer.html" %}
  </body>
</html>

Every page now has the title of the site in its tab, and a Blog link in its header. The Blog page does not exist yet: that is the next step.

Step 3: list the posts on a blog pageLink to this heading

Remember the tags of the posts? Douze groups the pages by tag in collections: collections.post is the list of every page tagged post, sorted by date, oldest first. Create _content/blog.md:

_content/blog.md
---
title: Blog
---
# {{ title }}

All my posts, newest first.

{% assign posts = collections.post | reverse %}
<ul class="post-list">
{%- for post in posts %}
  <li>
    <a href="{{ post.data.url | replace: "index.html", "" }}">{{ post.data.title }}</a>
    <time datetime="{{ post.data.date | date: "%Y-%m-%d" }}">{{ post.data.date | date: "%B %-d, %Y" }}</time>
  </li>
{%- endfor %}
</ul>

## Topics

{% for topic in topics %}
- [{{ topic.name }}](/tags/{{ topic.name }}/): {{ topic.description }}
{%- endfor %}

Each item of a collection has the page's variables in data: post.data.title, post.data.date, post.data.url. The reverse filter puts the newest post first.

Open http://localhost:8080/blog/: the three posts are listed, the newest first. Add a fourth post to _content/posts/ and it shows up in the list as soon as you save it.

The Topics section reads topics, a data file that you create in step 5.

Step 4: list the latest posts on the home pageLink to this heading

Replace _content/index.md, so that the home page shows the two latest posts instead of a list written by hand:

_content/index.md
---
title: Home
---
# Welcome to {{ site.title }}

{{ site.description }}

## Latest posts

{% assign posts = collections.post | reverse %}
{% for post in posts limit: 2 %}
- [{{ post.data.title }}]({{ post.data.url | replace: "index.html", "" }}): {{ post.data.description }}
{%- endfor %}

[All posts](/blog/)

Step 5: generate a page per topicLink to this heading

The posts have topic tags besides post: douze and liquid. A page per topic lists its posts. Rather than writing one page per topic, write one page that Douze paginates over a list of topics.

Create the list, _data/topics.yml:

_data/topics.yml
- name: douze
  description: Posts about Douze itself.
- name: liquid
  description: Posts about the Liquid template language.

Then create _content/tags.md:

_content/tags.md
---
title: Topic
pagination:
  data: topics
  size: 1
  alias: topic
permalink: /tags/{{ topic.name }}/
---
# Posts about {{ topic.name }}

{{ topic.description }}

<ul class="post-list">
{%- for post in collections[topic.name] %}
  <li><a href="{{ post.data.url | replace: "index.html", "" }}">{{ post.data.title }}</a></li>
{%- endfor %}
</ul>

[All posts](/blog/)

pagination splits the topics list into pages of size items: one topic per page here. alias: topic names the item of each page, and the permalink uses it to write each page to its own path, /tags/douze/ and /tags/liquid/. collections[topic.name] is the collection of that tag.

Open http://localhost:8080/tags/douze/: it lists the first two posts.

Link the topics from the posts. Replace _includes/post.html:

_includes/post.html
---
layout: base.html
---
<article class="post">
  <h1>{{ title }}</h1>
  <p class="meta">Published on <time datetime="{{ date | date: "%Y-%m-%d" }}">{{ date | date: "%B %-d, %Y" }}</time> by {{ author }}</p>
  <p class="tags">
    {%- for tag in tags %}
    {%- unless tag == "post" %}
    <a href="/tags/{{ tag }}/">#{{ tag }}</a>
    {%- endunless %}
    {%- endfor %}
  </p>
  {{ content }}
</article>

Step 6: generate an RSS feedLink to this heading

A feed is a template too. A file named feed.xml.liquid is rendered with Liquid, like a page, and written as feed.xml. Create _content/feed.xml.liquid:

_content/feed.xml.liquid
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>{{ site.title }}</title>
    <link>{{ "/" | absolute_url }}</link>
    <description>{{ site.description }}</description>
    {%- assign posts = collections.post | reverse %}
    {%- for post in posts %}
    <item>
      <title>{{ post.data.title }}</title>
      <link>{{ post.data.url | replace: "index.html", "" | absolute_url }}</link>
      <guid>{{ post.data.url | replace: "index.html", "" | absolute_url }}</guid>
      <pubDate>{{ post.data.date | date_to_rfc822 }}</pubDate>
      <description>{{ post.data.description }}</description>
    </item>
    {%- endfor %}
  </channel>
</rss>

absolute_url writes site.url before a path, and date_to_rfc822 writes a date as RSS wants it. Values are escaped as in HTML pages, which is valid XML too. Layouts apply to HTML pages only, so the feed has none.

Open http://localhost:8080/feed.xml: the feed lists the three posts with their absolute links, such as https://example.com/posts/third-post/.

Step 7: generate a sitemapLink to this heading

A sitemap lists every page of the site for search engines. collections.all has every page. Create _content/sitemap.xml.liquid:

_content/sitemap.xml.liquid
<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
{%- for p in collections.all %}
{%- unless p.data.url == "/404.html" or p.data.pagination %}
  <url><loc>{{ p.data.url | replace: "index.html", "" | absolute_url }}</loc><lastmod>{{ p.data.page.date | date_to_xmlschema }}</lastmod></url>
{%- endunless %}
{%- endfor %}
</urlset>

Open http://localhost:8080/sitemap.xml. Two pages are left out: the 404 page, and tags.md, the template of the topic pages, which collections.all holds once with the path of the template rather than one entry per topic. The feed and the sitemap are not in the collections either, because templates such as feed.xml.liquid are not pages.

See Feeds, sitemaps and other outputs, and the RSS feed and sitemap recipes, for more.

Answers
  1. site.title: the file site.yml is the variable site.
  2. By date, oldest first. The reverse filter reverses it.
  3. One per topic of _data/topics.yml, so two, written to the path of the permalink: /tags/douze/ and /tags/liquid/.

NextLink to this heading

The blog is complete. In unit 6, you will take control of how Douze builds it: add heading anchors, a table of contents, highlighted code and search, then deploy it to GitHub Pages.

Esc to close