Markdown Style Guide (Version 1.0)

For a compact summary, see the Markdown Style Cheat Sheet.

1. Scope

This guide defines the Markdown conventions for project documentation.

This guide documents the project conventions that matter in practice. Expand it when the project adopts additional Markdown rules.

2. Paragraphs and Manual Line Wrapping

Do not manually wrap long paragraphs or list items.

Write each paragraph as a normal paragraph line unless a Markdown construct requires a forced break.

This keeps diffs smaller and makes later edits easier.

Examples:

Good:

This paragraph stays on one source line even when it becomes long enough to wrap visually in the editor.

Bad:

This paragraph is manually wrapped even
though it is still one logical paragraph.

3. Headings and Vertical Spacing

Leave vertical space before headings so document structure stays easy to scan in raw Markdown.

Full guides use Setext headings (==== and ----) for the first two heading levels.

Use ATX headings for deeper levels such as ### and below.

Cheat sheets use ATX headings, including # and ##, instead of Setext headings.

Leave three blank lines before second-level headings written as ## or as a Setext heading with ---- in normal documents.

Leave two blank lines before third-level headings written as ###.

Leave one blank line before any other heading level.

The extra blank-line rules apply only when the heading is followed by body content.

If a heading is followed directly by another heading, keep only the normal single blank line between them.

In cheat sheets, leave one blank line before every heading except the top-level heading at the start of the file. Do not leave a blank line after a heading.

4. Lists

Use - for unordered lists unless a numbered sequence is semantically required.

If a bullet list item would exceed 79 visible characters on one line, leave one blank line between adjacent items and two blank lines after the list.

The line break itself counts as a character, so 79 visible characters is the maximum that still fits in an 80-column editor without wrapping.

Cheat sheets must stay compact without blank lines between items.

Keep each list item focused on one point.

When an item needs more structure, either use sub-items or use multiple paragraphs per item.

5. Code Blocks and Inline Markup

Prefer indented code blocks for code samples, formulas, and other short literal blocks.

Use fenced code blocks only for logs or large console output that would look awkward when indented.

Use backticks for inline code, identifiers, file names, paths, commands, environment variables, and literal values.

6. Links and Related Documents

When referring to another project document, use an actual Markdown link instead of plain text.

If a guide has a corresponding cheat sheet, the guide links to that cheat sheet near the top as the compact representation of the same rules.

7. Preference Rule

Prefer valid Markdown, compact structure, and consistency with nearby project documents.

If a Markdown rule conflicts with the purpose of a compact cheat sheet, keep the cheat sheet compact and preserve Markdown validity.