Markdown Syntax Guide — Headings, Tables, Images, Links, and Line Breaks

Practical Markdown syntax for documents

Markdown uses a small set of symbols to describe document structure. It is readable as plain text and works well for READMEs, specifications, procedures, and meeting notes. Use #, ##, and ### for a logical heading hierarchy; do not use headings merely to enlarge text.

Separate paragraphs with a blank line. For a hard break inside one paragraph, use two trailing spaces or a backslash where supported. Use **bold**, *emphasis*, and GFM ~~strikethrough~~ sparingly.

Lists begin with - or a number. Indent nested items consistently. Links use [label](URL) and images use ![alternative text](path). Relative image paths may break when exported HTML is moved, so inspect images after export or use an embedded-image workflow.

Tables use pipes and a separator row:

| Item | Status | Count |
|:---|:---:|---:|
| Design | Done | 12 |

Avoid placing long paragraphs in table cells because a wide table can overflow a PDF page. Inline code uses one backtick, while fenced code blocks use three backticks and may include a language identifier. Long code lines may need manual wrapping for print.

Block quotes begin with >, horizontal rules can be written as ---, and GFM task lists use - [ ] and - [x]. Support for tables, task lists, raw HTML, and Mermaid varies among processors, so check the actual preview.

PDF adds fixed page boundaries that a continuous HTML page does not have. Before distribution, check page breaks and any clipped tables, images, or code. Start with semantic Markdown structure and add only the styling the document needs.

Headings and paragraphs

Use one H1 for the document title, H2 for major sections, and H3 for subsections. A heading requires a space after the hash. Keep headings short enough for a TOC and make them describe the question or task answered below.

A blank line creates a new paragraph. A single source newline is usually soft wrapping, not a visible line break. Use a backslash or two trailing spaces for an intentional hard break when supported, but do not replace semantic paragraphs merely to reduce spacing.

Lists and task lists

Bullets use -, while ordered steps use 1.. Indent child items consistently with spaces. A continuation paragraph or fenced code block must remain indented beneath its parent item. GFM task lists add [ ] or [x] after the bullet; they are still lists and follow the same nesting rules.

Use numbered lists only when order matters. A deeply nested hierarchy is usually clearer when promoted into headings and shallower lists.

Links and images

Write descriptive labels instead of “click here.” Include https:// for external URLs and avoid local machine paths in distributed documents. Image alt text should explain the figure's purpose. Relative image paths work only while the surrounding directory structure remains available; embed important images for a self-contained PDF.

Tables for comparison

Keep the separator row and a consistent number of columns. Alignment colons affect cells, not arbitrary page text. Reduce long URLs, code tokens, and prose-heavy cells before PDF export. A table taller than one page must be allowed to split or be divided into meaningful sections.

Code, quotes, and horizontal rules

Use inline code for commands and identifiers within prose. Fenced code is better for multi-line samples; add a language identifier for syntax highlighting. Do not paste complete logs when a small relevant excerpt explains the issue.

Block quotes are useful for short notes or cited passages, not for visual indentation. A horizontal rule separates major transitions but should not replace a heading structure.

Raw HTML and portability

Some Markdown environments allow <br>, <details>, or custom HTML, while security sanitizers remove them elsewhere. Prefer portable Markdown when the same source will be used on GitHub, a CMS, HTML export, Word, and PDF. Test raw HTML in every required destination.

Mermaid and mathematical notation are extensions, not core syntax. Declare these dependencies in a project writing guide so contributors know which preview is authoritative.

Document preflight checklist

• One H1 and a consistent H2/H3 hierarchy.
• Blank lines separate paragraphs and blocks.
• List indentation uses spaces consistently.
• Links have descriptive labels and valid destinations.
• Images load outside the author's machine.
• Tables fit the target page width.
• Code fences close and include the correct language.
• Raw HTML behaves in the final renderer.
• The saved PDF has been opened and reviewed.

Frequently asked questions

Which Markdown flavor should a team use?

GFM is practical for technical documents because it adds tables, task lists, and familiar GitHub behavior. The important choice is consistency: document the flavor and use the same preview for review and export.

Can Markdown control every PDF layout detail?

No. Markdown describes content structure. Paper size, margins, fonts, page numbering, covers, TOC generation, and page breaks belong to the conversion and print layer.

Continue with why Markdown PDFs look broken when valid syntax still produces a poor printed layout.