Eleventy Plugin: Collection Schemas
Enforce a typed frontmatter schema for templates within an Eleventy collection.
Define a unique schema per collection, then receive output during development and builds to note incorrectly typed, missing, invalid, or misplaced custom data keys.
Terminal output example shown in VS Code using the theme Apollo Midnight
Conditions evaluted for:
- Missing required meta keys: [LIST]
- Possibly misplaced meta keys: [LIST]
- Incorrect type for meta [KEY], change to [TYPE]
- Invalid meta keys: [LIST]
Invalid
catches typos or extra, untyped keys that may need to be added to the schema.
Installation and Usage
Install the plugin:
npm install @11tyrocks/eleventy-plugin-collection-schemas
Then, include it in your .eleventy.js
config file:
const collectionSchemas = require("@11tyrocks/eleventy-plugin-collection-schemas");
module.exports = (eleventyConfig) => {
eleventyConfig.addPlugin(collectionSchemas);
};
You'll also need to create or add to a global eleventyComputed.js
file which should live in your global data directory (default: _data
). This is to enable access of the total computed page data to the plugin.
module.exports = {
metaSchema: function (data) {
return this.metaSchema(data);
},
};
The plugin works by adding a custom data extension (plugin default: .meta
). This .meta
file works similar to a directory data file, so it will need the same name as the parent directory of your collection. To associate the schema with the collection, the collection will also need the same name.
For each collection you want to enforce a schema for, you'll need to have the following setup, which assumes a collection named pages
:
pages/
pages.meta
pages.json
page-one.md <- content in any templating language
Where pages.json
is a directory data file that creates the collection via the tags mechanism:
{
"tags": "pages"
}
✨ Tip: You can also use the directory data file to change the permalink for all templates in a collection if you don't want them to have the collection name as URL base.
Schema Format
The content of the .meta
file is JSON formatted, with the parent key being the name of your custom data key, and the child properties of type
and required
.
{
"title": {
"type": "string",
"required": true
},
"draft": {
"type": "boolean",
"required": false
},
"categories": {
"type": "array",
"required": false
},
"order": {
"type": "number",
"required": true
}
}
Note
Data that Eleventy expects such as
date
should not be included in your schema, only custom data.
Use in templates
To adhere to your schema within templates, the default is to nest the schema-defined properties under a meta
key (configurable).
---
meta:
title: "My Page Title"
order: 3
description: "One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin."
---
Config Options
Option | Type | Default | Description |
---|---|---|---|
metaKey | string | 'meta' | Key to define data within templates |
metaExtension | string | 'meta' | File extension to use for schemas |
Schema Limitations
- Only one level of schema data is currently possible
- Only the top-level collection is used to locate schemas