Markdown Syntax Guide: From Basics to Tables to Diagrams

Markdown is a lightweight markup language created by John Gruber in 2004 that lets you write formatted text using plain text syntax. It has become the standard for README files, documentation, note-taking, blogs, and developer communication. This guide covers everything from basic syntax to advanced features across different Markdown flavors.

Core Syntax

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Text Formatting

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Title")
![Alt text](image.png)
![Alt text](image.png "Image title")

Lists

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item
   1. Nested ordered item

Code Blocks

```javascript
function hello() {
  console.log("Hello, world!");
}
```

Blockquotes

> This is a blockquote
> It can span multiple lines
>
> And have paragraphs

Extended Syntax (GFM and beyond)

Tables

| Header 1 | Header 2 | Header 3 |
|----------|:--------:|---------:|
| Left     | Center   | Right    |
| aligned  | aligned  | aligned  |

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Footnotes

Here is a footnote reference[^1].

[^1]: Here is the footnote content.

Markdown Flavor Comparison

Practical Tips

• README files: Start with a clear project title, badges, one-line description, installation, and usage sections.
• Documentation sites: Use consistent heading hierarchy (never skip levels). Include code examples for every concept.
• Table alignment: Use colons in the separator row: :--- (left), :---: (center), ---: (right).
• Line breaks: End a line with two spaces or use a blank line for a paragraph break. Behavior varies by flavor.

Convert between Markdown and other formats with WizlyTools: Markdown to HTML and HTML to Markdown.