Markdown in Five Minutes
The handful of markdown rules that cover almost everything: headings, bold, lists, links, code and blockquotes.
Headings are just hashes
Start a line with one to six hash marks to make a heading. A single hash is the biggest heading, two hashes the next size down, and so on. Most documents use one top-level heading for the page title and then two-level and three-level headings to break the body into sections. A blank line before each heading is what tells the renderer where one section ends and the next begins.
Emphasis with asterisks
Wrap a word in single asterisks to make it italic and in double asterisks to make it bold. Triple asterisks do both. Underscores work the same way. The rule is only useful if you apply it consistently: pick one style for emphasis and one for strong text and use it throughout, rather than mixing asterisks and underscores on the same page.
Lists come in two flavours
A line that starts with a dash, a plus or a star becomes a bullet point, and lines are joined into a single list as long as they are not separated by a blank line. A line that starts with a number and a period becomes a numbered list. You can nest one list inside another by indenting, which is how you build the sub-steps you see in most runbooks and checklists.
Links and images
A link is the text in square brackets followed by the address in parentheses, so visible text then destination. An image is the same syntax with an exclamation mark in front: a descriptive label in the brackets, then the image address. Because the address sits separately from the text, you can read the sentence naturally while the destination stays out of the way.
Code and quotes
Inline code is wrapped in backticks so it is set apart from prose without breaking the sentence. A block of code is fenced with three backticks on the lines above and below it, and you can name the language on the opening fence so the renderer highlights it. A blockquote starts with a greater-than sign, which indents the text and marks it as something quoted or called out.
One blank line between blocks
The most common markdown mistake is missing the blank line. Two paragraphs on adjacent lines with no blank line between them are joined into one, and a list or a heading pressed against a paragraph may not render at all. When in doubt, put a blank line around every block: before and after a heading, before and after a list, and between every two paragraphs.
Horizontal rules and line breaks
Three or more hyphens, asterisks or underscores on a line by themselves produce a horizontal rule, which is the markdown way to separate major sections without a heading. A single hard line break is made by ending a line with two spaces or a backslash, though most documents should prefer a new paragraph instead. The rule of thumb is to reach for a horizontal rule only when the sections are genuinely unrelated, not as a decorative divider between every paragraph.
Task lists
A list item that starts with square brackets containing a space or an x becomes a checkbox: a dash, a space, an open bracket, a space or an x, a close bracket, then the text. This is the syntax GitHub and most modern renderers use for to-do lists, and it is why a checklist in a markdown file can be ticked off by editing the source. Not every renderer supports it, so use it where you know the target supports it and fall back to a plain bullet elsewhere.