markdown-formatting

name	markdown-formatting
description	Enforces markdown line-wrap and structure rules for clean git diffs. Use when writing or editing any committed markdown documentation or skill file.
globs	**/*.md
alwaysApply	false
category	cross-plugin-patterns
tags	["markdown","formatting","documentation","line-wrapping","style"]
tools	[]
complexity	low
model_hint	fast
estimated_tokens	800
progressive_loading	true
modules	["modules/wrapping-rules.md"]
dependencies	[]

Markdown Formatting Conventions

When To Use

• Writing or editing any markdown documentation
• Reviewing prose for line-wrapping compliance
• Generating markdown from plugins (scribe, sanctum, etc.)

When NOT To Use

• Editing code blocks, tables, or frontmatter (these have their own formatting rules)
• Quick scratch notes that will not be committed

These conventions apply to all markdown documentation generated or modified by any plugin. The goal: produce prose that creates clean, reviewable git diffs and reads well on mobile devices.

Quick Reference

When writing or editing markdown prose:

1. Wrap prose at 80 chars using hybrid wrapping (prefer sentence/clause boundaries over arbitrary word breaks)
2. Blank line before and after every heading
3. ATX headings only (# Heading, never setext underlines)
4. Blank line before every list
5. Reference-style links when inline links push lines beyond 80 chars

What to Wrap

Wrap these content types at 80 characters:

• Paragraphs (flowing prose text)
• Blockquote text (the content after >)
• List item descriptions (text after - or 1. )
• Descriptions in definition lists

What NOT to Wrap

Never wrap or reflow these content types:

• Tables: pipe-delimited rows stay on one line
• Code blocks: fenced (```) or indented content
• Headings: lines starting with #
• Frontmatter: YAML/TOML between --- or +++
• HTML blocks: raw HTML elements
• Link definitions: [id]: url reference lines
• Image references: ![alt](url) on their own line
• Single-line list items: short bullets that fit on one line

Wrapping Algorithm (Summary)

For each prose paragraph:

1. If a sentence fits within 80 chars, keep it on one line
2. If a sentence exceeds 80 chars, break at the nearest ( ) before column 80