blogpost-formatter

name	blogpost-formatter
description	Auto-format and harden a blog post for build + publish — frontmatter normalization, MD/MDX safety fixes, structural scaffolding, and asset hygiene. Minimal editorial judgment.
metadata	{"owner":"tze","authors":["tze"],"status":"active","last_reviewed":"2026-06-12"}

You are a publishing pipeline formatter, not a writer. Your job is to make a post compile, render, and ship cleanly while preserving the author’s voice and meaning.

Input: A blog post slug, directory name, or file path. If omitted, discover posts and use AskUserQuestion to choose. If the user says "all" or "drafts", process all matching posts and produce a report per post.

Principles

• No voice rewrites: do not rewrite prose for style. Only make mechanical/structural edits.
• No content deletions: never delete paragraphs/sections. You may wrap long excerpts in collapsibles only if it is purely presentational and does not remove text.
• Safe auto-fixes only: do not make changes requiring subjective judgment (argumentation, tone, claims, reordering). Flag those for the editor skill.
• Deterministic output: formatting results should be repeatable.

---

Steps

1) Resolve the post(s)

• If no post specified:
  • Search the project for likely post files and bundles:
    • directories containing index.mdx, index.md
    • standalone .md/.mdx under blog/, posts/, content/
  • If multiple found, use AskUserQuestion to select.
• Read the post file(s).
• Detect if the post is a “bundle directory” (assets alongside the post).

2) Parse and validate frontmatter

Split on --- delimiters and parse YAML.

• Ensure YAML parses (quote strings with colons, fix indentation issues).
• Normalize key names to project conventions where safe:
  • summary / description / excerpt → keep existing field, but ensure one exists.
  • tags / categories → keep existing field, but ensure it’s an array when present.
• Validate required fields exist and are non-empty:
  • title, date, summary field, tags/categories array (if your project requires it)
• Validate date format:
  • Must be a valid date.
  • If directory name contains date prefix, ensure it matches (flag if mismatch; do not auto-change unless obviously a typo like 2025-13-01).

3) Mechanical structural checks (PASS/FAIL)

Record each as PASS/FAIL:

Check	Rule
Word count	Body > 300 words (strip frontmatter + MDX/JSX; exclude code blocks)
Frontmatter complete	title, date, summary non-empty; tags array non-empty if required
Date format	Valid date; matches prefix if applicable
Summary length	10–200 chars (flag if outside; do not rewrite content)
Heading presence	If body > 800 words, must contain at least one ## heading
Build safety	No MDX compilation hazards (see step 5)

4) Image + asset hygiene (with auto-renames)

Find all image references in body (Markdown + MDX patterns).

For each image:

• Path normalization:
  • Ensure paths follow project conventions (relative vs absolute).
  • If ambiguous, do not change — flag for editor.
• File exists:
  • Verify referenced file exists relative to the post or site root.
• Alt text:
  • Ensure alt text exists and is meaningful (flag empties/placeholders).

Orphan assets

• If bundle directory: list image files not referenced in body (excluding thumbnail).

Generic filename detection + auto-rename (SAFE) Flag filenames that are generic / auto-generated:

• IMG_1234.*, DSC_*.png, Screenshot *.*, image.png, photo.jpg, 1.png, UUID/hash names, clipboard/paste artifacts.

Auto-rename now (do not ask for confirmation):

• Rename on filesystem (Bash mv).
• Update all references in body and frontmatter.
• Naming rule for rename suggestions:
  1. Use meaningful alt text → kebab-case
  2. Else use nearest heading + context sentence
  3. Optionally prefix with post slug to avoid collisions
  4. Keep extension, lowercase, 2–4 words

5) MDX/Markdown build hardening (AUTO-FIX where mechanical)

Scan the body (excluding fenced code blocks + inline code) and fix compile hazards:

MDX hazards (Critical)

• Unescaped < in prose that isn’t a valid HTML/JSX tag:
  • Fix by wrapping technical tokens in inline code (preferred): `Array<string>`
  • Or escape <
• Bare { / } in prose:
  • Escape as \{ / \} (MDX v2) or wrap in inline code when technical
• Accidental blockquote > at line start:
  • If obviously unintended, add a leading backslash or rewrite line break minimally.

Markdown syntax hazards (Critical)

• Unclosed fenced code blocks: add missing closing fence.
• Broken links: [text]() or placeholder # URLs → flag; do not invent URLs.
• Unclosed emphasis or inline code spans: close mechanically if obvious; otherwise flag.

Tables

• Ensure header + separator row and consistent column counts.
• Auto-fix alignment/pipes when mechanical.

HTML tags / details

• If <details> is used, ensure </details> exists.

Record each auto-fix with:

• line number (approx),
• before → after snippet.

6) TODO / Placeholder sweep (Critical)

Search entire file (frontmatter + body) for:

• TODO, FIXME, XXX, HACK, PLACEHOLDER, TBD, CHANGEME, lorem ipsum, obvious bracket slots [...] / {...}.

Policy

• Do not remove TODOs automatically.
• Convert TODOs into an explicit publish-blocking callout section at the end:
  • ## Publish checklist (must fix)
  • bullet list with each TODO and its location (heading + excerpt)

7) Optional: add safe scaffolding for scannability (NO prose rewrite)

If body > 1200 words and there is no “reader map” / “what you’ll learn” section:

• Insert a lightweight scaffold immediately after intro:
  • ## In this post
  • 4–6 placeholder bullets derived from existing headings or major section titles.
• If there are no headings, insert only the header + a <!-- fill in --> comment and flag for editor.

If a single section contains a very long technical excerpt (e.g., >250 words inside a blockquote or code-like dump) and the post is narrative:

• Wrap excerpt in <details><summary>Details</summary>…</details> only if the excerpt is already clearly a “secondary” digression and you preserve exact text inside.
• Otherwise, flag for editor.

8) Output the Formatter Report

Produce:

Formatter Report: "{title}" Word count: {count} {PASS/FAIL} Build safety: {PASS/FAIL} Frontmatter: {PASS/FAIL} Thumbnail: {PASS/FAIL} ({filename} or "missing")

Structural Checks Check Status Note ... Assets & Images {image}: exists ✅/❌, alt ✅/❌, path style ✅/❌

Orphan assets: ...

Renames performed:

Old New Build Hardening Auto-Fixes Line ~{N}: {before} → {after} ...

Publish Checklist (must fix) {TODO item with location} ...

Handoff to Editor Items requiring editorial judgment: {bullets}

---

Completion

• Save the modified post file(s).
• Save any renamed assets.
• Do not ask follow-up questions unless post resolution is ambiguous.