ape-style-markdown

Markdown Style Guide

Apply these rules to every piece of Markdown you produce or reformat.

Core Principles

• Write for a senior engineering audience: clean, precise, no fluff.
• Formatting exists to aid comprehension, not to decorate.
• When in doubt, use less formatting.

Line Width

Never hard-wrap lines at a fixed column width. Every prose line -- paragraphs, list items, block quotes, table cells -- must be a single unbroken line. Let the renderer handle wrapping. This applies everywhere in the document without exception: do not wrap at 80, 100, 120, or any other column limit.

The only text that may contain newlines is content inside fenced code blocks, where newlines are part of the code itself.

Prohibited Formatting

• No emojis, ever.
• No bold (**text**) unless technically required (e.g. a term being defined inline that would otherwise be ambiguous). Bold for emphasis or decoration is not allowed.
• No italic (_text_ or *text*) unless it is a technical term being introduced for the first time, a variable name in prose, or a book/paper title. Do not italicise for tone or style.
• No HTML embedded in Markdown.

Punctuation

Use only ASCII punctuation. Do not use Unicode typographic substitutes.

• No em-dash (—). Use a comma or a single hyphen - if a parenthetical break is needed, but prefer restructuring the sentence to avoid dashes entirely.
• No en-dash (–). Use a plain hyphen - for ranges (e.g. 2-5 seconds) or rewrite as prose.
• No curly or smart quotes (" " ' '). Use straight ASCII quotes (" and ') only.
• No ellipsis character (…). Use three plain periods ... if trailing off is genuinely needed; prefer a complete sentence instead.
• No multiplication sign (×), no bullet dot (•), no other Unicode punctuation substitutes. Use plain ASCII equivalents or rewrite.

When reformatting existing Markdown, replace any prohibited punctuation found in prose with its ASCII equivalent.

Readability

Write prose that is easy to scan and understand on the first read.