Canonical markdown formatting conventions for diff-friendly documentation. Consult this skill when generating, editing, or reviewing markdown prose. Defines hybrid line wrapping, heading style, list spacing, and link conventions.
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.
When writing or editing markdown prose:
# Heading, never setext underlines)Wrap these content types at 80 characters:
>)- 1. Never wrap or reflow these content types:
```) or indented content#--- or +++[id]: url reference lines on their own lineFor each prose paragraph:
. ! ? ) before column 80, ; : ) before column 80and but or ) before column 80See modules/wrapping-rules.md for the full algorithm with
examples.
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.
WRONG:
Heading
=======
WRONG:
Subheading
----------
RIGHT:
# Heading
RIGHT:
## Subheading
WRONG:
Some introductory text:
- Item one
- Item two
RIGHT:
Some introductory text:
- Item one
- Item two
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.