Front matter and slugs

Before writing a page, two things it needs: a way to say what it is, and a name to go by. Front matter and a slug. Then one small file that turns the name into an address.

Front matter

Front matter is the block at the very top of a file, fenced by two lines of three dashes and written as YAML:

---
title: 'About'
slug: 'about'
description: 'What this site is, in one sentence, for anyone who wonders.'
---

The words of the page start here.

Everything in that block becomes data attached to this page and nothing else. Eleventy reads some of the keys itself, permalink, date, layout and tags among them. Baseline reads others: title and description are the two that feed the head. Any key you invent is yours, waiting in the page's data for a template to ask for it.

Three keys are the working minimum: title, slug and description. Write those on every page.

The rest is optional. date matters once something sorts your content, which posts do and pages do not, and permalink is for a page that has to name its own address rather than take the one it is given.

Slugs

A slug is the name a page goes by. Write slug: 'about' and the page is called about, which is a different question from where the file sits or what the URL ends up being. A slug is a name, a permalink is a path, and names are easier to keep tidy.

It is also the page's identity as far as Baseline is concerned. The content graph is built around slugs: they are how Baseline knows which page is which, and how one page finds another without anybody writing a URL down.

Give every page a slug, and make it unique.

Forget one and the rule below refuses to write the page at all. You get a warning in the build log and no file, which is easy to miss if you are not reading the output.

Give two pages the same slug and the build stops before writing anything, with an error naming both files. There is no winner to pick between them, so it refuses rather than guessing.

And pick it once. The slug is the URL, so changing it later moves the page, which means a redirect and every link you forgot about pointing at nothing.

Turning a slug into a URL

Eleventy lets every page declare its own address: put a permalink in the front matter and be done with it. It also means remembering it every single time, and missing it once puts the page at whatever the filename happened to be. So we set a rule for the whole folder instead, and let the URLs follow from what each page is called.

That rule lives in a directory data file, and the name is the mechanism: pages.11tydata.js sitting inside pages/ is how Eleventy knows this data belongs to everything in that folder. Create src/content/pages/pages.11tydata.js:

export default {
	// Ensure we have a value to work with by explicitly asking for the slug field.
	permalink: function ({ slug, page }) {
		if (!slug) {
			console.warn(`Warning: No slug found for ${page.inputPath}`);
			return false;
		}

		try {
			const normalizeSlug = this.slugify(slug);
			return `/${normalizeSlug}/`;
		} catch (error) {
			console.error(`Error generating permalink for ${page.inputPath}:`, error);
			return false;
		}
	}
};

Write slug: 'about', get /about/.

The rest is manners. this.slugify cleans up whatever you typed, so 'About Us' still arrives at /about-us/. A page with no slug gets a warning and return false, which tells Eleventy not to write the file at all: a page with no name is more likely a mistake than a decision, and a loud nothing beats a quiet file at an address you never chose.

That return false is worth knowing on its own. Any page whose permalink is false gets built and never written, so the same move is how you keep a draft or a scratch file out of the site.

It never has to catch the data file itself, though. Baseline excludes *.11tydata.js from the build for you, everywhere in the project.

It would be tempting to use eleventyComputed for creating the permalink, but that would always take precedence over the front matter field if set. The permalink function does plenty, including still allowing us to overwrite the field if needed.

So the order is: front matter wins. Write a permalink on a page and it gets that address, with the folder rule stepping aside; write none and the rule decides. Let's write some content next.