The Complete Markdown Guide: Syntax, Tables, Task Lists, and Code Blocks

Markdown is the closest thing to a universal writing format for digital professionals. GitHub, Notion, Obsidian, Slack, Discord, Stack Overflow, and dozens of documentation platforms all support it. Learn it once, use it everywhere.

Headings

Hash characters create headings: # = H1, ## = H2, up to ###### = H6. Use H1 for page title, H2 for major sections, H3 for subsections. Do not skip levels.

Text Formatting

**bold** → bold. *italic* → italic. ~~strikethrough~~ → strikethrough. `inline code` → code. Combine: **_bold italic_**.

Lists and Task Lists

Unordered: lines starting with - or *. Ordered: lines starting with 1.. Task lists: - [ ] unchecked, - [x] checked. Indent with 2 spaces for nested items.

Code Blocks

Fenced blocks use triple backticks with an optional language identifier for syntax highlighting:

```javascript
const x = 'hello';
```

Tables

| Column 1 | Column 2 |
|----------|----------|
| Cell A   | Cell B   |

Alignment: :--- left, :---: centre, ---: right.

Links, Images, Blockquotes

Links: [text](url). Images: ![alt](url). Blockquotes: lines starting with >. Horizontal rule: --- on its own line.

Live Preview

Use UltraToolkit's Markdown Previewer to write and instantly see the rendered output in a split-pane interface. Toolbar buttons insert syntax without memorising it. Copy as HTML or as Markdown with one click.

Markdown for Developers

Developers use Markdown in more contexts than any other professional group. GitHub READMEs, pull request descriptions, issue comments, GitHub Pages sites, JSDoc documentation, Confluence wiki pages, Notion documents, and technical blog posts on Medium and Dev.to all use Markdown or a Markdown dialect. A developer who writes clear, well-structured Markdown documentation is demonstrably more effective at communicating technical information to teammates and open-source contributors than one who writes poorly structured or unformatted documentation.

Markdown Across Different Platforms

Markdown has been adopted as the standard writing format across the software development ecosystem. GitHub uses it for README files, issues, pull request descriptions, and wikis. Notion uses a Markdown-inspired format for all content blocks. Slack and Discord use a subset of Markdown for message formatting (bold with asterisks, italic with underscores, code with backticks). Confluence supports Markdown import for technical documentation. Understanding Markdown makes you fluent in the native writing format of these platforms without learning a separate interface for each.

The subtle dialect differences between platforms create occasional cross-platform friction. GitHub's task list syntax (- [ ] unchecked, - [x] checked) is supported on GitHub but not all other Markdown renderers. Tables work on GitHub, Notion, and most static site generators but not in Slack messages. Nested lists work consistently across platforms but nested blockquotes (> > text) render differently. For cross-platform content, sticking to the CommonMark standard subset — headings, bold, italic, links, code blocks, and simple lists — ensures consistent rendering everywhere.

Markdown Tooling for Writers

Dedicated Markdown editors provide a superior writing experience to general text editors for Markdown-heavy workflows. Typora (paid) renders the Markdown formatting inline as you type — you never see the raw markup syntax, only the formatted output. Obsidian (free) is a knowledge management tool built on Markdown files with a powerful link graph for connecting notes. iA Writer (paid) provides a distraction-free writing environment with Markdown support and live preview. VS Code with the Markdown All in One extension provides a powerful free alternative with split-pane preview and keyboard shortcuts for common formatting.

For collaborative writing in Markdown, HackMD.io provides real-time collaborative Markdown editing with a Google Docs-like simultaneous editing experience. This fills the gap between static Markdown files (not easily collaborative) and Google Docs (not natively Markdown). For technical teams that write documentation in Markdown but need non-technical collaborators to review, HackMD provides an accessible interface without requiring reviewers to understand Markdown syntax.

Markdown for Content Management

Static site generators built on Markdown — Jekyll, Hugo, Eleventy, Gatsby — enable a content management workflow where content is version-controlled alongside code in a Git repository. Every content change is a Git commit with a clear author, timestamp, and diff showing exactly what changed. This versioning is more rigorous than most CMS change tracking, provides full rollback capability to any previous version, and enables branch-based content review workflows where changes are proposed via pull requests and reviewed before publishing.

The JAMstack architecture — JavaScript, APIs, and Markup — uses Markdown content files pre-rendered to static HTML by the build tool. The static HTML is served from a CDN with no server-side processing on each request, producing extremely fast page loads and high reliability. Content editors write Markdown files (through a Git-based CMS like Netlify CMS, Forestry, or Decap), the build tool converts them to HTML, and the CDN serves the static output globally. This architecture is both faster and cheaper to operate than traditional CMS-based sites at equivalent traffic levels.