Complete Markdown Formatting Guide: Syntax and When to Use It

Markdown is a lightweight markup language that uses simple text characters to format documents. This guide covers every Markdown syntax element and explains when to use each one for effective communication, especially with AI systems.

Headings

Headings create a hierarchy in your document. Use them to organize content into clear sections.

Syntax

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

When to Use

• H1: Main document title or primary section
• H2: Major sections within your document
• H3-H6: Subsections, nested topics, or supporting details

Best Practices

• Use only one H1 per document
• Maintain a logical hierarchy (don't skip from H2 to H4)
• Use headings to break up long text blocks

Bold and Italic

Emphasize important words or phrases to draw attention.

Syntax

**bold text** or __bold text__
*italic text* or _italic text_
***bold and italic*** or ___bold and italic___

When to Use

• Bold: Key terms, important instructions, critical information
• Italic: Emphasis, foreign words, book titles, or subtle emphasis
• Bold + Italic: Maximum emphasis for critical points

Example for AI Prompts

**Important**: Always validate user input before processing.
Use *italics* for optional parameters.

Strikethrough

Show text that has been removed or is no longer valid.

Syntax

~~strikethrough text~~

When to Use

• Showing revisions or corrections
• Indicating deprecated information
• Creating "before and after" comparisons

Inline Code

Highlight code, commands, or technical terms inline with your text.

Syntax

Use `console.log()` to debug your code.

When to Use

• Function names, variables, or commands
• File paths or configuration values
• Technical terms that need to stand out

Code Blocks

Display multi-line code snippets with syntax highlighting.

Syntax

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

When to Use

• Showing complete code examples
• Demonstrating API usage
• Providing configuration templates
• Sharing data structures (JSON, XML, etc.)

Supported Languages

Common languages include: javascript, python, html, css, json, bash, sql, and many more.

Links

Create clickable hyperlinks to external resources or internal references.

Syntax

[Link text](https://example.com)
[Link with title](https://example.com "Optional title")

When to Use

• Referencing external documentation
• Linking to related resources
• Providing additional context
• Citing sources

Images

Embed images in your document with alt text for accessibility.

Syntax

![Alt text](image-url.png)
![Alt text](image-url.png "Optional title")

When to Use

• Diagrams or flowcharts
• Screenshots for tutorials
• Visual examples or illustrations
• Charts and graphs

Lists

Organize information into structured, scannable formats.

Bullet Lists (Unordered)

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

When to Use: Non-sequential items, features, benefits, or any unordered collection.

Numbered Lists (Ordered)

1. First step
2. Second step
3. Third step
   1. Sub-step
   2. Another sub-step

When to Use: Sequential steps, instructions, rankings, or any ordered sequence.

Task Lists (Checkboxes)

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

When to Use: To-do lists, checklists, progress tracking, or action items.

Blockquotes

Highlight quoted text, callouts, or important notes.

Syntax

> This is a blockquote.
> It can span multiple lines.
>
> You can also have paragraphs within blockquotes.

When to Use

• Quoting external sources
• Creating callout boxes or warnings
• Emphasizing important information
• Providing context or background

Example for AI Prompts

> User context: The user is a marketing manager
> with 5 years of experience who needs to present
> to the C-suite next week.

Horizontal Rules

Create visual separators between sections.

Syntax

---

When to Use

• Separating major sections
• Creating visual breaks in long documents
• Dividing different topics or themes

Tables

Organize data into rows and columns.

Syntax

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

When to Use

• Comparing data across multiple dimensions
• Displaying structured information
• Creating feature comparison charts
• Organizing specifications or parameters

Alignment

| Left | Center | Right |
|:-----|:------:|------:|
| Left | Center | Right |

What Markdown Doesn't Support

Underline

Standard Markdown does not support underline formatting. This is intentional—underlines are reserved for links in Markdown. If you need underline, you would need to use HTML: underlined text, but this is not recommended as it breaks the portability of Markdown.

Text Color

Markdown doesn't support colored text. Use bold, italic, or code formatting for emphasis instead.

Font Size

Markdown doesn't support changing font sizes. Use headings for different sizes.

Best Practices for AI Communication

When using Markdown to communicate with AI:

1. Use headings to structure your prompt into clear sections
2. Use lists for multiple requirements or steps
3. Use bold for critical instructions or constraints
4. Use code blocks to show exact formats or examples
5. Use blockquotes for context or background information
6. Use tables for structured data or comparisons

Quick Reference

| Element | Syntax | Use Case | |---------|--------|----------| | Heading 1 | # Title | Main title | | Heading 2 | ## Section | Major sections | | Bold | text | Important terms | | Italic | *text* | Emphasis | | Code | `code` | Technical terms | | Link | text | References | | Image | !alt | Visuals | | List | - item | Unordered items | | Numbered | 1. item | Sequential steps | | Task | - [ ] task | Checklists | | Quote | > text | Callouts | | Table | | col | | Structured data | | Code Block | `lang` | Code examples |

Get Started

Use our visual Markdown editor to create formatted documents without memorizing syntax. The editor shows you the Markdown output in real-time, so you can learn as you write.