wiki/prds/howto-Frontmatter.md

How to Add New Frontmatter Fields

This guide documents the process for adding new frontmatter fields to the markdown blog framework.

Files Updated for authorName and authorImage (13 total)

When adding the authorName and authorImage frontmatter fields, these files were updated:

File	What Was Updated
convex/schema.ts	Added fields to posts and pages table definitions
scripts/sync-posts.ts	Added to interfaces (PostFrontmatter, ParsedPost, PageFrontmatter, ParsedPage) and parsing logic
convex/posts.ts	Added to return validators and syncPosts/syncPostsPublic mutations
convex/pages.ts	Added to return validators and syncPagesPublic mutation
src/pages/Post.tsx	Added UI rendering for author display
src/pages/Write.tsx	Added to POST_FIELDS and PAGE_FIELDS arrays
src/styles/global.css	Added CSS styles for author display
content/blog/setup-guide.md	Updated frontmatter tables and examples
content/pages/docs.md	Updated frontmatter tables
files.md	Updated frontmatter field tables
README.md	Updated frontmatter field tables
AGENTS.md	Updated frontmatter field tables
content/blog/about-this-blog.md	Added example usage

Frontmatter Flow Summary

Frontmatter is the YAML metadata at the top of each markdown file. Here is how it flows through the system:

1. Content directories (content/blog/*.md, content/pages/*.md) contain markdown files with YAML frontmatter
2. scripts/sync-posts.ts uses gray-matter to parse frontmatter and validate required fields
3. Convex mutations (api.posts.syncPostsPublic, api.pages.syncPagesPublic) receive parsed data
4. convex/schema.ts defines the database structure for storing frontmatter fields

Reusable Prompt for Future Frontmatter Updates

Copy and customize this prompt when adding new frontmatter fields:

Add a new optional frontmatter field called [FIELD_NAME] for [posts/pages/both].

Description: [What the field does]
Type: [string/boolean/number/array]
Display: [Where it should appear in the UI, if applicable]

Update these files:
1. convex/schema.ts - Add field to [posts/pages/both] table
2. scripts/sync-posts.ts - Add to [PostFrontmatter/PageFrontmatter] interface and parsing logic
3. convex/posts.ts - Add to return validators and sync mutations (if for posts)
4. convex/pages.ts - Add to return validators and sync mutations (if for pages)
5. src/pages/Post.tsx - Add UI rendering (if display needed)
6. src/pages/Write.tsx - Add to POST_FIELDS/PAGE_FIELDS array
7. src/styles/global.css - Add CSS styles (if display needed)
8. content/blog/setup-guide.md - Update frontmatter tables
9. content/pages/docs.md - Update frontmatter tables
10. files.md - Update frontmatter field tables
11. README.md - Update frontmatter field tables
12. AGENTS.md - Update frontmatter field tables
13. Add example usage to a content file

After implementation:
- Update changelog.md with the new feature
- Update content/pages/changelog-page.md
- Update TASK.md with completed task
- Create/update PRD in prds/ folder if needed

Step-by-Step Implementation Guide

Step 1: Update Schema

Add the field to convex/schema.ts:

// For posts
posts: defineTable({
  // ... existing fields
  newField: v.optional(v.string()), // or v.number(), v.boolean(), etc.
  lastSyncedAt: v.number(),
})

// For pages
pages: defineTable({
  // ... existing fields
  newField: v.optional(v.string()),
  lastSyncedAt: v.number(),
})

Step 2: Update Sync Script

Add to scripts/sync-posts.ts:

// Add to interface
interface PostFrontmatter {
  // ... existing fields
  newField?: string;
}

interface ParsedPost {
  // ... existing fields
  newField?: string;
}

// Add to parsing logic in parseMarkdownFile()
return {
  // ... existing fields
  newField: frontmatter.newField,
};

Step 3: Update Convex Mutations

Add to convex/posts.ts and/or convex/pages.ts:

// Add to return validator
returns: v.array(v.object({
  // ... existing fields
  newField: v.optional(v.string()),
}))

// Add to args validator in sync mutation
posts: v.array(v.object({
  // ... existing fields
  newField: v.optional(v.string()),
}))

// Add to patch/insert calls
await ctx.db.patch(existingPost._id, {
  // ... existing fields
  newField: post.newField,
});

Step 4: Update UI (if needed)

Add to src/pages/Post.tsx:

{post.newField && (
  <div className="post-new-field">
    {post.newField}
  </div>
)}

Step 5: Update Write Page

Add to src/pages/Write.tsx:

const POST_FIELDS = [
  // ... existing fields
  { name: "newField", required: false, example: '"example value"' },
];

Step 6: Add CSS (if needed)

Add to src/styles/global.css:

.post-new-field {
  /* styles */
}

Step 7: Update Documentation

Update frontmatter tables in:

• content/blog/setup-guide.md
• content/pages/docs.md
• files.md
• README.md
• AGENTS.md

Step 8: Add Example

Add the new field to a content file as an example (e.g., content/blog/about-this-blog.md).

Step 9: Update Changelog

Add entry to:

• changelog.md (root)
• content/pages/changelog-page.md

Step 10: Run Sync

npm run sync      # Development
npm run sync:prod # Production

Current Frontmatter Fields

Blog Posts (content/blog/*.md)

Field	Required	Description
title	Yes	Post title
description	Yes	SEO description
date	Yes	Publication date (YYYY-MM-DD)
slug	Yes	URL path
published	Yes	Show publicly
tags	Yes	Array of tags
readTime	No	Reading time
image	No	Header/OG image URL
excerpt	No	Short excerpt for cards
featured	No	Show in featured section
featuredOrder	No	Order in featured (lower first)
authorName	No	Author display name
authorImage	No	Round author avatar URL

Static Pages (content/pages/*.md)

Field	Required	Description
title	Yes	Page title
slug	Yes	URL path
published	Yes	Show publicly
order	No	Nav order (lower first)
excerpt	No	Short excerpt for cards
image	No	Thumbnail/OG image URL
featured	No	Show in featured section
featuredOrder	No	Order in featured (lower first)
authorName	No	Author display name
authorImage	No	Round author avatar URL

Related Files

• PRD: prds/howto-Frontmatter.md (this file)
• Write conflicts guide: prds/howtoavoidwriteconflicts.md
• Stats implementation: prds/howstatsworks.md