Frontmatter and Metadata Processing

**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [adelaide-city-fc.md](file://src/content/cases/adelaide-city-fc.md) - [2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md) - [01-matt-neagle.md](file://src/content/team/01-matt-neagle.md) - [getting-started.md](file://src/content/knowledge/getting-started.md) - [cases.11tydata.json](file://src/content/cases/cases.11tydata.json) - [news.11tydata.json](file://src/content/news/news.11tydata.json) - [team.11tydata.json](file://src/content/team/team.11tydata.json) - [knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js) - [site.json](file://src/_data/site.json) - [pages.json](file://src/_data/pages.json) - [partners.json](file://src/_data/partners.json) - [testimonials.json](file://src/_data/testimonials.json) - [polling.js](file://src/_data/polling.js)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains how frontmatter and metadata are processed and made available throughout the Eleventy build pipeline in this project. It covers frontmatter structure, YAML parsing, data types, and how metadata flows into templates and collections. It also documents inheritance and defaults via global data files and 11ty data files, validation patterns, and practical guidance for structuring frontmatter across content types. Finally, it provides troubleshooting tips and best practices for consistent metadata handling.

Project Structure

Eleventy’s configuration defines input/output directories and template formats. Content files (Markdown with frontmatter) live under src/content, while global data lives under src/_data. Per-collection 11ty data files customize behavior such as permalinks and computed values. Collections are defined in the Eleventy config to filter and sort content using metadata.

graph TB
A[".eleventy.js<br/>dir.input/src<br/>dir.data/_data<br/>collections"] --> B["src/content/*/*.md<br/>frontmatter YAML"]
A --> C["src/_data/*.json<br/>src/_data/*.js"]
A --> D["src/content/*/ *.11tydata.{json|js}"]
B --> E["Collections via data.*"]
C --> F["Template data (global)"]
D --> G["Per-item/per-collection overrides/computed"]

Diagram sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)
  • [adelaide-city-fc.md:1-14](file://src/content/cases/adelaide-city-fc.md#L1-L14)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)

Section sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)

Core Components

  • Frontmatter in Markdown files: Defines per-page metadata such as title, date, author, image, excerpt, tags, ordering, and flags like featured.
  • Global data files: Provide site-wide defaults and shared content (e.g., site metadata, hero copy, testimonials).
  • Per-collection 11ty data files: Disable permalinks for index-like pages and set computed permalink structures.
  • Eleventy collections: Filter and sort content using metadata fields (e.g., date, order, featured).
  • Filters and transforms: Support rendering and post-processing of metadata in templates.

Examples of frontmatter fields observed:

  • String scalars: title, client, category, anchor, name, role, image, image_alt, pdf_url, pdf_label, bio_short.
  • Boolean flags: featured.
  • Numeric values: order (including null), integers for polling metrics.
  • Arrays: tags_list.
  • Dates: date (ISO string).

These are consumed in templates and collections to drive rendering and filtering.

