Markdown Reference Guide

Basic Syntax

Headings

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

Text Formatting

Syntax Output Example
**bold text** bold text **Hello** → Hello
*italic text* italic text *Hello* → Hello
***bold and italic*** bold and italic ***Hello*** → Hello
~~strikethrough~~ ~~strikethrough~~ ~~Hello~~ → ~~Hello~~

Lists

Unordered Lists (Bullet Points)

- Item 1
- Item 2
- Item 3
  - Sub-item 3.1
  - Sub-item 3.2

Ordered Lists

1. First item
2. Second item
3. Third item
   1. Sub-item 3.1
   2. Sub-item 3.2

Code

Inline Code

Use `inline code` within text

Output: Use inline code within text

Code Blocks

```python
def hello():
    print("Hello, World!")
```

```shell
pip install package-name
```

```javascript
console.log("Hello");
```

[Link Text](https://google.com)
[Google](https://google.com)

Images

![Alt Text](path/to/image.jpg)
![Logo](images/logo.png)

[Link Text](https://google.com "Title on hover")

Blockquotes and Highlights

Blockquote (Highlighted Paragraph)

> This is a blockquote
> It can span multiple lines

Output:

This is a blockquote It can span multiple lines

Multi-line Blockquote with Line Break

> First line\
> Second line (use backslash for new line within blockquote)

Tables

Basic Table


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

Important: Add empty lines before and after tables for proper formatting in MkDocs.

Table Alignment


| Left Align | Center Align | Right Align |
|:-----------|:------------:|------------:|
| Left       | Center       | Right       |
| Text       | Text         | Text        |

Horizontal Line (Separator)

---

or

***

Output:

Anchor Navigation (Table of Contents)

How It Works

All headings automatically become anchor links. The link is created from the heading text: - Convert to lowercase - Replace spaces with hyphens - Remove special characters

Example

## Anchor Navigation
## Tips & Tricks

Links become: - #anchor-navigation - #tips--tricks

[Go to Anchor Navigation](#anchor-navigation)
[Jump to Tips & Tricks](#tips--tricks)

Full Table of Contents Example

## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
  - [Basic Usage](#basic-usage)
  - [Advanced Usage](#advanced-usage)
- [Conclusion](#conclusion)

Special Characters

Escaping Characters

Use backslash \ to display special characters literally:

\* Not a bullet point
\# Not a heading
\[Not a link](url)
\`Not code\`

Advanced Features

Task Lists

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

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

Footnotes

Here's a sentence with a footnote[^1].

[^1]: This is the footnote content.

Collapsible Sections

<details>
<summary>Click to expand</summary>

Hidden content goes here.

</details>

Quick Reference Table

Feature Syntax Notes
Headings # H1 to ###### H6 Use one space after #
Bold **text** Double asterisks
Italic *text* Single asterisk
Code Inline `code` Backticks
Code Block ```language Triple backticks
Link [text](url) Text in brackets, URL in parentheses
Image ![alt](path) Same as link with ! prefix
List - item or 1. item Dash for bullets, numbers for ordered
Blockquote > text Greater-than symbol
Horizontal Line --- Three dashes
Table \| col \| col \| Pipes separate columns
Anchor Link [text](#heading) Hash + lowercase heading with dashes

Tips & Tricks

For MkDocs

  1. Tables: Always add empty lines before and after tables
  2. Code blocks: Specify language for syntax highlighting
  3. Images: Use relative paths from the docs root

General Best Practices

  1. Spacing: Add blank lines between different elements
  2. Headings: Use hierarchical structure (H1 → H2 → H3)
  3. Links: Use descriptive link text, not "click here"
  4. Lists: Keep items concise and parallel in structure
  5. Code blocks: Always specify the language for highlighting

Common Mistakes

  • ❌ #Heading → ✅ # Heading (need space)
  • ❌ [link] (url) → ✅ [link](url) (no space)
  • ❌ Missing empty lines around tables
  • ❌ Mixing tabs and spaces in lists

Examples

Documentation Page Template

# Project Name

Brief description of the project.

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Examples](#examples)

## Installation

```bash
pip install package-name

Usage

Basic usage example:

import package
package.function()

Examples

Example 1: Basic Usage

Code and explanation here...

License

MIT License ```

Resources