Markdown Syntax Guide

Markdown is a lightweight markup language for writing formatted text using plain, readable characters. Instead of clicking toolbar buttons, you type a few symbols — a # for a heading, asterisks for bold, a dash for a list item — and a Markdown processor turns them into structured HTML. The result stays easy to read even before it is rendered, which is exactly why it powers README files, GitHub issues, documentation sites, chat apps, note-taking tools, and static blogs.

The original Markdown spec was deliberately small, so over time it grew dialects. The most widely used today is GitHub-Flavored Markdown (GFM), which layers tables, task lists, strikethrough, and fenced code blocks on top of the CommonMark standard. Every example on this page uses GFM, the same flavor you get from GitHub, most AI assistants, and modern editors. When you are ready to turn your Markdown into something else, you can convert it to clean, semantic markup with our Markdown to HTML tool, or export a polished, searchable document with the Markdown to PDF converter — both run entirely in your browser.

This guide is organized so you can skim the table of contents, jump to the element you need, and copy a working snippet. Nothing here needs to be memorized: bookmark the page and come back whenever you forget how to align a table column or nest a list. Each live example is real Markdown rendered by the same engine that powers this whole site, so what you see is exactly what you get.

Create a heading by starting a line with one to six # characters followed by a space. One # is the largest, top-level heading (an <h1>), and six ###### is the smallest (an <h6>). Headings define the document outline, so use them in order — do not jump from an <h1> straight to an <h3> — and reserve a single <h1> for the page or document title.

Good heading structure is not just cosmetic: it builds the outline that screen readers, table-of-contents generators, and search engines rely on. On this page, the very table of contents you see on the left is generated straight from the section headings.

Wrap text in a single asterisk or underscore for italic, and in a double asterisk or underscore for bold. Combine them — triple asterisks — for bold italic. GitHub-Flavored Markdown adds strikethrough with a pair of tildes on each side, handy for showing edits or crossed-off items.

A common gotcha: emphasis needs to hug the text with no stray space between the marker and the word. Writing ** bold ** with inner spaces will not render as bold. When in doubt, keep the markers tight against the characters they wrap.

For a bullet (unordered) list, start each line with a -, * or + followed by a space — pick one marker and stay consistent. For a numbered (ordered) list, start lines with a number and a period. Markdown does not actually care whether your numbers are sequential; it renumbers them for you, so a list written 1. 1. 1. still renders as 1, 2, 3.

Nest items by indenting them two (or four) spaces under their parent. Keep the indentation consistent within a list — mixing two- and four-space indents is the single most common reason a nested list refuses to render the way you expect.

The basic link syntax is square brackets around the visible text, immediately followed by the URL in parentheses: [text](https://example.com). You can add a hover title in quotes inside the parentheses. For a URL you want to reuse or keep out of the flow of a sentence, use a reference-style link — a [label] in the text and a matching [label]: url definition elsewhere in the document. Bare URLs wrapped in angle brackets, like <https://example.com>, are auto-linked too.

Internal links between your own pages work exactly the same way — just use a relative path such as (/docs/getting-started). Well-chosen link text (never "click here") helps both readers and search engines understand where a link goes.

Images use almost the same syntax as links, with a leading exclamation mark: . The alt text in the brackets is not optional decoration — it is what screen readers announce and what shows if the image fails to load, so write a real, descriptive sentence. You can point the path at a URL or a relative file, and add a title in quotes just like links.

To make an image clickable, wrap the whole image in a link: put the image syntax inside the square brackets of a link. Markdown itself has no width or alignment controls, so for precise sizing you drop down to an HTML <img> tag, which every Markdown renderer accepts.

Wrap a snippet in single backticks for inline code — perfect for a function name or a file path inside a sentence. For a whole block, use a fence: three backticks on their own line, your code, then three closing backticks. Add a language name right after the opening fence (```js, ```python, ```bash) and most renderers, including GitHub, apply syntax highlighting.

If your code itself contains a run of backticks, open and close the fence with a longer run (four backticks) so the inner ones are treated as literal text. Fenced blocks preserve whitespace and line breaks exactly, which makes them the right home for anything indentation-sensitive.

GFM tables are built from pipes and dashes. The first row is the header, the second row is a line of dashes that separates the header from the body, and every row after that is data. Add colons to the separator row to control alignment: :--- is left, :---: is centered, and ---: is right. Your raw source does not need to line up perfectly — the renderer handles the spacing — but padding the columns with spaces makes the plain-text version far easier to read.

Tables are also the format people most often need to move in and out of spreadsheets. When you need to get a Markdown table into Excel, Google Sheets, or a data pipeline, our Markdown Table to CSV converter turns a pasted table into clean, spreadsheet-ready CSV in one step.

Start a line with a > to turn it into a blockquote — ideal for quoting someone, highlighting a note, or setting text apart. Add a second > to nest a quote inside a quote. Blockquotes can contain other Markdown too: put headings, lists, or even code inside them and they render normally.

To keep a multi-paragraph quote together, put a > on the blank line between paragraphs; otherwise the second paragraph breaks out of the quote.

Task lists are a GitHub-Flavored extension that turns list items into checkboxes. Write a normal bullet, then add [ ] for an unchecked box or [x] for a checked one, right after the marker. On GitHub, pull requests, and many editors these render as real, sometimes clickable, checkboxes — great for to-do lists, acceptance criteria, and release checklists.

GitHub-style callouts (also called alerts or admonitions) are blockquotes with a special first line: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], or > [!CAUTION]. Renderers that support them show a colored, icon-labeled box that draws the eye — perfect for warnings, tips, and things a reader must not miss. Where callouts are not supported they simply degrade to an ordinary blockquote, so they are safe to use.

Three or more dashes, asterisks, or underscores on their own line create a horizontal rule — a thematic divider between sections. For line breaks, remember that a single newline inside a paragraph is usually collapsed into a space; leave a blank line to start a new paragraph, or end a line with two trailing spaces (or a backslash) to force a hard line break without a new paragraph.

Many Markdown renderers, including this one, support LaTeX math through KaTeX. Wrap an expression in single dollar signs for inline math, or double dollar signs for a centered display equation on its own line. This is what makes Markdown a genuinely comfortable format for academic notes, homework, and technical specs full of equations.

When you need to hand that math to someone as a finished, searchable file, export it straight to a document with our Markdown to PDF tool — the equations stay crisp and the text stays selectable.