Frontmatter Reference

Every Markdown file in content/ starts with a YAML frontmatter block. This page documents every field Pycora Pro reads.

---

Basic Structure

---
layout: layouts/post
title: "My Post"
description: "A short description"
date: 2026-01-15
tags: [python, ssg]
author: Axcora
---

The block starts and ends with ---. Everything below the closing --- is the body.

---

Common Fields

These fields appear in every content file:

Field	Type	Required	Description
layout	string	Yes	Template to use (e.g., layouts/post)
title	string	Yes	Page or post title
description	string	No	Meta description for SEO
image	string	No	Social share / featured image
date	date	No	Publish date (YYYY-MM-DD)
tags	list	No	Tags for categorization
author	string	No	Author name
keywords	string	No	SEO keywords

---

Page Fields

Pages (Home, About, Contact) use these extra fields:

Field	Type	Description
body	string	Markdown body (About Page)
hero	object	Hero section (Home Page)
trusted	object	Trusted logos (Home Page)
intro	object	Intro section (Home Page)
intro_grid1	object	First grid block (Home Page)
intro_grid2	object	Second grid block (Home Page)
intro_grid3	object	Third grid block (Home Page)
stats	object	Stats counters (Home Page)
journal	object	Journal link (Home Page)
projects	object	Projects link (Home Page)
testimonial	object	Client quote (Home Page)

See Home Page Reference for the full structure.

---

Controller Fields

Controllers are Markdown files with a collection: key:

Field	Type	Required	Description
collection	string	Yes	Collection to list (posts, projects)
pagination	number	No	Items per page
sort_by	string	No	Sort field (date, title)
sort_order	string	No	asc or desc
filter	object	No	Metadata filter
limit	number	No	Maximum items

See Controllers for full details.

---

Project Fields

Project entries use these fields:

Field	Type	Required	Description
layout	string	Yes	layouts/project-detil
info	string	Yes	Short category label
title	string	Yes	Project name
description	string	No	Short summary
image	string	No	Featured image
client	string	No	Client name
years	string	No	Project year
date	date	No	Publish date
tags	list	No	Tags
author	string	No	Author name

---

Post Fields

Blog posts use these fields:

Field	Type	Required	Description
layout	string	Yes	layouts/post
title	string	Yes	Post title
description	string	No	Short summary
image	string	No	Featured image
date	date	No	Publish date
author	string	No	Author name
tags	list	No	Tags

---

Date Formats

Pycora Pro accepts multiple date formats:

Format	Example
ISO	2026-01-15
ISO with time	2026-01-15T10:30:00
Long form	January 15, 2026

For sorting to work, use ISO (YYYY-MM-DD).

---

Tags

Tags can be written three ways:

Inline Array

tags: [python, ssg, jamstack]

Multiline List

tags:
  - python
  - ssg
  - jamstack

Comma-Separated String

tags: "python, ssg, jamstack"

All three are parsed into a list.

---

Nested Objects

Frontmatter can contain nested objects:

hero:
  info: "Axcora Lab"
  title1: "We Build"
  title2: "Structures"
  title3: "That Last."
  button1:
    text: "Get Started"
    url: "/contact/"
  image:
    url: "/img/hero.avif"
    alt: "Hero image"

Access in templates:

{{ hero.title1 }}
{{ hero.button1.text }}
{{ hero.image.url }}

---

Missing Fields

If a field is missing, Pycora Pro returns a ChainableUndefined — a safe placeholder. Templates do not crash.

{{ post.author }}              {# empty if missing #}
{{ post.author.name }}         {# empty if nested missing #}
{{ post.author | default("Anonymous") }}

Use default() for fallbacks.

---

Validation

Pycora Pro does not validate frontmatter. Invalid YAML will fail the build with a parse error.

Before committing, verify:

• All keys are lowercase with hyphens or underscores
• Strings with special characters are quoted
• Dates are ISO format
• Lists use - or []

---

Best Practices

• Quote strings with special characters: "Pycora — Python SSG"
• Use ISO dates: 2026-01-15
• Keep tags lowercase: python, not Python
• Use consistent field names across files in the same collection
• Do not add custom fields unless you edit the templates to use them

---

Troubleshooting

Build fails with a YAML error

1. Check the YAML syntax — indentation matters
2. Look for tabs — YAML uses spaces only
3. Check for missing --- at the top or bottom

Field is empty in the output

1. Check that the field name matches the template variable
2. Check that the field is not nested incorrectly
3. Use | default() for optional fields

Date sorting does not work

1. Use ISO format: YYYY-MM-DD
2. Check that dates are not quoted (date: 2026-01-15, not date: "2026-01-15")

Tags do not create tag pages

1. Check that tags has at least one item
2. Rebuild the site

---

Related

• YAML Configuration
• Controllers
• Template Engine
• Project Structure

---

What's Next?

• YAML Configuration
• Contributing