---
description: Frontmatter syntax for posts and pages
---

# Frontmatter Reference

How to write frontmatter for markdown-blog posts and pages.

## Blog post frontmatter

Location: `content/blog/*.md`

### Required fields

| Field | Type | Description |
|-------|------|-------------|
| title | string | Post title |
| description | string | SEO description |
| date | string | YYYY-MM-DD format |
| slug | string | URL path (must be unique) |
| published | boolean | true to show publicly |
| tags | string[] | Array of topic tags |

### Optional fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| featured | boolean | false | Show in featured section |
| featuredOrder | number | - | Display order (lower = first) |
| image | string | - | OG/header image path |
| showImageAtTop | boolean | false | Display image at top of post |
| excerpt | string | - | Short text for card view |
| readTime | string | auto | Reading time (auto-calculated if omitted) |
| authorName | string | - | Author display name |
| authorImage | string | - | Author avatar URL (round) |
| layout | string | - | "sidebar" for docs-style layout |
| rightSidebar | boolean | true | Show right sidebar |
| aiChat | boolean | false | Enable AI chat in sidebar |
| blogFeatured | boolean | false | Hero featured on /blog page |
| newsletter | boolean | - | Override newsletter signup |
| contactForm | boolean | false | Enable contact form |
| unlisted | boolean | false | Hide from listings but allow direct access via slug |
| showFooter | boolean | - | Override footer display |
| footer | string | - | Custom footer markdown |
| showSocialFooter | boolean | - | Override social footer |

### Example blog post

```markdown
---
title: "How to write a blog post"
description: "A guide to writing posts with frontmatter"
date: "2025-01-15"
slug: "how-to-write-a-blog-post"
published: true
tags: ["tutorial", "markdown"]
featured: true
featuredOrder: 1
image: "/images/my-post.png"
excerpt: "Learn how to create blog posts"
authorName: "Your Name"
authorImage: "/images/authors/you.png"
---

Your content here...
```

## Page frontmatter

Location: `content/pages/*.md`

### Required fields

| Field | Type | Description |
|-------|------|-------------|
| title | string | Page title |
| slug | string | URL path (must be unique) |
| published | boolean | true to show publicly |

### Optional fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| order | number | - | Nav order (lower = first) |
| showInNav | boolean | true | Show in navigation menu |
| featured | boolean | false | Show in featured section |
| featuredOrder | number | - | Display order (lower = first) |
| image | string | - | Thumbnail/OG image for cards |
| showImageAtTop | boolean | false | Display image at top |
| excerpt | string | - | Short text for card view |
| authorName | string | - | Author display name |
| authorImage | string | - | Author avatar URL |
| layout | string | - | "sidebar" for docs-style |
| rightSidebar | boolean | true | Show right sidebar |
| aiChat | boolean | false | Enable AI chat |
| contactForm | boolean | false | Enable contact form |
| newsletter | boolean | - | Override newsletter signup |
| textAlign | string | "left" | "left", "center", "right" |
| showFooter | boolean | - | Override footer display |
| footer | string | - | Custom footer markdown |
| showSocialFooter | boolean | - | Override social footer |

### Example page

```markdown
---
title: "About"
slug: "about"
published: true
order: 1
showInNav: true
featured: true
featuredOrder: 2
excerpt: "Learn about this site"
---

Page content here...
```

## Common patterns

### Featured post on homepage

```yaml
featured: true
featuredOrder: 1
```

### Hero post on /blog page

```yaml
blogFeatured: true
image: "/images/hero.png"
```

### Docs-style page with sidebar

```yaml
layout: "sidebar"
rightSidebar: true
```

### Hide from navigation

```yaml
showInNav: false
```

### Unlisted post

```yaml
published: true
unlisted: true
```

## Docs section navigation

Posts and pages can appear in the docs sidebar:

| Field | Type | Description |
|-------|------|-------------|
| docsSection | boolean | Include in docs navigation |
| docsSectionGroup | string | Sidebar group name |
| docsSectionOrder | number | Order within group |
| docsSectionGroupOrder | number | Order of group itself |
| docsSectionGroupIcon | string | Phosphor icon name |
| docsLanding | boolean | Use as /docs landing page |

### Example docs post

```yaml
---
title: "Getting Started"
slug: "getting-started"
published: true
docsSection: true
docsSectionGroup: "Quick Start"
docsSectionOrder: 1
docsSectionGroupOrder: 1
docsSectionGroupIcon: "Rocket"
layout: "sidebar"
---
```

## Validation

The sync script validates:

- Required fields must be present
- `slug` must be unique
- `date` should be YYYY-MM-DD format
- `published` must be boolean

Missing required fields will cause the file to be skipped with a warning.