Adding data to external files

Data in the frontmatter can be helpful for writing content close to the page, but sometimes having discreet data files can keep the page files much cleaner. We can move data from the frontmatter to specific files along the 11ty Data Cascade.

Creating a template data file for the home page triptych

Let’s start by moving the triptych data from the frontmatter into a data file for the home page. To create a template data file, we create a file with a specific naming pattern. For JSON files, we use <template-name>.json or <template-name>.11tydata.json. For JavaScript data files—which we’ll dive into later in this chapter—the 11tydata string is required for template or directory data.

For this example, we’ll use a JSON file to store the array we need for the home page. Create a file in the src directory named index.json. If you’re currently running 11ty, the terminal will show an error that the JSON is not formatted properly. That’s because 11ty already recognizes the data file, but it’s blank, and therefore incorrectly formatted for JSON.

For the triptych, insert the following JSON into the file you just created:

{
    "triptychs": [
        {
            "headline": "Triptych 1",
            "content": "Triptych 1 content!"
        },
        {
            "headline": "Triptych 2",
            "content": "Triptych 2 content!"
        },
        {
            "headline": "Triptych 3",
            "content": "Triptych 3 content!"
        }
    ]
}

Once this is saved, the browser will refresh, and now we have six triptych items! When possible, 11ty will attempt to merge data from various sources instead of overriding it. So, for the triptych key, it knows that there are two arrays and adds them together. Note the template data file’s array content comes first. That’s because the template data is added first in the data cascade and then the frontmatter is added. If you insert a title string into the template data file, you won’t see the title change. That’s because the frontmatter takes precedence in the cascade and strings won’t be merged like arrays.

The array merge is a nice feature, but we don’t want six items. For now, delete the frontmatter from the home page. The home page file is now much more readable and more data can be added to the data file and not overwhelm the page template. The same could be done for data for the About page as well. Follow the naming convention with about.json and add any data you’d like.

If we had multiple pages with data files for each page, that would be difficult to manage. To fix this, we can use directory data files.

Moving the About page to its own directory

11ty allows for a deeper directory structure in the project to keep things neat but also adds additional power to pages that should be grouped together.

To start, create a new directory in the src directory. Name this directory about and move about.json and about.md into it. 11ty will recognize that the about.md file is meant to be the root of that directory and automatically uses that file for the /about/ route on our site. It will also accept index.md as the main file for this route. To keep things obvious, let’s change about.md to the index.md filename.

A note of caution on filenaming

While 11ty allows the use of the about.md filename, it’s often better to go with index.md for this file. By using about.json, we’re telling 11ty to treat the data in about.json as directory data. If we want template data for the About page, we need it to be index.md with index.json as the data file. For this example, this is unnecessary, but it can be important for bigger projects with a larger data structure.

The about.json file can now provide data for any page within the about directory. Let’s add a History page to our About section.

Create a new file in the about directory and name it history.md.

Add some Markdown to the file and save it. When 11ty rebuilds the site, there will now be a route at /about/history/. This page will only display the Markdown you added to the file. In order to take advantage of the layout and other data, the layout path needs to be added. Instead of recreating reusable data, let’s move certain data to the directory data file. Both the layout data and the pageId data may need to be used by any page in the About section, so let’s add those two pieces of data to the about.json file:

{
    "layout": "layouts/base.html",
    "pageId": "about"
}

Once that’s saved, the page will have the header and footer, as well as the correct navigation item selected. We’re still missing a banner. To add the banner, create the frontmatter in the History page. This ensures that the banner content is unique for each page:

---
title: "History"
bannerContent: "This is a little paragraph to start talking
  about the history of the company."
---
## The page content can go here
It can use any markdown, since we're in a markdown page. Like [an anchor](https://packtpub.com) or **bold text**.

We’ll dive deeper into directory data when creating a blog collection in Chapter 4.

While this is all good for a set of unique data, it’s often important to share data across the entire site—footers, metadata, and more are often powered by global data. Let’s add some data for all of our pages and templates.