doc-frontmatter

name	doc-frontmatter
description	Add or fix YAML frontmatter for documentation files. Adds missing required fields or fixes invalid frontmatter. Use for bulk fixing or when validation fails. Use when this capability is needed.
metadata	{"author":"esola-thomas"}

Fix Documentation Frontmatter

Add or repair YAML frontmatter for documentation files.

Instructions

1. Read the target file

2. Check current frontmatter status:

   • No frontmatter: Generate complete frontmatter
   • Partial frontmatter: Add missing required fields
   • Invalid YAML: Fix syntax errors

3. Required fields (must all be present):

Field	Type	How to determine value
title	string	From H1, or derive from filename
category	string	From parent directory name
tags	array	From content keywords
order	integer	Next available in directory

4. Derive values intelligently:

Title:

• Use explicit --title if provided
• Otherwise extract from first H1 in document
• Otherwise derive from filename: getting-started.md -> "Getting Started"

Category:

• Use explicit --category if provided
• Otherwise derive from directory:
  • docs/guides/ -> "Guides"
  • docs/api/ -> "API Reference"
  • docs/reference/ -> "Reference"
  • example/tutorials/ -> "Tutorials"

Tags:

• Use explicit --tags if provided (comma-separated)
• Otherwise analyze content for keywords
• Always include category as a tag (lowercase)
• Suggest 2-4 relevant tags

Order:

• Check sibling files in same directory
• Find highest existing order number
• Set to next available (highest + 1)
• Default to 1 if first file

5. Apply changes:
   • If no frontmatter exists, add at top of file
   • If frontmatter exists, merge new fields (don't overwrite existing valid fields)

Output Format

Show what was added/changed:

## Frontmatter Updated: docs/guides/new-doc.md

Added:
- title: "New Document"
- category: "Guides"
- tags: ["guide", "setup"]
- order: 3

Final frontmatter:
---
title: "New Document"
category: "Guides"
tags: ["guide", "setup"]
order: 3
---

Batch Mode

If path is a directory, process all .md files:

/doc-frontmatter docs/guides/

Reports summary:

Processed 5 files:
- 2 files updated
- 1 file already valid
- 2 files created frontmatter

Example Usage

/doc-frontmatter docs/new-doc.md                           # Auto-detect all
/doc-frontmatter docs/api/tool.md --category "API"         # Override category
/doc-frontmatter docs/guide.md --tags "beginner,setup"     # Specify tags
/doc-frontmatter docs/guides/                              # Batch process

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.