Markdown Formatting Guide: Syntax, Tips & Examples
Master Markdown formatting with this comprehensive guide. Learn syntax for headers, lists, links, images, code blocks, tables, and more with examples.
Markdown Basics: Headers, Paragraphs, and Emphasis
Markdown is a lightweight markup language that converts plain text into formatted HTML. Headers use hash symbols: # for H1, ## for H2, through ###### for H6. Paragraphs are created by separating text with a blank line — a single line break within text does not create a new paragraph (add two trailing spaces for a line break). For emphasis, wrap text in single asterisks or underscores for italic (*italic* or _italic_), double for bold (**bold**), and triple for bold italic (***bold italic***). Strikethrough uses double tildes (~~deleted text~~). These basics cover roughly 80 percent of Markdown usage for most documents.
Lists, Links, and Images
Unordered lists use -, *, or + followed by a space. Ordered lists use numbers followed by a period and space. Nested lists require four spaces of indentation. Links use the format [display text](URL), with an optional title: [Google](https://google.com "Search Engine"). Reference-style links define the URL separately: [text][id] with [id]: URL defined elsewhere in the document. Images are identical to links but prefixed with an exclamation mark: . For clickable images, nest an image inside a link: [](link-url). Blockquotes use > at the start of each line and can be nested with multiple > characters.
Code Blocks and Tables
Inline code uses single backticks: `const x = 5`. Code blocks use triple backticks with an optional language identifier for syntax highlighting: ```javascript followed by your code and closing ```. Indenting code by four spaces also creates a code block but does not support syntax highlighting. Tables use pipes (|) and hyphens: the header row is separated from data rows by a line of hyphens. Column alignment is controlled by colons in the separator row — :--- for left, :---: for center, ---: for right. Tables must have at least three hyphens per column in the separator row. Keep tables simple — complex data is often better presented as a list or formatted code block.
Recommended Resources
Sponsored · We may earn a commission at no cost to you
Advanced Markdown Features
Task lists use - [ ] for unchecked and - [x] for checked items — supported on GitHub, GitLab, and many other platforms. Footnotes use [^1] in the text with [^1]: definition at the bottom. Definition lists use the term on one line and the definition on the next, prefixed by a colon and space. Many platforms support emoji shortcodes like :smile: or :rocket:. HTML is valid within Markdown — you can use <details><summary>Click to expand</summary>Hidden content</details> for collapsible sections. Not all features are supported everywhere — GitHub Flavored Markdown (GFM), CommonMark, and other specifications have different feature sets.
Writing Better Documentation with Markdown
Start every document with a clear H1 title and a brief introduction explaining what the document covers and who it is for. Use headers to create a logical hierarchy — do not skip heading levels (jump from H2 to H4). Keep paragraphs short (3 to 5 sentences) and use lists for sequential steps or related items. Use code blocks for all technical content — commands, configuration, code examples — to distinguish them from prose. Include a table of contents for documents longer than 3 to 4 sections using linked headers. Preview your Markdown in the target platform before publishing, as rendering can vary between tools.
Related Free Tools
Related Articles
Frequently Asked Questions
What is the difference between Markdown and HTML?
Markdown is a simplified syntax that converts to HTML. It covers the most common formatting needs (headers, lists, links, emphasis, code) with minimal and readable syntax. HTML provides full control over document structure and styling but is more verbose and harder to read in source form. Markdown is ideal for documentation, README files, and content writing. HTML is necessary for complex layouts, forms, and interactive elements.
Which Markdown flavor should I use?
CommonMark is the standardized specification and the safest choice for broad compatibility. GitHub Flavored Markdown (GFM) extends CommonMark with task lists, autolinked URLs, tables, and strikethrough — use it for GitHub repositories and documentation. For note-taking, Obsidian and other tools add features like wiki-links and embedded queries. Choose based on where your content will be rendered.
Can I use Markdown for presentations?
Yes. Tools like Marp, Reveal.js, and Slidev convert Markdown files into presentation slides, usually using --- or a similar separator between slides. This is popular among developers because it keeps content in version-controlled text files, allows keyboard-driven editing, and produces clean, consistent slides without fighting with presentation software. The tradeoff is less visual control than PowerPoint or Google Slides.