Writing Tools

Markdown Guide: Everything You Need to Know

WritePadPro Team 10 min read

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you write formatted text using plain text syntax -- simple characters like # for headings, ** for bold, and - for lists. The formatted text can then be converted to HTML for web publishing, or rendered directly by platforms like GitHub, Reddit, Stack Overflow, Discord, Slack, and Notion.

Practice Markdown with live preview in WritePadPro's Markdown Editor -- type Markdown on the left, see the rendered HTML on the right in real time.

Markdown's genius is its readability. Unlike HTML where a heading requires <h1>Title</h1>, Markdown uses # Title. Unlike HTML where bold requires <strong>text</strong>, Markdown uses **text**. The plain text source is almost as readable as the rendered output -- which was Gruber's explicit design goal. He wanted a format that was "publishable as-is, as plain text, without looking like it has been marked up with tags or formatting instructions."

Where Markdown Is Used

  • GitHub -- README files, issues, pull requests, wikis, comments
  • Documentation -- Jekyll, Hugo, MkDocs, Docusaurus, GitBook
  • Blogging -- Ghost, Jekyll, Hugo, Gatsby, many static site generators
  • Note-taking -- Obsidian, Notion, Bear, Typora, Joplin
  • Communication -- Slack, Discord, Reddit, Stack Overflow, Telegram
  • Technical writing -- API docs, knowledge bases, internal wikis

Headings

Create headings by starting a line with one or more # symbols. The number of hashes determines the heading level (1-6).

# Heading 1 (largest)\n## Heading 2\n### Heading 3\n#### Heading 4\n##### Heading 5\n###### Heading 6 (smallest)

Rules:

  • Always put a space between the # and the heading text
  • Use only one H1 per document (the document title)
  • Do not skip levels -- go H1 to H2 to H3, not H1 to H3
  • Leave a blank line before and after headings for compatibility

Text Formatting

Bold

**bold text** or __bold text__

Renders as: bold text

Italic

*italic text* or _italic text_

Renders as: italic text

Bold and Italic

***bold and italic*** or ___bold and italic___

Renders as: bold and italic

Strikethrough

~~strikethrough text~~

Renders as: strikethrough text

Inline Code

Use `backticks` for inline code

Renders as: Use backticks for inline code

For converting your Markdown to HTML programmatically, see our Markdown to HTML Guide.

Links and Images

Links

