Markdown Formatting

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 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.

Hybrid Line Wrapping Rules

Wrap prose text at 80 characters per line, preferring semantic boundaries (sentences, clauses) over arbitrary word breaks. This produces clean git diffs while keeping lines readable.

The Algorithm

When writing a prose paragraph, apply these rules in order:

Priority 1: Sentence Boundaries

If a sentence (ending with . ! or ? followed by a space) fits within 80 characters, keep it on one line.

BEFORE (single long line):
Install the plugin with npm. Configure it in your settings file. Restart the editor to activate.

AFTER (one sentence per line, each under 80 chars):
Install the plugin with npm.
Configure it in your settings file.
Restart the editor to activate.

Priority 2: Clause Boundaries

If a sentence exceeds 80 characters, break after the nearest comma, semicolon, or colon before column 80.

BEFORE (one 95-char sentence):
When the configuration file is missing, the system falls back to sensible defaults for all settings.

AFTER (break after comma at position 43):
When the configuration file is missing,
the system falls back to sensible defaults
for all settings.

Priority 3: Conjunctions

If no clause boundary exists before column 80, break before a conjunction: and, but, or, nor, yet, so.

BEFORE:
The parser reads the input file and transforms each node into an output token.

AFTER:
The parser reads the input file
and transforms each node into an output token.

Priority 4: Word Boundaries

If none of the above apply, break at the last word boundary before column 80.

BEFORE:
The implementation requires understanding the underlying architecture thoroughly.

AFTER:
The implementation requires understanding the underlying
architecture thoroughly.

Never Break Inside

These constructs must stay intact on a single line:

• Inline code: ` some_function_name ` stays together
• Link text: [link text] stays on one line
• Link URLs: (https://example.com/path) stays on one line
• Image syntax: ![alt](url) stays together
• Bold/italic spans: **bold text** stays together

If keeping these intact pushes a line beyond 80 chars, that is acceptable. Do not break the construct.

Exempt Content Types

Do NOT apply wrapping to any of these:

Blockquotes

For blockquote content, wrap the text inside the quote at 78 characters (80 minus the > prefix) following the same algorithm:

BEFORE:
> This is a very long blockquote line that exceeds 80 characters when you include the prefix marker.

AFTER:
> This is a very long blockquote line that exceeds
> 80 characters when you include the prefix marker.

List Items

For list items with long descriptions, wrap the continuation lines with appropriate indentation:

BEFORE:
- **markdown-formatting**: Canonical markdown formatting conventions for diff-friendly documentation generation and review.

AFTER:
- **markdown-formatting**: Canonical markdown formatting
  conventions for diff-friendly documentation generation
  and review.

Continuation lines align with the text start (2 spaces for - , 3 spaces for 1. ).

Reference-Style Links

When an inline link would push a line beyond 80 characters, convert to reference-style:

BEFORE:
See the [complete formatting guide](https://google.github.io/styleguide/docguide/style.html) for more details.

AFTER:
See the [complete formatting guide][fmt] for more details.

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

Place definitions at the end of the current section (after the last paragraph, before the next heading) or at the end of the document.

Examples: Full Paragraph

Before (no wrapping)

The scribe plugin detects AI-generated content markers and helps you remediate them. It analyzes vocabulary patterns, structural markers, and phrase patterns to calculate a slop density score on a 0-10 scale. Documents scoring above 2.5 should receive section-by-section review, while documents above 5.0 need a full rewrite to remove artificial patterns.

After (hybrid wrapping)

The scribe plugin detects AI-generated content markers
and helps you remediate them.
It analyzes vocabulary patterns, structural markers,
and phrase patterns to calculate a slop density score
on a 0-10 scale.
Documents scoring above 2.5 should receive
section-by-section review,
while documents above 5.0 need a full rewrite to remove
artificial patterns.

Note how each sentence starts on its own line when possible, and long sentences break at clause boundaries (after commas) or before conjunctions (and, while).