Markdown YAML Frontmatter

Goal

Ensure every Markdown file created or substantially edited includes a YAML frontmatter block with consistent, searchable metadata.

Required Frontmatter Fields

When creating any .md file content (new file or major rewrite), include a YAML frontmatter block at the very top of the file with these fields:

• title: Human-readable title (string)
• description: One-paragraph summary (string)
• category: One primary category (string)
• tags: List of keywords for discovery (array of strings) — see Tag Selection Guide below
• status: One of Proposed, Working, Living (string)
• updated: Last meaningful edit date (ISO-8601 YYYY-MM-DD)
• related: Paths to closely related docs (array of strings)
• links_from: Paths that reference or should reference this doc (array of strings)

Tag Selection Guide

Tags enable tag-based discovery — finding documents that bridge multiple concepts. Choose tags strategically:

Tag Categories

1. Domain tags: The primary subject area (e.g., async, error-handling, testing)
2. Pattern tags: Design patterns or techniques (e.g., retry, result-pattern, dependency-injection)
3. Technology tags: Specific technologies or libraries (e.g., polly, entity-framework, signalr)
4. Concern tags: Cross-cutting concerns (e.g., performance, security, resilience)

Best Practices

• Include 3–8 tags per document
• Include at least one domain tag and one pattern/concern tag
• Use consistent naming: lowercase, hyphenated (e.g., error-handling not ErrorHandling)
• Include synonyms when commonly searched (e.g., both di and dependency-injection)
• Think: "What concepts does this document bridge?"

Example: Good Tag Selection

# Document about async exception handling
tags: ["async", "error-handling", "exceptions", "task", "cancellation"]

# Document bridges: async ↔ error-handling ↔ cancellation
# Discoverable via: "async error handling", "cancellation exceptions", etc.

Anti-patterns

• ❌ Too few tags: tags: ["csharp"] — not discoverable
• ❌ Too generic: tags: ["code", "programming", "software"] — no signal
• ❌ Inconsistent naming: tags: ["ErrorHandling", "error_handling"] — won't match searches

Process

1. Determine whether the task is creating/editing Markdown content.
   • If yes, ensure frontmatter exists.
   • Exception: prompt definition files (for example .prompt.md under .github/prompts) may require a restricted frontmatter schema. In that case, keep the prompt frontmatter valid and record the required doc-metadata fields in the body.
2. If the file has no frontmatter, add a new YAML frontmatter block at the top.
3. If the file has frontmatter, preserve existing fields and add any missing required fields.
4. Select tags strategically using the Tag Selection Guide above.
5. Update updated to today's date (ISO YYYY-MM-DD) when changes are non-trivial.
6. Keep related and links_from as workspace-relative paths (use / separators).
7. Keep metadata minimal and accurate.
   • Prefer 3–8 tags (with cross-domain coverage).
   • Prefer 0–6 related files.
   • links_from is allowed to be empty initially; populate it when known.

Template

Use this template when creating new Markdown files:

---
title: "<concise title>"
description: "<1–3 sentence summary>"
category: "<single category>"
tags: ["tag-one", "tag-two"]
status: "Proposed"
updated: "YYYY-MM-DD"
related: ["knowledge-base/README.md"]
links_from: ["README.md"]
---

Note: Prefer YAML inline arrays for tags, related, and links_from (for example tags: ["tag-one", "tag-two"]) to keep metadata compact.

Examples

Example: Adding frontmatter to an existing doc

If a file begins immediately with a heading (e.g., # Something), prepend the frontmatter block above it.

Example: Filling related and links_from

• related should include peer docs that a reader should also see.
• links_from should include docs that link here, or that should link here once the docs are cleaned up.

Guardrails

• Don’t invent relationships. If you’re unsure, leave related: [] and/or links_from: [].
• Don’t rewrite the whole doc just to add metadata; keep the diff focused.
• If the repository already uses another metadata system in a subfolder, follow that local convention and still include these required fields unless it conflicts.