How to Write and Format Documents in Markdown

Markdown is a plain-text format that uses a small set of punctuation conventions to indicate structure: a hash for a heading, asterisks for emphasis, dashes for list items, backticks for code. The source is readable as text — you can open a Markdown file in any editor and understand it without rendering — and a renderer converts it to HTML, PDF, or rich text for display. That dual nature, readable raw and presentable rendered, is why it became the default for documentation, READMEs, notes, and increasingly for prose of all kinds.

The alternative Markdown displaced was not other markup languages so much as the word-processor model, where structure and presentation are entangled in a binary format. A Markdown file is plain text, so it diffs cleanly in version control, opens in any editor on any platform, survives format obsolescence, and can be transformed into whatever output the future requires. These are not minor advantages for anything you want to keep.

The trade-off is that Markdown is structural, not presentational: it describes what something is (a heading, a list, a quote) rather than how it looks. If you need pixel-precise layout, Markdown is the wrong tool. If you need durable, portable, readable structured text, it is hard to beat.

The reliable core is small. Headings use one to six hashes for levels one through six. Paragraphs are separated by a blank line — a single newline within a paragraph is treated as a space by most renderers, which is the most common surprise for new authors. Emphasis uses single asterisks or underscores for italics, double for bold. Lists use dashes, asterisks, or plus signs for unordered items, and numbers for ordered ones (the actual numbers need not be sequential — renderers renumber).

Links are written as link text, and images as !alt text — the only difference is the leading exclamation mark. Code spans use single backticks; code blocks use triple backticks, optionally with a language identifier for syntax highlighting. Blockquotes use a leading angle bracket. Horizontal rules use three dashes, asterisks, or underscores on their own line.

Mastering this core covers the vast majority of real writing. The syntax is deliberately minimal because the design goal was to stay out of the author's way — the conventions are chosen to look like what people already type in plain-text email, so writing Markdown feels like writing, not like operating a formatter.

The original Markdown specification was minimal, and over the years different tools extended it in different directions — tables, task lists, footnotes, definition lists, strikethrough, and various code-fencing conventions. This is the source of most "it works in one place but not another" frustrations: a table written in GitHub-Flavored Markdown may not render in a tool that implements only the original spec.

The practical guidance is to know which flavour your target platform uses. GitHub, GitLab, and most modern documentation systems support GitHub-Flavored Markdown, which adds tables, task lists, strikethrough, and fenced code blocks with language hints. Some platforms add their own extensions — math rendering, diagrams, admonition blocks — that will not port elsewhere. If portability matters, stick to the widely supported subset and treat extensions as enhancements that degrade gracefully to readable text when unsupported.

Tables are the extension most worth learning, because tabular data is common and the alternative — HTML tables — defeats the readability purpose. The syntax uses pipes and dashes to sketch the table in text, which renders to an HTML table and remains legible in source. The one limitation to know: Markdown tables do not support cells spanning multiple columns or rows; for complex layouts, fall back to HTML or restructure the content.

Task lists are another widely supported extension worth knowing. A list item that begins with square brackets containing a space or an x renders as a checkbox that readers can tick in supporting platforms like GitHub. This turns a simple list into an interactive checklist, which is useful for tracking issues, project steps, or meeting action items directly in a document. Like tables, task lists are part of GitHub-Flavored Markdown and degrade gracefully — a platform that does not render them shows the brackets as plain text, which remains readable even if it is not interactive.

A few habits make Markdown documents more durable. Use heading levels hierarchically — one H1 per document, H2s for major sections, H3s beneath them — because many renderers generate a table of contents from heading structure, and skipping levels produces odd navigation. Separate paragraphs with a blank line consistently; relying on single newlines produces output that varies between renderers. Prefer reference-style links ([text][ref] with the URL defined elsewhere) for documents with many links, so the prose stays readable and the URLs are collected in one place.

For code, always specify the language on fenced blocks when you know it — the syntax highlighting is a significant readability improvement, and unknown languages degrade to plain text harmlessly. For images, always write meaningful alt text; it serves screen readers, shows when the image fails to load, and documents the image's purpose in the source.

Finally, keep lines reasonably short in source. Markdown does not care about line length — a paragraph can be one long line — but short lines make diffs readable in version control, where a change to one sentence shows as a change to one line rather than a change to the entire paragraph. This is a workflow consideration, not a rendering one, and it is the habit that pays off most when documents are edited collaboratively over time.

The most frequent Markdown error is treating a single newline as a paragraph break. In most renderers, a single newline within a paragraph collapses to a space — paragraphs require a blank line between them. Authors who press Enter once between thoughts are surprised when their paragraphs merge into one block. The fix is consistent: separate every paragraph with a blank line, and reserve single newlines for within-paragraph soft wraps that you do not expect to render as breaks.

The second common mistake is inconsistent or missing language identifiers on fenced code blocks. A block written as three backticks with no language renders as plain text, losing syntax highlighting that materially aids readability. Always specify the language when you know it — javascript, python, bash — because unknown languages degrade harmlessly to plain text, so there is no downside to being specific.

The third is heading hierarchy. Many renderers generate a table of contents from heading levels, and skipping from H1 to H3 (or using multiple H1s) produces broken navigation. Use one H1 per document, then H2 for major sections, H3 beneath them, never skipping a level. The fourth is link syntax: the link form requires no spaces around the URL, and image syntax differs from link syntax only by the leading exclamation mark — easy to omit, and the result renders as a link to the image rather than the image itself. These are small habits, but they are the difference between Markdown that renders cleanly everywhere and Markdown that surprises you on a different platform.

Write in a Markdown editor with a live preview so you see the rendered output as you type, which catches syntax errors immediately — a missing closing bracket on a link, a list that did not start on its own line, a heading that ran into the previous paragraph. Toggle between split, edit, and preview modes as the task demands: split while drafting, edit for focus, preview for a final read.

When the document is finished, copy the rendered HTML for a CMS that wants HTML, or keep the Markdown source for a system that renders it natively. The same source serves both, which is the point: write once, present anywhere. And because the source is plain text, it will open in twenty years in whatever editor exists then — a property few other document formats can promise.

Most Markdown editors also export to PDF or HTML directly, which is useful when you need a portable artifact rather than the editable source. The export uses the same renderer as the preview, so what you see in the preview pane is exactly what the export contains — no surprises between draft and final. Keep the Markdown source as the master and treat the exported file as a derived copy, the way you would treat a compiled binary alongside its source code. The Markdown Editor on this site runs entirely in your browser, so your drafts never leave your device while you write and preview them — a meaningful property for notes, drafts, and documents you would prefer not to transmit.