What is Markdown?
Markdown is a lightweight markup language created by John Gruber in 2004. It allows you to write formatted text using plain text syntax that's easy to read and write. Markdown is widely used for documentation, README files, blogs, and increasingly for AI prompt engineering.
Markdown Flavors
Markdown Studio supports multiple markdown flavors:
- CommonMark — The standard specification
- GitHub Flavored Markdown (GFM) — Tables, task lists, strikethrough
- Extended Syntax — Math equations, footnotes, highlights
- Mermaid — Diagrams and charts
Syntax Reference
Headings
| Syntax | Result |
|---|
# Heading 1 | Largest heading |
## Heading 2 | Second level |
### Heading 3 | Third level |
#### Heading 4 | Fourth level |
##### Heading 5 | Fifth level |
###### Heading 6 | Smallest heading |
Text Formatting
| Syntax | Result |
|---|
**bold text** | bold text |
*italic text* | italic text |
***bold and italic*** | bold and italic |
~~strikethrough~~ | strikethrough |
==highlighted== | highlighted (extended) |
`inline code` | inline code |
H~2~O | subscript (extended) |
X^2^ | superscript (extended) |
Links & Images
| Syntax | Result |
|---|
[Link text](https://example.com) | Clickable link |
[Link with title](https://example.com "Title") | Link with hover title |
 | Image |
 | Image with title |
<https://example.com> | Auto-linked URL |
<email@example.com> | Auto-linked email |
Lists
| Syntax | Result |
|---|
- Item 1
- Item 2
- Item 3 | Unordered list |
* Item 1
* Item 2 | Unordered (asterisk) |
1. First
2. Second
3. Third | Ordered list |
- [ ] Task
- [x] Done | Task list (GFM) |
- Item
- Nested
- Deep | Nested list |
Blockquotes
| Syntax | Result |
|---|
> Quote text | Simple quote |
> Line 1
> Line 2 | Multi-line quote |
> Outer
>> Nested | Nested quotes |
GitHub Alerts (GFM)
| Syntax | Result |
|---|
> [!NOTE]
> Useful information | Blue note callout |
> [!TIP]
> Helpful advice | Green tip callout |
> [!IMPORTANT]
> Key information | Purple important callout |
> [!WARNING]
> Potential issues | Yellow warning callout |
> [!CAUTION]
> Dangerous actions | Red caution callout |
Code Blocks
| Syntax | Result |
|---|
```
code here
``` | Plain code block |
```javascript
const x = 1;
``` | Syntax highlighted |
```python
print("hello")
``` | Python highlighting |
indented code | Indented code block |
Tables (GFM)
| Syntax | Result |
|---|
| Header | Header |
|--------|--------|
| Cell | Cell | | Basic table |
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R | | Aligned columns |
Horizontal Rules
| Syntax | Result |
|---|
--- | Horizontal rule (dashes) |
*** | Horizontal rule (asterisks) |
___ | Horizontal rule (underscores) |
Footnotes
| Syntax | Result |
|---|
Text[^1]
[^1]: Footnote content | Simple footnote |
[^longnote]: Multi-paragraph footnote | Named footnote |
Math (LaTeX)
| Syntax | Result |
|---|
$E = mc^2$ | Inline math |
$$
\frac{a}{b}
$$ | Block math |
$\sum_{i=1}^{n} x_i$ | Summation |
$\sqrt{x^2 + y^2}$ | Square root |
Mermaid Diagrams
| Syntax | Result |
|---|
```mermaid
flowchart TD
A --> B
``` | Flowchart |
```mermaid
sequenceDiagram
A->>B: Hi
``` | Sequence diagram |
```mermaid
pie
"A": 50
"B": 50
``` | Pie chart |
```mermaid
gantt
Task: a1, 2024-01-01, 7d
``` | Gantt chart |
```mermaid
mindmap
root((Mind))
A
B
``` | Mind map |
```mermaid
timeline
2024: Event A
2025: Event B
``` | Timeline |
```mermaid
classDiagram
Class01 <|-- Class02
``` | Class diagram |
```mermaid
erDiagram
User ||--o{ Order
``` | ER diagram |
```mermaid
stateDiagram-v2
[*] --> Active
``` | State diagram |
Definition Lists (Extended)
| Syntax | Result |
|---|
Term
: Definition of term | Simple definition |
Word
: First meaning
: Second meaning | Multiple definitions |
Abbreviations (Extended)
| Syntax | Result |
|---|
*[HTML]: Hyper Text Markup Language | Define abbreviation |
The HTML spec
*[HTML]: ... | Auto-tooltip on hover |
Frontmatter (YAML)
| Syntax | Result |
|---|
---
title: My Doc
author: Name
--- | Document metadata |
---
tags: [a, b, c]
date: 2024-01-01
--- | Arrays and dates |
Tips for Better Markdown
Use Blank Lines
Always add blank lines before and after headings, code blocks, and lists for consistent rendering across different parsers.
Escape Special Characters
Use backslash (\) to escape characters like *, _, #, etc. when you want them displayed literally: \*not italic\*
Consistent Style
Pick one style for similar elements (e.g., always use - for lists, not mixing - and *) for cleaner, more maintainable documents.
Use Reference Links
For documents with many links, use reference-style links at the bottom to keep your text readable: [text][ref] ... [ref]: url
Frequently Asked Questions
What's the difference between Markdown and HTML?
Markdown is designed to be readable as plain text and converts to HTML. It's much simpler than HTML but less powerful. Most markdown parsers also allow inline HTML for advanced formatting.
Why doesn't my markdown render correctly?
Common issues include: missing blank lines before/after elements, incorrect indentation for nested lists, or using syntax from a different markdown flavor. Markdown Studio's live preview helps catch these issues instantly.
Can I use markdown for academic writing?
Yes! With LaTeX math support and proper citation management, markdown is increasingly used for academic papers. Tools like Pandoc can convert markdown to PDF, DOCX, or LaTeX.
How do I create complex tables?
For complex tables, you may need to use HTML within your markdown. GFM tables support basic alignment but not merged cells or complex layouts.