Markdown Extensions

VitePress extends standard Markdown with powerful features for technical documentation.

Basic Markdown

Headers

# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header

Text Formatting

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`

Lists

<!-- Unordered list -->
- Item 1
- Item 2
  - Nested item
  - Another nested item

<!-- Ordered list -->
1. First item
2. Second item
   1. Nested numbered item
   2. Another nested numbered item

<!-- Task list -->
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Link title")
[Internal link](./other-page.md)
[Link to heading](#specific-heading)

![Image alt text](./images/example.png)
![Image with title](./images/example.png "Image title")

Code Blocks

Basic Code Blocks

```javascript
function hello() {
  console.log('Hello, VitePress!')
}
```

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

```bash
npm install vitepress
```

Line Highlighting

```javascript {2,4-6}
function example() {
  const highlighted = true  // This line is highlighted
  const normal = true
  const alsoHighlighted = true  // Lines 4-6 are highlighted
  const stillHighlighted = true
  const lastHighlighted = true
  const normal2 = true
}
```

Line Numbers

```typescript:line-numbers
interface User {
  id: number
  name: string
  email: string
}

function createUser(data: Partial<User>): User {
  return {
    id: Math.random(),
    name: data.name || 'Anonymous',
    email: data.email || 'no-email@example.com'
  }
}
```

Focus Lines

```javascript
function example() {
  const important = 'This line is focused'
  const normal = 'This is normal'
  const alsoImportant = 'This is also focused'
}
```

Diff Highlighting

```javascript
function example() {
  const old = 'old value'
  const new = 'new value'
  
  console.log('Removed code')
  console.log('Added code')
}
```

Error and Warning Highlighting

```javascript
function example() {
  const error = 'This will cause an error'
  const warning = 'This is suspicious'
}
```

Custom Containers

Info Containers

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

Custom Titles

::: danger STOP
Danger zone, do not proceed
:::

::: details Click me to view the code
```javascript
console.log('Hello, world!')

:::

### Raw HTML in Containers
```markdown
::: tip Custom HTML
You can use <strong>HTML</strong> inside containers.

<div class="custom-block">
  <p>Custom content with styling</p>
</div>
:::

Tables

Basic Tables

| Feature | Supported | Notes |
| ------- | --------- | ----- |
| Tables | ✅ | Full support |
| Alignment | ✅ | Left, center, right |
| HTML | ✅ | Limited support |

Table Alignment

| Left | Center | Right |
| :--- | :----: | ----: |
| Text | Text | Text |
| More | More | More |

Complex Tables

| Feature | Description | Example |
| ------- | ----------- | ------- |
| **Bold** | Bold text | `**text**` |
| *Italic* | Italic text | `*text*` |
| `Code` | Inline code | `` `code` `` |
| [Link](/) | Link | `[text](url)` |

Math Expressions

Inline Math

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Block Math

$$
\begin{aligned}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &= \frac{4\pi}{c}\vec{\mathbf{j}} \\
\nabla \cdot \vec{\mathbf{E}} &= 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} &= \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} &= 0
\end{aligned}
$$

Emoji Support

Shortcodes

:tada: :100: :rocket: :heart: :fire:

Unicode Emoji

🎉 💯 🚀 ❤️ 🔥

Advanced Features

Line Breaks

This is line one\
This is line two (with line break)

This is a new paragraph

Footnotes

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

Here's another footnote[^note].

[^1]: This is the first footnote.
[^note]: This is a named footnote.

Definition Lists

Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

Abbreviations

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

The HTML specification is maintained by the W3C.

Vue Components in Markdown

Using Vue Components

<script setup>
import CustomComponent from './components/CustomComponent.vue'
</script>

# My Page

<CustomComponent :count="5" />

Regular markdown content continues here.

Inline Vue Expressions

{{ 1 + 1 }}

{{ new Date().getFullYear() }}

Vue Directives

<div v-if="true">
  This will be rendered
</div>

<ul>
  <li v-for="item in ['a', 'b', 'c']" :key="item">
    {{ item }}
  </li>
</ul>

Import Code Snippets

Import Entire Files

<<< @/examples/basic.js

<<< @/examples/config.ts{typescript}

Import Specific Lines

<<< @/examples/example.js{1,3-5}

<<< @/examples/example.js{javascript:line-numbers}

Import with Custom Language

<<< @/examples/data.json{json}

<<< @/examples/style.css{css}

Frontmatter

YAML Frontmatter

---
title: Page Title
description: Page description
layout: doc
sidebar: true
---

# Page Content

JSON Frontmatter

---
{
  "title": "Page Title",
  "description": "Page description"
}
---

# Page Content

Custom Markdown Plugins

Adding Plugins

// .vitepress/config.js
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    config: (md) => {
      // Add custom markdown-it plugins
      md.use(require('markdown-it-footnote'))
      md.use(require('markdown-it-deflist'))
      md.use(require('markdown-it-abbr'))
    }
  }
})

Custom Renderer Rules

// .vitepress/config.js
export default defineConfig({
  markdown: {
    config: (md) => {
      // Customize link rendering
      md.renderer.rules.link_open = (tokens, idx, options, env, renderer) => {
        const token = tokens[idx]
        const href = token.attrGet('href')
        
        if (href && href.startsWith('http')) {
          token.attrSet('target', '_blank')
          token.attrSet('rel', 'noopener noreferrer')
        }
        
        return renderer.renderToken(tokens, idx, options)
      }
    }
  }
})

Best Practices

Content Organization

• Use consistent heading hierarchy
• Keep paragraphs concise
• Use lists for better readability
• Add meaningful alt text for images

Code Documentation

• Include language identifiers for syntax highlighting
• Use line highlighting for important code
• Add comments to explain complex code
• Keep code examples focused and relevant

Accessibility

• Use descriptive link text
• Provide alt text for images
• Use proper heading hierarchy
• Ensure sufficient color contrast

Performance

• Optimize images before including them
• Use appropriate image formats
• Keep markdown files reasonably sized
• Minimize external dependencies