[Link Text](https://example.com)\n[Link with title](https://example.com "Hover title")

Renders as: Link Text

Images

![Alt text](image-url.jpg)\n![Logo](logo.png "Optional title")

The syntax is identical to links but with an exclamation mark prefix. Alt text is required for accessibility.

Reference-Style Links

For documents with many links, reference-style keeps the text readable:

Read the [Markdown guide][1] and the [HTML guide][2].\n\n[1]: https://writepadpro.com/blog/markdown-complete-guide\n[2]: https://writepadpro.com/blog/html-entities-guide

The link definitions can be placed anywhere in the document -- typically at the bottom. The Markdown to HTML converter handles both inline and reference-style links.

Lists

Unordered Lists

- Item one\n- Item two\n  - Nested item\n  - Another nested item\n- Item three

You can use -, *, or + as bullet markers. Be consistent within a document.

Ordered Lists

1. First item\n2. Second item\n3. Third item\n   1. Nested ordered item\n   2. Another nested item

The actual numbers do not matter for rendering -- Markdown auto-numbers. But using correct sequential numbers improves plain text readability.

Task Lists (GitHub-Flavored)

- [x] Complete task\n- [ ] Incomplete task\n- [ ] Another incomplete task

Renders as checkboxes. Supported on GitHub, GitLab, and many Markdown renderers.

Code Blocks

Indented Code Block

Indent every line by 4 spaces or 1 tab:

    function hello() {\n        console.log("Hello");\n    }

Fenced Code Block (Preferred)

Wrap code in triple backticks with an optional language identifier:

```javascript\nfunction hello() {\n    console.log("Hello");\n}\n```

The language identifier enables syntax highlighting on platforms that support it (GitHub, GitLab, VS Code preview, Hugo, Jekyll). Common identifiers: javascript, python, php, html, css, json, bash, sql, java, go, rust, typescript.

Blockquotes, Horizontal Rules, and Tables

Blockquotes

> This is a blockquote.\n>\n> It can span multiple paragraphs.\n>\n> > Nested blockquotes use double arrows.

Blockquotes are used for quotations, callouts, and highlighted information.

Horizontal Rules

---\nor\n***\nor\n___

Creates a horizontal divider line. Use blank lines before and after for compatibility.

Tables

| Column 1 | Column 2 | Column 3 |\n|----------|----------|----------|\n| Cell 1   | Cell 2   | Cell 3   |\n| Cell 4   | Cell 5   | Cell 6   |

Alignment:

| Left     | Center   | Right    |\n|:---------|:--------:|---------:|\n| aligned  | aligned  | aligned  |

Tables are supported in GitHub-Flavored Markdown (GFM) and most modern renderers. For converting existing HTML tables to Markdown, see our HTML to Markdown Guide.

Extended Syntax (GitHub-Flavored Markdown)

Beyond the original Markdown spec, GitHub-Flavored Markdown (GFM) and other implementations add useful extensions.

Footnotes

This claim needs a source[^1].\n\n[^1]: Author Name, "Article Title," Journal, 2024.

Supported by GitHub, Hugo, Jekyll with plugins, and many static site generators.

Definition Lists

Term\n: Definition of the term\n\nAnother Term\n: Its definition

Supported by PHP Markdown Extra and some static site generators. Not in standard GFM.

Abbreviations

The HTML specification is maintained by the W3C.\n\n*[HTML]: Hyper Text Markup Language\n*[W3C]: World Wide Web Consortium

When rendered, hovering over "HTML" shows the full expansion. Supported by PHP Markdown Extra.

Automatic URL Linking

Most Markdown renderers automatically convert bare URLs to clickable links:

Visit https://writepadpro.com for details.

Becomes: Visit https://writepadpro.com for details.

Escaping

To display a literal character that Markdown would interpret as formatting, prefix it with a backslash:

\*not italic\*\n\# not a heading\n\[not a link\]

Characters that can be escaped: \ ` * _ { } [ ] ( ) # + - . ! |

For focus-based writing without the distraction of preview panes, see our Focus Writing Guide. For building and previewing code alongside Markdown, see the Code Playground Guide.

Markdown vs HTML: When to Use Which

CriterionMarkdownHTML
Readability of sourceHighly readable as plain textCluttered with tags
Learning curveMinutes to learn basicsHours to learn fundamentals
Formatting powerLimited (headings, bold, links, lists, code, tables)Complete (any web layout)
Custom stylingNo (depends on renderer CSS)Full control (inline styles, classes)
PortabilityWorks everywhere (GitHub, CMS, docs, notes)Requires a browser or renderer
Version controlClean diffs (plain text changes)Noisy diffs (tag changes mixed with content)
Use caseDocumentation, blogs, notes, README filesWeb pages, email templates, complex layouts

The recommendation: use Markdown for content-focused writing where structure matters more than visual design. Use HTML when you need precise layout control, custom styling, or interactive elements. WritePadPro's Markdown to HTML converter bridges the gap -- write in Markdown, export to HTML when needed.

Using WritePadPro's Markdown Editor

WritePadPro's Markdown Editor provides a split-pane writing environment with live HTML preview.

Step 1: Open the Editor

Navigate to the Markdown Editor. The left panel is for Markdown input, the right panel shows the live-rendered HTML preview.

Step 2: Write Markdown

Type Markdown syntax in the left panel. As you type, the right panel updates in real time -- you see headings, bold text, links, images, code blocks, and tables rendered instantly.

Step 3: Use the Toolbar

The toolbar provides quick-insert buttons for common syntax: headings, bold, italic, links, images, code blocks, lists, blockquotes, and tables. Click a button to insert the syntax at your cursor position.

Step 4: Copy or Export

Copy the Markdown source for use in GitHub, documentation platforms, or static site generators. Or copy the rendered HTML for use in web pages, email templates, or CMS content fields.

Privacy

All rendering runs locally in your browser. Your Markdown content is never transmitted to any server.

Summary

Markdown is a lightweight markup language that converts plain text formatting to HTML. Its syntax covers headings (#), bold (**), italic (*), links ([text](url)), images (![alt](url)), lists (- or 1.), code blocks (```), blockquotes (>), tables (| pipes |), and horizontal rules (---).

