/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**: `` 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 **sentence boundary** (`. ` `! ` `? `) before column 80 3. If no sentence boundary, break at the nearest **clause boundary** (`, ` `; ` `: `) before column 80 4. If no clause boundary, break before a **conjunction** (`and ` `but ` `or `) before column 80 5. If none of the above, break at the last **word boundary** before column 80 6. Never break inside backtick spans, link text, or URLs

See `modules/wrapping-rules.md` for the full algorithm with examples.

Structural Rules

Blank Lines Around Headings

WRONG:
Some text.
## Heading
More text.

RIGHT:
Some text.

## Heading

More text.

Exception: the first line of a file may be a heading without a preceding blank line.

ATX Headings Only

WRONG:
Heading
=======

WRONG:
Subheading
----------

RIGHT:
# Heading

RIGHT:
## Subheading

Blank Line Before Lists

WRONG:
Some introductory text:
- Item one
- Item two

RIGHT:
Some introductory text:

- Item one
- Item two

Reference-Style Links for Long URLs

When an inline link pushes a line beyond 80 characters, use reference-style syntax:

WRONG (line too long):
See the [formatting guide](https://google.github.io/styleguide/docguide/style.html) for details.

RIGHT:
See the [formatting guide][fmt-guide] for details.

[fmt-guide]: https://google.github.io/styleguide/docguide/style.html

Place link definitions at the end of the current section or at the end of the document. When the same URL appears multiple times, use a single shared reference definition.

Short inline links that keep the line under 80 chars are fine:

OK:
See [the guide](https://example.com) for details.

Exit Criteria

• [ ] All prose lines in the edited file wrap at 80 characters or

fewer; verified with `awk 'length>80' <file>` returning no matches on prose blocks (tables, code, headings, frontmatter excluded)

• [ ] Every heading has a blank line before and after it (except

the first line of a file); no setext-style underline headings present

• [ ] Every list is preceded by a blank line
• [ ] Inline links that would push a line past 80 characters

converted to reference-style syntax with the URL definition at the end of the section or document