Markdown: The Complete Developer's Guide to Writing with Markdown

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you write formatted text using a plain text syntax that is easy to read and easy to write. The magic of Markdown is that it looks good even in raw form, yet can be compiled into clean HTML, PDFs, or any other format you need.

Developers love Markdown because it removes the friction of formatting. No more wrestling with clunky rich text editors or writing bulky HTML tags by hand. If you need to convert Markdown to HTML quickly, use our free Markdown to HTML converter.

Why Developers Use Markdown

Markdown has become the de facto standard for documentation across the developer world:

• README files — every GitHub, GitLab, and Bitbucket repository uses Markdown for its README.
• Documentation sites — tools like Jupyter, MkDocs, Docusaurus, and Hugo all use Markdown as the source format.
• Note-taking — Obsidian, Notion, and Logseq all support Markdown natively.
• Forums and comments — Stack Overflow, Reddit, and Discord use Markdown-style formatting.
• Static site generators — Jekyll, Eleventy, and Astro all use Markdown for content.

Once you learn Markdown, you can write for almost any platform without switching tools.

Headers

Headers use # signs. The number of # symbols determines the level (H1 through H6).

# Heading 1 (H1)
## Heading 2 (H2)
### Heading 3 (H3)
#### Heading 4 (H4)
##### Heading 5 (H5)
###### Heading 6 (H6)

Always put a space after the # signs. Use only one H1 per page (typically the title), and structure your document with a logical hierarchy of H2 and H3 headings.

Bold and Italic

Use asterisks or underscores for emphasis:

*This text is italic*
_This text is also italic_

**This text is bold**
__This text is also bold__

***This text is bold and italic***

Single asterisk or underscore = italic. Double = bold. Triple = both. The asterisk syntax is more widely supported across platforms.

Lists

Unordered lists use -, *, or +:

- Item one
- Item two
  - Nested item (indent 2 spaces)
  - Another nested item
- Item three

Ordered lists use numbers. The actual numbers don't matter — Markdown auto-numbers them:

1. First item
2. Second item
1. Third item (renders as "3.")
   1. Sub-item (indent 3 spaces)

Links and Images

Links use square brackets for the display text and parentheses for the URL:

[Visit Wang Toolbox](https://wangtoolbox.com)

Images are identical to links but with an exclamation mark prefix:

![Alt text](https://wangtoolbox.com/favicon.ico)

You can also use reference-style links for cleaner source text:

[Wang Toolbox][1]

[1]: https://wangtoolbox.com

Code Blocks and Inline Code

Use backticks for inline code and triple backticks for code blocks:

Use the `console.log()` function to print to the console.

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
console.log(greet("World"));
```

Add the language name after the opening triple backticks to enable syntax highlighting. Supported languages include javascript, python, html, css, bash, sql, json, and many more.

Tables

Tables are created with pipes (|) and dashes (-):

| Feature       | Syntax           | Example             |
|---------------|------------------|---------------------|
| Bold          | `**text**`       | **bold**            |
| Italic        | `*text*`         | *italic*            |
| Code          | `` `code` ``     | `inline code`       |
| Link          | `[text](url)`    | [Link](https://...) |

The header row is separated from the body by a row of dashes. Colons align columns: :--- for left, :---: for center, ---: for right. Columns don't need to be perfectly aligned in the source, but doing so improves readability.

Blockquotes

Use the > symbol for blockquotes:

> This is a blockquote.
> It can span multiple lines.
>
> Use a blank line with `>` to separate paragraphs.

> **Nested quotes** work too:
> > This is nested inside.

Horizontal Rules

Three or more dashes, asterisks, or underscores create a horizontal line:

---
***
___

GitHub Flavored Markdown (GFM)

GitHub extends standard Markdown with several useful features:

• Task lists — - [x] Completed and - [ ] Pending for checkboxes.
• Strikethrough — ~~strikethrough~~ renders as strikethrough.
• Emoji — :rocket: renders as 🚀 (shortcode format).
• Autolinks — bare URLs like https://example.com become clickable links automatically.
• Tables with alignment — as described above.
• Fenced code blocks — triple backticks with language annotation.

Most modern Markdown processors support GFM features. If you are writing for GitHub, use the GFM style guide.

Markdown Editors and Tools

You don't need a special editor to write Markdown — any text editor works. But these tools make the experience better:

• VS Code — built-in Markdown preview (Ctrl+K V).
• Obsidian — a powerful note-taking app with Markdown at its core.
• Typora — a distraction-free Markdown editor with live preview.
• HackMD / HedgeDoc — collaborative Markdown editing.
• Our Markdown to HTML converter — instantly convert your Markdown to clean HTML.

Summary

Markdown is an essential skill for modern developers. With just a handful of simple syntax rules, you can write beautiful documentation, READMEs, notes, and more. Start with headers, bold, italic, and lists, then gradually add tables, code blocks, and blockquotes. In less than an afternoon, you will be fluent enough to write anything.