Markdown Style Cheat Sheet (Version 1.0)

Compact version of the Markdown Coding Style.

1. Scope

• Applies to all project Markdown documents.
• This cheat sheet covers the project conventions that matter in practice.

2. Paragraphs and Manual Line Wrapping

• Do not manually wrap long paragraphs or list items.

3. Headings and Vertical Spacing

• Full guides use Setext headings (==== and ----) for the first two heading levels.
• Cheat sheets use ATX headings, including # and ##, instead of Setext headings.
• Leave three blank lines before second-level headings (## or ---- underlining) in normal documents.
• Leave two blank lines before third-level headings (###) in normal documents.
• Leave one blank line before any other heading level in normal documents.
• The extra blank-line rules apply only when the heading is followed by body content.
• If one 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 cheat-sheet heading.

4. Lists

• Use - for unordered lists unless a numbered sequence is required.
• In normal documents, 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.
• Otherwise, in normal documents, do not leave blank lines between bullet items.
• Cheat sheets must stay compact without blank lines between items.
• Keep each list item focused on one point.

5. Code Blocks and Inline Markup

• Prefer indented code blocks for code examples and 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, file names, identifiers, paths, commands, environment variables, and literal values.

6. Links and Related Documents

• Use real Markdown links when referring to related documents.
• Guides that have cheat sheets must link to the cheat sheet near the top.

7. Preference Rule

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