What Is Markdown? A Complete Guide for Beginners With Examples
Learn the full Markdown syntax in one place: headings, links, tables, code blocks, task lists, flavours, and a complete cheat sheet you can bookmark and use every day.
Markdown is one of the most practical things a developer, writer, or content creator can learn. It takes roughly 15 minutes to pick up the basics, it works across virtually every platform you already use, and it never goes out of date. This guide covers everything: what Markdown is, why it matters, the complete syntax with working examples, and a full reference table to bookmark.
What Is Markdown?
Markdown is a lightweight markup language that uses plain-text formatting syntax. It was created by John Gruber in 2004 with one clear goal: to let people write in a format that is easy to read and easy to write, and that can be converted to HTML automatically without any special software.
In plain terms: Markdown lets you format text using symbols you already know how to type. You write symbols around your text and any Markdown-aware tool converts those symbols into proper HTML formatting when rendering the output.
- Item one
- Item two
Instead of clicking a Bold button in a toolbar, you type **bold**. Instead of selecting Heading 1 from a menu, you type # Heading 1. The result looks identical to what a word processor would produce, but you never had to leave the keyboard or reach for the mouse.
Markdown is the closest thing writing has to a universal language. Write it once, and it renders correctly on GitHub, Notion, Reddit, Stack Overflow, and thousands of other platforms without any changes.
Why Markdown Matters
Learning Markdown is a force multiplier for everything you write in a technical context. Once you know the syntax, your formatting skills transfer automatically across every platform you use. Here is where Markdown is used every single day:
Markdown files are plain text. They open in any text editor on any operating system without special software. They are searchable, version-controllable with Git, and future-proof. A Markdown file written today will still be readable in 30 years with no conversion needed.
The Complete Markdown Syntax
The following sections cover every core element of Markdown with live examples of both the input you type and the rendered output. All of these work in CommonMark-compatible renderers, which includes GitHub, Notion, VS Code preview, and most documentation tools.
Headings
Headings are created by placing one or more hash symbols at the start of a line, followed by a space. The number of hash symbols determines the heading level, which maps directly to HTML heading tags:
A page should typically have only one # Heading 1 as the main title. Use ## for major sections and ### for sub-sections. Heading hierarchy is important for both readability and accessibility: screen readers use it to navigate documents.
#Heading (no space) will not be recognised as a heading by most renderers. Write # Heading with a single space between the hash and the text. This is the single most common beginner mistake with headings.
Text Formatting
Bold and italic
Inline code
Both asterisks (*) and underscores (_) work for bold and italic. The convention in most style guides is to use asterisks for bold and italic, and underscores only when needed for disambiguation. Inline code wrapped in backticks (`) is rendered in a monospace font and ignores any Markdown formatting inside it, making it ideal for variable names, file paths, and command references.
Paragraphs and line breaks work differently from most word processors. A blank line between two blocks of text creates a new paragraph. A single line break in the source does not produce a new line in the rendered output. To force a line break within a paragraph, add two spaces at the end of a line before pressing Enter.
Unordered and Ordered Lists
For unordered lists, you can use a dash (-), asterisk (*), or plus sign (+). Dashes are the most common convention and the most readable in raw Markdown. For ordered lists, the actual numbers you type do not matter in most renderers: you can write 1. 1. 1. and it will render as 1, 2, 3. However, using sequential numbers in your source is best practice for readability when the file is opened raw.
Nesting lists works by indenting with two or four spaces (depending on the renderer). Mixing ordered and unordered lists in nested structures is fully supported and useful for complex outlines or multi-level instructions.
Links and Images
The syntax for images is identical to links, with one addition: a leading exclamation mark (!). The text inside the square brackets becomes the alt text, which is displayed when the image fails to load and is read by screen readers. Always write descriptive, meaningful alt text for accessibility.
Reference-style links keep the document body clean when you have many links. You define the URLs in a separate section at the bottom of the document and reference them by label throughout the body text. This is especially useful in long technical documents where the same URL appears multiple times.
Code Blocks and Blockquotes
For inline code, wrap the text in single backticks. For multi-line code blocks, wrap the code in triple backticks on their own lines. Adding a language name immediately after the opening backticks enables syntax highlighting on platforms that support it:
The language identifier after the opening backticks (javascript, python, json, bash, yaml, etc.) is used by the renderer to apply syntax highlighting. GitHub, VS Code, and all major documentation tools recognise dozens of language identifiers. Using the correct identifier makes code significantly easier to read for your audience.
Blockquotes are created by placing a greater-than symbol (>) at the start of a line. They can span multiple lines and can be nested by adding additional > characters. Blockquotes are commonly used for quotes, callouts, and highlighted notes in documentation:
When writing documentation that includes JSON examples, always validate the JSON before publishing. A missing comma or mismatched bracket in a JSON code block makes the example misleading. Paste your JSON snippet into the JSON Formatter to instantly check syntax and format it cleanly before adding it to your Markdown document.
Tables, Task Lists, and Horizontal Rules
Tables use pipe characters (|) to separate columns and hyphens to create the header separator row. Column alignment can be controlled by placing colons in the separator row:
A colon on the left of the separator (:---) means left-aligned. Colons on both sides (:---:) means centred. A colon on the right only (---:) means right-aligned. When no colons are present, the default is left alignment. Tables in Markdown render cleanly without writing any HTML table markup.
Task lists are a GitHub Flavored Markdown extension that renders interactive checkboxes. An x inside the brackets marks the item as complete. These are particularly useful in GitHub issues and pull requests to track progress:
Horizontal rules separate sections visually. Write three or more hyphens, asterisks, or underscores on a line by themselves to create a horizontal rule: --- or *** or ___.
Markdown Flavours: Why Syntax Varies Across Platforms
The original Markdown specification created by John Gruber in 2004 left certain edge cases ambiguous. Different platforms extended the spec in different directions, creating what are called "flavours." Understanding which flavour a platform uses tells you which extended features are available:
The core syntax (headings, bold, italic, links, lists, code) is identical across every flavour. The differences appear only in extended features like tables, task lists, footnotes, and embedded components. Writing in standard CommonMark syntax guarantees portability across every platform.
Need to convert Markdown content to YAML front matter, XML configurations, or other formats? Use the JSON to YAML Converter and JSON to XML Converter on StackDevTools to handle the structured data portions of your documents. For comparing two versions of a Markdown document to see what changed, the Text Diff Checker highlights every addition and deletion side by side.
Where Markdown Files Are Stored
Markdown files use the .md extension (sometimes .markdown). Every software project and documentation repository contains standard Markdown files that serve specific conventions in the development community:
Markdown vs HTML: When to Use Each
Markdown converts to HTML automatically. This raises a reasonable question: if the end result is HTML, why not just write HTML directly? The answer depends on who will edit the content and how frequently:
- Writing content that humans will read and edit frequently
- Working on a README, documentation file, or blog post
- Using a platform that renders Markdown natively
- The content is written prose with simple structure
- You want content to be portable across editors and platforms
- Non-developers also need to edit the content
- You need precise control over structure and attributes
- Embedding complex layouts that Markdown cannot express
- Working in a context where Markdown is not rendered
- Adding custom classes, IDs, or data attributes
- Building templates or component structures
- The output is always machine-generated, not human-edited
Most Markdown processors allow inline HTML inside a Markdown document. You can use standard HTML tags anywhere in your Markdown source when the Markdown syntax does not support what you need. This hybrid approach gives you the readability of Markdown for most content and the full power of HTML for complex elements.
Complete Markdown Cheat Sheet
Bookmark this table. Every element with its exact Markdown syntax and what it produces:
| Element | Markdown Syntax | HTML Output | Notes |
|---|---|---|---|
| Heading 1 | # Heading | <h1>Heading</h1> | One per page recommended |
| Heading 2 | ## Heading | <h2>Heading</h2> | Major section titles |
| Heading 3 | ### Heading | <h3>Heading</h3> | Sub-sections |
| Bold | **text** | <strong>text</strong> | Also: __text__ |
| Italic | *text* | <em>text</em> | Also: _text_ |
| Bold + Italic | ***text*** | <strong><em>text</em></strong> | Triple asterisks |
| Strikethrough | ~~text~~ | <del>text</del> | GFM extension |
| Inline Code | `code` | <code>code</code> | Monospace, no formatting inside |
| Link | [text](url) | <a href="url">text</a> | Add title in quotes after URL |
| Image |  | <img src="url" alt="alt"> | Alt text is required for accessibility |
| Unordered List | - item | <ul><li>...</li></ul> | Also: * or + |
| Ordered List | 1. item | <ol><li>...</li></ol> | Numbers auto-increment |
| Nested List | - item | Nested <ul> or <ol> | Indent with 2 spaces |
| Blockquote | > text | <blockquote>text</blockquote> | Nest with >> text |
| Code Block | ```lang ... ``` | <pre><code>...</code></pre> | Language enables highlighting |
| Table | | col | col | | <table>...</table> | GFM extension, use :--- for alignment |
| Task List | - [x] done | Checkbox input rendered | GFM extension, use [ ] for incomplete |
| Horizontal Rule | --- | <hr> | Also: *** or ___ |
| Line Break | text[2 spaces] | <br> | Two trailing spaces before Enter |
| Escape Character | \*literal\* | *literal* | Backslash escapes any symbol |
7-Step Workflow for Writing Markdown Effectively
Knowing the syntax is the easy part. Writing Markdown well, producing documents that are readable both raw and rendered, requires a consistent approach. This workflow covers the steps professionals use to write clean, portable, well-structured Markdown:
- Start with structure, not content. Before writing a word of body text, write all your heading levels. A # Title at the top, then ## for each major section, then ### for any sub-sections you know you need. This outline keeps your document organised and prevents heading-level drift halfway through a long document.
- Choose your flavour upfront. Check which Markdown variant the platform you are writing for uses. GitHub uses GFM. Docusaurus uses MDX. Most note-taking apps support CommonMark. Knowing this before you start prevents writing features (like footnotes or complex tables) that will not render correctly in your target environment.
- Write in plain text with a live preview. Use an editor with a side-by-side Markdown preview: VS Code with the built-in preview, Typora, or iA Writer. Seeing the rendered output alongside the raw text lets you catch formatting mistakes immediately rather than discovering them after publishing.
- Validate all code blocks and JSON examples. Any code block in your documentation should be syntactically correct. Copy JSON examples into the JSON Formatter to validate and format them before inserting. A broken JSON example in documentation is misleading for every reader who copies it.
- Use reference-style links for repeated URLs. If you link to the same URL more than twice in a document, switch to reference-style links. Define the URL once at the bottom: [label]: https://url. Reference it throughout: [text][label]. This makes the document easier to update when URLs change and keeps the body text more readable.
- Check heading hierarchy and link integrity. Before finalising, read through the heading structure to confirm it flows logically from h1 to h2 to h3 without skipping levels. Click every link in the preview to confirm it resolves correctly. Broken links and skipped heading levels are the two most common quality issues in published Markdown documents.
- Diff your changes before committing. When updating an existing Markdown document, use the Text Diff Checker to review exactly what changed between the old and new version. This is especially important for documentation that others depend on: it catches accidental deletions, formatting regressions, and unintended changes that are easy to miss in a full document review.
- One # H1 heading at the top and nowhere else
- All code blocks have a language identifier after the opening backticks
- All links tested and resolving correctly
- All JSON examples validated with the JSON Formatter
- Image alt text written for every image
- No heading levels skipped (h2 directly to h4)
- Document reads sensibly in raw plain text, not just rendered
Frequently Asked Questions About Markdown
No, but Markdown converts to HTML. Markdown is a plain-text authoring format with a simple syntax designed for human readability. HTML is the markup language that web browsers render. When you write Markdown, a Markdown processor converts it into HTML before displaying it. You can also embed raw HTML directly inside a Markdown document when you need more control over the output than Markdown allows, and most processors will pass the HTML through unchanged.
No. Markdown files are plain text, so any text editor works: Notepad on Windows, TextEdit on macOS, or VS Code anywhere. For a live preview while writing, VS Code has a built-in Markdown preview (press Ctrl+Shift+V or Cmd+Shift+V). Alternatives include Typora, iA Writer, Obsidian, and Zettlr, all of which render the output as you type. Online platforms like GitHub and Notion render Markdown automatically when you save or publish.
Different platforms support different Markdown flavours. A table written in GitHub Flavored Markdown syntax will not render correctly on a platform that only supports CommonMark. Features like task lists, strikethrough, and auto-linking are GFM extensions and are not part of the base specification. The safest approach is to use only core CommonMark syntax (headings, bold, italic, links, lists, code, blockquotes) when you need maximum portability, and use extended features only when you know the target platform supports them.
Base Markdown does not include automatic table of contents generation, but many tools add this feature. GitHub renders anchor links for every heading automatically, so you can manually create a table of contents using heading-level anchor links. Tools like MkDocs, Docusaurus, and VitePress generate tables of contents from heading structure automatically. Some Markdown editors (VS Code with extensions, Typora) can also insert a table of contents that updates as you write.
Standard Markdown does not support inline colour or custom styling. Markdown intentionally separates content from presentation. For basic styling needs, most Markdown processors allow inline HTML, so you can write <span style="color:red">text</span> directly in a Markdown file. For full styling control, the correct approach is to use CSS applied to the rendered HTML output rather than attempting to embed styling in Markdown source files. In documentation tools like Docusaurus, you can use MDX to embed React components with full styling capabilities.
Both extensions refer to the same file format and can be used interchangeably. The .md extension is far more common in practice because it is shorter and less typing. GitHub, most editors, and documentation tools recognise both extensions. The convention in software projects is to use .md for all Markdown files including README.md, CHANGELOG.md, and CONTRIBUTING.md. Use .md unless you have a specific reason to use .markdown.
Tools that work alongside your Markdown workflow
Validate JSON code blocks, compare document versions, convert between data formats, and generate slugs for your headings. All free, all in your browser, no login required.
Start Writing Markdown Today
Markdown has one of the best learning curves in programming: 15 minutes to learn the basics, a lifetime of usefulness. The syntax you learned today works on GitHub, in your note-taking app, in your documentation site, on Stack Overflow, and across Slack messages. You never have to re-learn it for a new platform.
Start with the essentials: headings, bold, italic, links, unordered lists, and inline code. Those six elements cover the majority of formatting needs in any document. Add tables and code blocks when you need them. Everything else in the cheat sheet is there when the situation calls for it.
Keep this guide bookmarked alongside the JSON Formatter and the Text Diff Checker. The formatter helps you keep code examples in your Markdown clean and valid. The diff checker helps you review changes to long documents without missing anything. Together, they cover the two most common quality checks in any Markdown-based documentation workflow.