Section sources

  • [adelaide-city-fc.md:1-14](file://src/content/cases/adelaide-city-fc.md#L1-L14)
  • [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [01-matt-neagle.md:1-21](file://src/content/team/01-matt-neagle.md#L1-L21)
  • [getting-started.md:1-52](file://src/content/knowledge/getting-started.md#L1-L52)

Architecture Overview

The Eleventy pipeline merges data from multiple sources:

  • Global data files (JSON/JS) supply site-wide metadata and reusable content blocks.
  • Per-collection 11ty data files define layout, tags, and computed permalink behavior.
  • Individual content frontmatter supplies per-page metadata.
  • Collections read from disk, apply filters/sorts, and expose items to templates.
sequenceDiagram
participant FS as "Disk Files"
participant ED as "Eleventy Engine"
participant GD as "Global Data (_data)"
participant CD as "Collection 11ty Data"
participant MD as "Markdown Frontmatter"
participant CL as "Collections"
participant TM as "Templates"
FS->>ED : Read src/content/**/*.md
ED->>GD : Load site.json, pages.json, testimonials.json, polling.js
ED->>CD : Load *.11tydata.{json|js}
ED->>MD : Parse YAML frontmatter
ED->>CL : Build collections (filters/sorts)
ED->>TM : Render with merged data

Diagram sources

  • [.eleventy.js:169-210](file://.eleventy.js#L169-L210)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [pages.json:1-79](file://src/_data/pages.json#L1-L79)
  • [polling.js:1-17](file://src/_data/polling.js#L1-L17)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

Detailed Component Analysis

Frontmatter Structure and Data Types

  • Scalars: Strings (title, category, image paths), booleans (featured), numeric values (order, polling percentages).
  • Arrays: tags_list for tagging content.
  • Nested objects: social profiles, structured content blocks (e.g., polling data).
  • Dates: ISO date strings for chronological sorting.

Frontmatter is parsed from YAML delimiters and exposed as data in templates and collections.

Section sources

  • [adelaide-city-fc.md:1-14](file://src/content/cases/adelaide-city-fc.md#L1-L14)
  • [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [01-matt-neagle.md:1-21](file://src/content/team/01-matt-neagle.md#L1-L21)
  • [polling.js:1-17](file://src/_data/polling.js#L1-L17)

Metadata Availability in Templates and Collections

  • Collections use data.* to filter and sort content. Examples:
    • Sort by date descending for news and knowledge.
    • Sort by order for team members.
    • Filter by featured flag for featured content.
  • Templates can access frontmatter fields directly (e.g., title, date, author, image, excerpt, tags_list, featured).

Practical usage patterns:

  • Sorting by date: [news collection:170-174](file://.eleventy.js#L170-L174), [knowledge collection:206-210](file://.eleventy.js#L206-L210)
  • Sorting by order: [teamMembers collection:187-191](file://.eleventy.js#L187-L191)
  • Filtering by boolean: [featuredNews collection:193-198](file://.eleventy.js#L193-L198)

Section sources

  • [.eleventy.js:169-210](file://.eleventy.js#L169-L210)

Metadata Inheritance and Defaults

  • Global data files provide defaults for site-level metadata and reusable page content blocks.
    • Site metadata: [site.json:1-20](file://src/_data/site.json#L1-L20)
    • Page-specific hero/CTA content: [pages.json:1-79](file://src/_data/pages.json#L1-L79)
    • Testimonials: [testimonials.json:1-24](file://src/_data/testimonials.json#L1-L24)
    • Dynamic polling data: [polling.js:1-17](file://src/_data/polling.js#L1-17)
  • Per-collection 11ty data files set layout, tags, and computed permalink behavior.
    • Index-like pages disable permalinks: [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2), [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2), [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
    • Knowledge base computes custom permalinks: [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

How inheritance works:

  • Global data is merged into every template context.
  • Per-collection 11ty data augments or overrides global behavior for that collection.
  • Per-item frontmatter overrides both global data and collection data at render time.

Section sources

  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [pages.json:1-79](file://src/_data/pages.json#L1-L79)
  • [testimonials.json:1-24](file://src/_data/testimonials.json#L1-L24)
  • [polling.js:1-17](file://src/_data/polling.js#L1-L17)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

Default Values and Computed Metadata

  • Default permalink behavior is overridden per collection:
    • Disabling permalinks for index pages: [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2), [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2), [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
    • Custom permalink for knowledge base articles: [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • Dynamic data injection via JS:
    • Polling data computed at build-time: [polling.js:1-17](file://src/_data/polling.js#L1-L17)

Validation patterns:

  • Use boolean flags (e.g., featured) for conditional rendering.
  • Use arrays (e.g., tags_list) for taxonomy-based filtering.
  • Use numeric order fields for deterministic ordering.

Section sources

  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • [polling.js:1-17](file://src/_data/polling.js#L1-L17)

Conditional Metadata and Dynamic Data Generation

  • Conditional rendering in templates:
    • Featured content filtering: [featuredNews collection:193-198](file://.eleventy.js#L193-L198)
    • Ordering logic: [teamMembers collection:187-191](file://.eleventy.js#L187-L191)
  • Dynamic data:
    • Per-page computed permalink: [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
    • Runtime-generated polling metrics: [polling.js:1-17](file://src/_data/polling.js#L1-L17)
flowchart TD
Start(["Render Article"]) --> CheckFeatured["Check 'featured' flag"]
CheckFeatured --> IsFeatured{"Featured?"}
IsFeatured --> |Yes| ShowFeatured["Render featured card"]
IsFeatured --> |No| SkipFeatured["Skip featured card"]
Start --> OrderField["Read 'order' or fallback"]
OrderField --> SortTeam["Sort team members by order"]
Start --> ComputePermalink["Compute custom permalink"]
ComputePermalink --> RenderLink["Render article link"]

Diagram sources

  • [.eleventy.js:187-191](file://.eleventy.js#L187-L191)
  • [.eleventy.js:193-198](file://.eleventy.js#L193-L198)
  • [knowledge.11tydata.js:4-6](file://src/content/knowledge/knowledge.11tydata.js#L4-L6)

Section sources

  • [.eleventy.js:187-198](file://.eleventy.js#L187-L198)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • [polling.js:1-17](file://src/_data/polling.js#L1-L17)

Structuring Frontmatter for Different Content Types

  • Cases: client, category, title, image, image_alt, quote, quote_author, order, featured.
  • News: title, date, author, excerpt, image, image_alt, pdf_url, pdf_label, featured.
  • Team: anchor, name, role, order, image_index/image_profile, image_alt_index/image_alt_profile, bio_short, featured.
  • Knowledge: title, date, author, excerpt, tags_list.

Recommendations:

  • Always include canonical fields (title, date, excerpt) for discoverability.
  • Use tags_list for taxonomy and filtering.
  • Use order for deterministic presentation.
  • Use featured for highlight logic in collections.

Section sources

  • [adelaide-city-fc.md:1-14](file://src/content/cases/adelaide-city-fc.md#L1-L14)
  • [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [01-matt-neagle.md:1-21](file://src/content/team/01-matt-neagle.md#L1-L21)
  • [getting-started.md:37-51](file://src/content/knowledge/getting-started.md#L37-L51)

Metadata-Based Filtering and Sorting

  • Sorting by date: news and knowledge collections.
  • Sorting by order: team members.
  • Filtering by boolean: featured content.
  • Filtering by taxonomy: tags_list.

Filters and transforms support additional transformations in templates (e.g., limit, skip, sortBy, where, unique, truncate, slug, dateFormat).

Section sources

  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [.eleventy.js:187-191](file://.eleventy.js#L187-L191)
  • [.eleventy.js:193-198](file://.eleventy.js#L193-L198)
  • [.eleventy.js:206-210](file://.eleventy.js#L206-L210)
  • [.eleventy.js:46-164](file://.eleventy.js#L46-L164)

Dependency Analysis

The following diagram shows how frontmatter and data files relate to Eleventy’s processing pipeline and resulting template context.

graph LR
subgraph "Data Sources"
S["site.json"]
P["pages.json"]
T["testimonials.json"]
L["polling.js"]
C11["*.11tydata.{json|js}"]
end
subgraph "Content"
M["*.md (frontmatter)"]
end
subgraph "Eleventy Config"
E[".eleventy.js<br/>collections, filters, transforms"]
end
subgraph "Output"
O["Templates + Collections"]
end
S --> O
P --> O
T --> O
L --> O
C11 --> O
M --> O
E --> O

Diagram sources

  • [.eleventy.js:169-210](file://.eleventy.js#L169-L210)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [pages.json:1-79](file://src/_data/pages.json#L1-L79)
  • [testimonials.json:1-24](file://src/_data/testimonials.json#L1-L24)
  • [polling.js:1-17](file://src/_data/polling.js#L1-L17)
  • [cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)

Section sources

  • [.eleventy.js:169-210](file://.eleventy.js#L169-L210)

Performance Considerations

  • Prefer arrays and simple scalars in frontmatter for fast template rendering.
  • Use computed permalinks sparingly; they run per item during collection building.
  • Avoid heavy synchronous computation in global data files; use asynchronous JS data files when appropriate.
  • Keep tag lists concise to reduce template filtering overhead.

Troubleshooting Guide

Common issues and resolutions:

  • Missing or invalid date fields cause sorting errors. Ensure date is present and parseable.
    • Reference: [news collection sorting:170-174](file://.eleventy.js#L170-L174), [knowledge collection sorting:206-210](file://.eleventy.js#L206-L210)
  • Null order values can break deterministic sorting. Provide fallbacks or normalize order fields.
    • Reference: [teamMembers sorting:187-191](file://.eleventy.js#L187-L191)
  • Featured content not appearing: verify boolean flag presence and correct casing.
    • Reference: [featuredNews filter:193-198](file://.eleventy.js#L193-L198)
  • Incorrect permalinks for knowledge articles: confirm computed permalink logic.
    • Reference: [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • Dynamic data not updating: ensure asynchronous data file exports a Promise-returning function.
    • Reference: [polling.js:1-17](file://src/_data/polling.js#L1-L17)
  • Global data not applied: verify file location under src/_data and correct JSON syntax.
    • Reference: [site.json:1-20](file://src/_data/site.json#L1-L20), [pages.json:1-79](file://src/_data/pages.json#L1-L79)

Section sources

  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [.eleventy.js:187-191](file://.eleventy.js#L187-L191)
  • [.eleventy.js:193-198](file://.eleventy.js#L193-L198)
  • [.eleventy.js:206-210](file://.eleventy.js#L206-L210)
  • [knowledge.11tydata.js:1-8](file://src/content/knowledge/knowledge.11tydata.js#L1-L8)
  • [polling.js:1-17](file://src/_data/polling.js#L1-L17)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [pages.json:1-79](file://src/_data/pages.json#L1-L79)

Conclusion

Frontmatter and metadata in this project are central to content organization, presentation, and filtering. By combining per-item frontmatter, global data files, and per-collection 11ty data files, the pipeline supports flexible, maintainable content management. Following the recommended patterns ensures consistent rendering, robust filtering, and scalable metadata handling across cases, news, team, and knowledge content.

Appendices

Best Practices for Frontmatter

  • Always include canonical fields: title, date, excerpt.
  • Use tags_list for taxonomy and filtering.
  • Use order for deterministic presentation; provide fallbacks for null values.
  • Use boolean flags (e.g., featured) for conditional rendering.
  • Keep frontmatter minimal and consistent across similar content types.

Example References

  • Cases frontmatter: [adelaide-city-fc.md:1-14](file://src/content/cases/adelaide-city-fc.md#L1-L14)
  • News frontmatter: [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • Team frontmatter: [01-matt-neagle.md:1-21](file://src/content/team/01-matt-neagle.md#L1-L21)
  • Knowledge frontmatter and template guidance: [getting-started.md:1-52](file://src/content/knowledge/getting-started.md#L1-L52)