Markdown Article Frontmatter Convention

Contract

When you format or "beautify" prose into a publish-ready markdown file, emit a YAML frontmatter block with EXACTLY the fields below, in the given order, move any body H1 into title, and leave the body prose untouched. Apply whenever the task asks to format, beautify, clean up, or add a metadata/frontmatter header to an article, post, or note.

Rules

R1 — Field set is exactly four (plus one conditional)

The frontmatter contains EXACTLY these four fields, in THIS order:

1. title
2. slug
3. summary
4. description

Add coverImage (5th) ONLY when a cover image actually exists for the article. Never invent it. Add NOTHING else: no date, author, tags, category, excerpt, keywords, draft, layout, published, readingTime, or any other key — even if it seems helpful or conventional elsewhere. Four fields, that order, full stop.

R2 — Title lives only in frontmatter; body is H1-free

If the body starts with an H1 (# ...), MOVE that exact text into the title field and DELETE the # ... line from the body. If the source has no H1, derive a title from the content. The body must contain NO level-1 heading anywhere — the first body heading is ##. There is never both a title in frontmatter and a # line in the body (that duplicates the title).

R3 — slug is kebab-case derived from the title

slug is the title lowercased and kebab-cased: all lowercase, words joined by SINGLE hyphens, ASCII only, no spaces, no punctuation (drop ?, :, ,, ., ', ", &, /), no leading/trailing hyphen, no doubled hyphens. Drop nothing meaningful — keep the content words so the slug stays recognizable. It is NOT a random id, NOT snake_case, NOT camelCase, NOT title-cased.

R4 — summary is ONE short sentence conveying reader VALUE

summary is a SINGLE sentence, roughly 50–80 characters, that conveys the reader value (what they get), not merely the topic. It is the punchy hook used in feeds and SEO meta. It MUST be shorter (fewer characters) than description.

R5 — description is 2–3 sentences of richer context

description is 2–3 sentences, roughly 100–200 characters, expanding on summary with supporting detail. It is always LONGER than summary.

R6 — Forbidden openings for summary and description

NEITHER summary NOR description may begin with: "This article", "This post", "This guide", "In this article", "In this post", "In this", "Here we", "A guide to", or a reworded copy of the title. Lead with the value or the concrete claim instead.

R7 — Never touch the body prose

Only formatting (headings, bold, lists, code, blockquotes) and the frontmatter may change. Never add sentences, delete content, shorten, or rephrase the author's words. Preserve voice, tone, and every word.

Worked examples

R1 — exact field set (BEFORE → AFTER)

BEFORE (base adds helpful extras — date, author, tags):

yaml
---
title: Caching Is a Distributed System
date: 2026-06-26
author: Engineering Team
tags: [caching, systems]
slug: caching-is-a-distributed-system
description: ...
---

AFTER (exactly four fields, correct order):

yaml
---
title: Caching Is a Distributed System
slug: caching-is-a-distributed-system
summary: Add a cache and you inherit a second source of truth to keep honest.
description: A cache turns one source of truth into two. Treat invalidation as a design decision up front, not a bug you patch later.
---

R2 — H1 moves into frontmatter (BEFORE → AFTER)

BEFORE (title duplicated as a body H1):

markdown
---
title: Postgres Is All You Need
slug: postgres-is-all-you-need
summary: ...
description: ...
---

# Postgres Is All You Need

You probably do not need Kafka, Redis, and Elasticsearch on day one.

AFTER (body H1 deleted; body starts with prose or ##):

markdown
---
title: Postgres Is All You Need
slug: postgres-is-all-you-need
summary: ...
description: ...
---

You probably do not need Kafka, Redis, and Elasticsearch on day one.

R3 — slug kebab-case (BEFORE → AFTER)

Title: Why We Switched to Postgres: A Field Guide BEFORE (base keeps casing/punctuation or uses snake_case):

yaml
slug: Why_We_Switched_to_Postgres:_A_Field_Guide

AFTER:

yaml
slug: why-we-switched-to-postgres-a-field-guide

R4 / R5 — summary value vs topic, and length ordering (BEFORE → AFTER)

BEFORE (topic restatement, and summary longer than description):

yaml
summary: This article is about how our team migrated the billing service to Rust and what we learned during the process.
description: A migration story.

AFTER (summary = punchy value, shorter than description):

yaml
summary: Rewriting billing in Rust cut p99 latency from 800ms to 40ms.
description: A Python billing service that timed out under load became a Rust one with 20x lower tail latency. Here are the migration surprises that mattered.

R6 — forbidden opening (BEFORE → AFTER)

BEFORE:

yaml
summary: This article explores why standups became status theater.

AFTER:

yaml
summary: Async, five-line standups gave the team its mornings back.

R7 — body prose preserved (BEFORE → AFTER)

BEFORE (base "improves" the wording while formatting):

markdown
We made standups async and capped them at five lines, reclaiming our focus time.

(original was: "We made them async, capped at five lines each, and got our mornings back.") AFTER (original words kept verbatim; only frontmatter/formatting added):

markdown
We made them async, capped at five lines each, and got our mornings back.

Edge cases & exceptions

• No H1 in source. Derive title from the content; still emit all four fields. The

body simply never gains a # line.

• An existing frontmatter field is already present. Keep an existing good title,

summary, or description; only fill the missing ones. But still strip any non-conforming extra keys (date, tags, …) per R1.

• Title has a colon or subtitle (Foo: A Field Guide). The colon and space become a

hyphen in the slug → foo-a-field-guide (no stray double hyphen).

• Numbers and ampersands in the title. Keep digits; spell-or-drop symbols: Cut Our

AWS Bill in Half → cut-our-aws-bill-in-half; Q&A → q-a (ampersand dropped, not kept).

• No real cover image. Do NOT add coverImage. It is the only conditional field and

it requires an actual image to exist.

• summary creeping past ~80 chars. Tighten it; the one-sentence, shorter-than-

description constraints are hard, not soft.

Do / Don't

• DON'T add date, author, tags, category, or excerpt. ALWAYS emit exactly

title, slug, summary, description (+ coverImage only if one exists).

• DON'T leave a # Title line in the body. ALWAYS move it into title and delete it.
• DON'T write the slug in Title Case, snake_case, or with punctuation. ALWAYS kebab-case,

lowercase, ASCII, single hyphens.

• DON'T open summary/description with "This article…". ALWAYS lead with the value.
• DON'T make summary longer than description. ALWAYS keep summary the shorter, one-

sentence field.

• DON'T reword, trim, or add to the body prose. ALWAYS preserve every original word.

Common mistakes (the base's wrong defaults)

1. Helpfully adding date, author, and tags — extra fields that violate the exact-four

rule.

1. Keeping the title as a body # H1 AND putting it in frontmatter — duplication.
2. Emitting a slug that mirrors the title's casing/punctuation, or using snake_case.
3. Writing summary as a topic restatement ("This article covers…") instead of value.
4. Making summary longer than description, or making them near-identical.
5. Silently polishing the author's sentences while "formatting."

Quick checklist

• ] Frontmatter has exactly title, slug, summary, description, in that order.
• ] No date/author/tags/category/excerpt/keywords.
• ] Body has no # H1; title is only in frontmatter.
• ] slug is lowercase kebab-case, ASCII, single hyphens, no punctuation.
• ] summary is one sentence (~50–80 chars), value-led, shorter than description.
• ] description is 2–3 sentences (~100–200 chars), longer than summary.
• ] Neither opens with "This article/post/guide" or restates the title.
• ] Body prose is byte-for-byte the author's.