Editing Post Frontmatter

Overview

Blog post frontmatter drives OpenGraph metadata, search indexing, tag pages, and preview cards. Getting it wrong means broken social sharing, inconsistent tag pages, and placeholder text visible to readers. This skill ensures frontmatter is complete, consistent, and optimized for sharing.

When to Use

• Creating a new post or publishing a draft
• Reviewing frontmatter before committing
• User asks about tags, excerpts, or OG metadata
• Placeholder values detected (tag1, tag2, A brief description)

Frontmatter Reference

yaml
1slug: post-slug                    # Required. Kebab-case, matches filename.
2title: Post Title                  # Required. Sentence/title case.
3date: 'YYYY-MM-DD'                # Required. ISO date string.
4excerpt: >-                        # Required. See Excerpt Guidelines below.
5  One to two sentences...
6tags:                              # Required. See Tag Guidelines below.
7  - Tag Name
8featured_image: /images/file.webp  # Required. Used as OG image.
9draft: false                       # Required. true hides from production builds.
10showToc: false                     # Optional. Defaults to showing ToC.

No explicit OG fields needed. The site auto-generates og:title, og:description, og:image, Twitter cards, and JSON-LD from these fields via src/lib/seo.ts.

Excerpt Guidelines

The excerpt serves triple duty: OG description, search result preview, and on-page summary.

Rules:

• 1-2 sentences, under 160 characters ideal (search engine display limit)
• Describe what the reader will learn or find, not what you did
• Avoid starting with "In this post..." or "This article..."
• Must make sense out of context (social media card, search result)
• Never leave as template placeholder

Good:

yaml
1excerpt: "Lockpicking, ranged combat simplification, grapple redesign, and a dev environment rebuild in the latest Iron, Blood & Omens devlog."

Bad:

yaml
1excerpt: "A brief description of your post that will appear in previews and summaries."

Tag Guidelines

MANDATORY: Before suggesting tags, run this command to list all existing tags:

bash
1grep -rh "^  - " content/posts/*.mdx | sed 's/^[[:space:]]*- //' | sort | uniq -c | sort -rn

Rules:

• Reuse existing tags before creating new ones
• Title Case for multi-word tags (e.g., "DM Advice", "Game Development")
• Acronyms stay uppercase (e.g., "IBO", "DnD 5e")
• 2-4 tags per post is ideal
• Tags generate dedicated pages at /tag/[tag]/ so consistency matters

Established tags (check command above for current list):

Note: This table may drift. Always run the grep command to get the authoritative list.

Pre-Publish Checklist

1. No placeholders - excerpt is not template default, tags are not ["tag1","tag2","tag3"]
2. Excerpt under 160 chars - check with echo -n "excerpt text" | wc -c
3. Tags exist - ran grep command, reused existing tags where possible
4. Tag casing matches - Title Case, consistent with existing usage
5. featured_image set - path exists in /public/images/
6. slug matches filename - 2026-03-06-my-post.mdx has slug: my-post

Common Mistakes