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.

Two companion pages cover the questions that come up around the syntax rather than inside it: what a .md file actually is if you are new to the format, and why Markdown sometimes refuses to render when the syntax looks correct but the output does not.

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.

If you have ever pasted an AI answer into Word and seen the asterisks show up as literal characters instead of bold text, that is the same syntax arriving somewhere that does not parse it — here is why that happens and how to paste it cleanly.

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.

To link to a heading inside the same document — an anchor link — point at the heading slug with a leading #. Most renderers build that slug by lowercasing the heading, dropping punctuation and replacing spaces with hyphens, so "## Getting Started" becomes (#getting-started). The exact rule is renderer-specific: GitHub strips emoji and resolves duplicate headings by appending -1, -2 and so on, while some static-site generators let you set an explicit id. When an anchor does not jump, view the rendered page and copy the id the renderer actually produced rather than guessing from the heading text.

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.

Footnotes let you park a citation, caveat or aside at the bottom of the document without breaking the sentence you are writing. They are an extended-syntax feature rather than part of the original spec, so support varies: GitHub, GitLab, Obsidian, Pandoc and most static-site generators render them, while a strict CommonMark parser will leave the markers as literal text.

The syntax has two halves. In the sentence, write a marker like [^1]. Anywhere else in the document — convention puts them at the end — define it with [^1]: followed by the note text. The label is just an identifier, not a position, so [^note] or [^source] work equally well and the renderer numbers them in the order they appear. That means you can reorder paragraphs without renumbering anything by hand.

Two details worth knowing. A footnote definition can hold multiple paragraphs if you indent the continuation lines by four spaces, which is useful for a longer aside. And a definition that is never referenced simply does not render — handy while drafting, but it also means a typo in the label silently drops the note, so check the output if a footnote goes missing.

Markdown has no comment syntax of its own. The CommonMark spec never defined one, so every method below is a workaround that exploits something else the parser already does — which is why support differs between tools and why the same trick can behave differently in two editors.

The dependable default is an HTML comment: anything between <!-- and --> is dropped from the rendered output. It works in essentially every renderer that handles inline HTML, spans multiple lines, and reads clearly to anyone who later opens the file. The one caveat is that it survives in the HTML source, so treat it as "hidden from readers", not as a secret — anyone viewing the page source can read it.

The alternative is the link-label trick: a line like [//]: # (a note) declares a reference-link definition that nothing in the document ever uses, and a CommonMark renderer discards unused definitions entirely. Unlike an HTML comment, this leaves no trace in the output at all, which makes it the better choice when the file will be published as HTML. It needs a blank line above and below, and it only works on its own line — you cannot hide something mid-sentence with it.

Some editors add their own. Obsidian hides text wrapped in %%double percent signs%%, and MDX files — used by Next.js, Astro and Docusaurus — need JSX-style {/* braces */} because MDX parses the file as JSX, where an HTML comment is not valid. If you are unsure which applies, paste the file into a viewer and look: a working comment is one you cannot see in the rendered pane.