Extended syntax adds task lists, footnotes, definition lists, abbreviations, and strikethrough. Markdown is used across GitHub, documentation platforms, static site generators, note-taking apps, and messaging platforms.

Practice and write Markdown with WritePadPro's Markdown Editor -- split-pane editing with live HTML preview, running entirely in your browser.

Tags

Markdown syntax formatting GitHub documentation static sites writing

Frequently Asked Questions

What is the difference between Markdown and HTML?

Markdown is a simplified syntax that converts to HTML. The Markdown '## Heading' becomes the HTML '<h2>Heading</h2>'. Markdown is much easier to read and write but has limited formatting options -- it covers headings, emphasis, links, images, lists, code, tables, and blockquotes. HTML provides complete control over web layout including custom classes, inline styles, forms, interactive elements, and complex structures. Use Markdown for content-focused writing (documentation, blog posts, notes). Use HTML when you need precise visual control.

Is Markdown the same everywhere?

No. The original Markdown specification by John Gruber is intentionally minimal and ambiguous on some edge cases. This led to multiple implementations with slightly different behavior. CommonMark (2014) standardized the core syntax with a formal specification. GitHub-Flavored Markdown (GFM) extends CommonMark with tables, task lists, strikethrough, and auto-linking. Other extensions exist in PHP Markdown Extra, MultiMarkdown, and platform-specific implementations. The core syntax (headings, bold, links, lists, code) works identically everywhere. Extended features (tables, footnotes, task lists) vary by platform.

How do I create a table in Markdown?

Use pipes (|) to separate columns and hyphens (-) for the header separator row. Minimum syntax: | Header 1 | Header 2 | followed by |----------|----------| followed by | Cell 1 | Cell 2 |. For alignment, add colons to the separator row: |:--------| for left-aligned, |:--------:| for centered, |--------:| for right-aligned. Columns do not need to be visually aligned in the source -- the renderer handles spacing. WritePadPro's Markdown Editor toolbar includes a table insert button that generates the syntax automatically.

Can I use HTML inside Markdown?

Yes. Most Markdown renderers allow raw HTML to be embedded directly in Markdown content. This is useful for features Markdown does not support -- details/summary elements, custom divs with classes, embedded videos, or complex tables. Simply write the HTML inline with your Markdown. However, Markdown syntax is not processed inside HTML block elements -- if you open a div tag, Markdown formatting inside that div is typically ignored. Some platforms (GitHub, sanitized CMS editors) strip or limit HTML in Markdown for security reasons.

What is the best Markdown editor?

It depends on your use case. For web-based editing with live preview, WritePadPro's Markdown Editor provides split-pane editing directly in your browser with no installation. For desktop apps: Typora (seamless live preview), Obsidian (note-taking with linking), VS Code (coding with Markdown preview). For mobile: iA Writer (iOS/Android), Bear (Apple ecosystem). For documentation: MkDocs or Docusaurus with a code editor. The 'best' editor is the one that fits your workflow -- try WritePadPro's browser-based editor for quick Markdown writing without installing anything.

Related Tools

Markdown Editor → Markdown to HTML Converter → HTML to Markdown Converter →

Related Articles

Markdown to HTML Conversion: How It Works and When to Use It

Convert Markdown to clean, semantic HTML. Understand how the conversion works and when to use it for blogs,...

HTML to Markdown: Convert Web Content to Clean Markdown

Convert HTML content into clean Markdown syntax. Learn when HTML-to-Markdown conversion is useful and use WritePadPro's...