Understanding the 11ty Data Cascade

Before we can dive into the code, we need to discuss how 11ty handles data.

Much like 11ty’s template options, the way 11ty handles data is also very flexible. With that flexibility comes some extra complexity. 11ty allows you to add data at every layer of your project, in page files, layout files, directories, and globally. Based on that, there’s a specific order and precedence in which it ingests the data along the way. This is called the 11ty Data Cascade. Let’s take a look at data sources in order of highest priority to lowest priority. At each step along the way, data can either be merged or overridden.

Lowest-priority, most generic data—such as a global data file—is the first to be computed. This gives us access to that data to be used or mutated by higher-priority, more specific data—such as computed data.

Computed data

While we won’t cover computed data in this chapter, it is the data with the highest priority and the last to run. 11ty computed data is run at the page or template level and has access to various data variables that are already available. It can be used for things such as generating page permalinks, working with the navigational structure, or anything else that requires additional data to be already compiled.

Page frontmatter

We covered the frontmatter a little in Chapter 1 as a way of declaring what layout our pages will use. The frontmatter can also be used to add page-specific data to each page template. Examples include titles, publish dates, descriptions, and data required for the page, such as banner content and promotional space content.

Template data files

Template data files are specific files of JSON or JavaScript data that are paired by name with specific pages. This can make for a better developer experience than just using frontmatter data on an individual page. These data files need filenames that match the template name.

Directory data files

Directory data is shared between multiple pages in a specific directory in your project. This can be used to share things such as layouts and parent IDs between various pages within a section of your site. For deeply nested directories, the data from parent directories is also available within the deeply nested template. This data file needs to match the directory it lives within.

Layout frontmatter

Layouts in 11ty are just chained templates. So, any page or layout can have frontmatter. In the context of a layout, the frontmatter is the same as a page, but a page can override its layout. The layout frontmatter can be helpful for creating template inheritance features to show different data on each section of your site based on the layout.

Configuration API global data

You used the 11ty configuration API to set up your 11ty instance in Chapter 1, but it can also be used to store global data. The addGlobalData method on the configuration object can be used to create regular global data but is best used to create data source plugins for various APIs and add data programmatically to the 11ty data stack.

Global data files

The lowest-priority data is global data. These files are typically JavaScript or JSON files and are stored by default in the src directory of your project. This data is accessible to any template, layout, include, or page in your project. These files are great for data that should be fetched or created once and used in multiple places.

With the basics in hand, let’s begin by making our templates and includes more dynamic. To start, we’ll add individual page data that can be used in our base template, as well as in includes.