Jekyll Front Matter Defaults: Share Metadata Across Pages

The problem and the useful answer

If your Jekyll site has dozens of pages that all use the same layout, permalink pattern, or category, repeating those values in every front matter block is tedious and error-prone. Front matter is the YAML block between triple dashes at the top of a Markdown or HTML file that Jekyll reads as page metadata. Jekyll defaults let you declare shared metadata once in _config.yml. Jekyll then fills in missing front matter keys for matching files, while any key set directly on a page wins over the default.

Declare defaults in _config.yml

Defaults live under the top-level defaults key as a list. Each item combines optional scope filters with a values mapping of front matter keys. path is relative to your site source directory, and type can be pages, posts, or the name of a collection.

defaults:
  - scope:
      path: "docs"
      type: "pages"
    values:
      layout: "docs"
      permalink: "/docs/:name/"
      categories: ["documentation"]
  - scope:
      path: "_posts"
      type: "posts"
    values:
      layout: "post"
      categories: ["journal"]

The first entry applies to every page under source/docs/. The second applies to posts. A file at source/docs/getting-started.md with no front matter inherits layout: docs and permalink: /docs/getting-started/.

Page-level values override defaults

If you add front matter to that same file, Jekyll merges the two, but page-level keys take precedence:

---
title: "Getting Started"
layout: guide
---

Here layout: guide replaces the defaulted layout: docs, while permalink and categories still come from the default.

Shallow merging only

Jekyll does not append arrays. If a default sets categories: [documentation] and a page sets categories: [tutorial], the page ends up with only tutorial, not both. The same replacement behavior applies to other list-valued keys such as tags.

Limits of defaults

• Defaults are static YAML. They cannot render Liquid tags, read site.data, or compute values at build time.
• Defaults do not process excluded files or posts with published: false.
• Because _config.yml is usually committed to version control, never store secrets or API tokens in default values.
• Changing defaults requires a full rebuild; incremental regeneration may not reapply new defaults to every file.

Common mistakes that fail silently

• Path format: path values are relative to source and should not include a leading slash or trailing slash. path: "/docs/" may not match files under source/docs/, and the default simply will not apply.
• Wrong template: A defaulted layout can apply the wrong template when page authors forget to set layout explicitly. The mistake appears only in rendered output, not as a build error.
• Scope mismatch: Using type: pages for files in a collection named staff will not match; use the collection name instead.

Verify the result

1. Open a terminal in your site root and run jekyll -v to confirm a Jekyll 4.x release.
2. Add or edit the defaults block in _config.yml. No special permissions are required beyond write access to the file.
3. Run jekyll build. This regenerates _site from source.
4. Inspect _site/docs/getting-started/index.html or the path implied by the defaulted permalink. Confirm the file exists at the expected URL path and uses the defaulted layout.
5. Create a matching source file with no front matter, build, and confirm it inherits the defaults. Then add conflicting front matter and confirm the page-level value wins.
6. Run jekyll doctor after editing _config.yml to catch YAML syntax errors in the defaults block before deploying.

Risk: editing _config.yml changes build output. If a new default produces the wrong layout across many pages, revert the defaults block and run jekyll build again to restore the previous output.

Practical check

After a build, confirm the expected file path exists under _site and that the HTML uses the defaulted layout. If the file is missing or uses the wrong template, check the path and type values in your defaults block first.