how-to · 6 min read
Markdown syntax: a practical guide
Markdown is a plain-text way to write structured documents. You add a few punctuation marks around text, and a renderer turns them into headings, lists, links, code blocks and tables. The file stays readable in any text editor, which is why READMEs, documentation, notes and issue trackers all use it.
The syntax is small, but small differences matter: a blank line creates a paragraph, spaces decide whether a line becomes a list item, and a single underscore inside a word can italicise half of it. This guide covers the syntax you will use daily and the failure modes that make rendered output look wrong.
What Markdown is and what it is not
Markdown was designed as a writing format that could be converted to HTML, not as a page description language. It has no concept of fonts, margins, page breaks or precise positioning; those belong to the stylesheet or the PDF converter that consumes the HTML. That is a feature: a Markdown file is still legible in a terminal, a code review or a plain text email.
The original syntax has no tables, task lists or footnotes. GitHub Flavored Markdown (GFM) added tables, fenced code blocks with language hints, task lists, strikethrough and autolinked URLs, and most modern tools follow that extension. If a table renders literally as pipes and dashes, the renderer probably does not support GFM tables, so check the tool's documentation before rewriting the content.
The syntax you will use every day
Block structure is controlled by blank lines. Paragraphs are separated by one empty line; a single line break is usually treated as a space unless the renderer supports hard breaks. Headings use one to six hash marks followed by a space, and the space is required in almost every implementation. Keep one level-one heading per document and build a hierarchy instead of skipping levels.
Inline formatting uses paired characters: double asterisks or underscores for bold, single asterisks or underscores for italic, backticks for inline code. Links are square brackets around the label followed by parentheses around the destination, and images add an exclamation mark before the brackets. Quote blocks start with a greater-than sign, and unordered lists accept dashes, asterisks or plus signs as long as you are consistent within a list.
- Heading: # Title, ## Section, ### Subsection (space after the hashes).
- Emphasis: **bold**, *italic*, ***bold italic***, `inline code`.
- Link: [visible label](https://example.com) and image: .
- Unordered list: one dash and a space per item; nested items need consistent indentation.
- Ordered list: 1. plus a space; the renderer renumbers automatically, so every item can start with 1.
- Quote: > before each paragraph; separate blocks with a blank line and another >.
- Code block: three backticks, an optional language name, the code, then three closing backticks.
Tables, code and extended syntax
A GFM table needs a header row, a separator row of dashes and optional colons for alignment, then data rows. Every row needs the same number of pipe characters, and a missing pipe silently shifts a column. Fenced code blocks are safer than indented code blocks because the fence survives copy-paste and the language hint enables syntax highlighting.
Task lists add a pair of brackets after the bullet: a space for unchecked and an x for checked. Footnotes and definition lists are extensions that vary between renderers, so avoid them when the document must survive conversion to PDF, a wiki or an email. When in doubt, test the exact renderer your audience uses instead of assuming all Markdown is identical.
A workflow that keeps Markdown readable
Write for the plain-text view first. Keep lines reasonably short, separate sections with blank lines, and put link destinations near their labels so the source remains understandable when wrapped in a narrow editor. Use relative links for files in the same repository and absolute URLs for external resources; a relative link to a file that was renamed becomes a broken link that nobody notices until a reader clicks it.
Preview while you write, especially after tables, nested lists and code fences. A live editor with a rendered preview catches a missing blank line before it reaches a release page. When you convert Markdown to HTML or PDF, keep the source under version control: the rendered output is disposable, while the Markdown is the document you can diff and review.
Where Markdown fits and where it does not
Markdown is excellent for documentation, release notes, README files, meeting notes, technical articles and anything that will be stored in Git. It is a poor fit for print layout, pixel-precise design, complex tables with merged cells, or documents that non-technical authors need to edit visually. In those cases write in a word processor and export, or use Markdown only as an intermediate source and apply a stylesheet for the final HTML.