mirror of
https://github.com/waynesutton/markdown-site.git
synced 2026-01-12 04:09:14 +00:00
195 lines
4.9 KiB
Markdown
195 lines
4.9 KiB
Markdown
---
|
|
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.
|