markdown-conventions

name	markdown-conventions
description	Conventions for writing or editing markdown. Use whenever you are writing or editing a .md or .markdown file.

Markdown conventions

Rules for writing and editing markdown in any repo.

Blank line before lists

Always include a blank line before a list (ordered or unordered). Some renderers won't recognize the list otherwise.

No two tildes on one line

In markdown prose, don't put two ~ characters on the same line. Some renderers I use pair them into strikethrough. A single ~ (e.g. ~100ms) is fine; two on one line (e.g. "takes ~100ms and ~3 retries") is not. Rewrite one or both as "about" or "roughly". Tildes inside backtick code spans are fine.

Don't renumber numbered lists item-by-item

If an insertion or deletion shifts numbers in a numbered list, do not fix it with sequential Edit calls — that's slow and easy to get wrong. Pick one:

• Use sed to renumber in one shot.
• Leave gaps in the numbering (markdown renderers don't care).
• Switch to an unordered list.

Wrapping markdown

When asked to wrap a markdown file, use:

prettier --prose-wrap always --print-width 80 --write <file.md> 2>&1