> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vuejs/vitepress/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown Extensions

> Learn about VitePress's powerful markdown extensions including syntax highlighting, custom containers, code groups, and Vue component integration.

# Markdown Extensions

VitePress extends standard Markdown with powerful features powered by [markdown-it](https://github.com/markdown-it/markdown-it). These extensions enable rich documentation with minimal effort.

## Syntax Highlighting

VitePress uses [Shiki](https://shiki.style/) for syntax highlighting with accurate, beautiful code blocks that support hundreds of languages.

<Steps>
  <Step title="Specify Language">
    Add the language identifier after the opening code fence:

    ````markdown theme={null}
    ```typescript
    interface User {
      id: number
      name: string
    }
    ```
    ````
  </Step>

  <Step title="Configure Theme">
    Customize syntax highlighting in your config:

    ```typescript theme={null}
    // .vitepress/config.ts
    export default {
      markdown: {
        theme: 'github-dark'
        // Or dual themes
        theme: { 
          light: 'github-light', 
          dark: 'github-dark' 
        }
      }
    }
    ```
  </Step>

  <Step title="Add Language Aliases">
    Create custom language aliases:

    ```typescript theme={null}
    export default {
      markdown: {
        languageAlias: {
          'my_lang': 'python'
        }
      }
    }
    ```
  </Step>
</Steps>

### Line Highlighting

Highlight specific lines to draw attention to important code:

<Tabs>
  <Tab title="Single Line">
    ````markdown theme={null}
    ```js{4}
    export default {
      data () {
        return {
          msg: 'Highlighted!'
        }
      }
    }
    ```
    ````
  </Tab>

  <Tab title="Multiple Lines">
    ````markdown theme={null}
    ```js{1,4,6-8}
    export default { // Highlighted
      data () {
        return {
          msg: 'Highlighted!',
          lorem: 'ipsum',
          motd: 'VitePress is awesome'
        }
      }
    }
    ```
    ````
  </Tab>

  <Tab title="Inline Comments">
    ````markdown theme={null}
    ```js
    export default {
      data () {
        return {
          msg: 'Highlighted!' // [!code highlight]
        }
      }
    }
    ```
    ````
  </Tab>
</Tabs>

### Code Annotations

VitePress supports special comments for focused lines, diffs, and error highlighting:

<CodeGroup>
  ```javascript Focus theme={null}
  export default {
    data () {
      return {
        msg: 'Focused!' // [!code focus]
      }
    }
  }
  ```

  ```javascript Diff theme={null}
  export default {
    data () {
      return {
        msg: 'Removed' // [!code --]
        msg: 'Added' // [!code ++]
      }
    }
  }
  ```

  ```javascript Errors theme={null}
  export default {
    data () {
      return {
        msg: 'Error', // [!code error]
        msg: 'Warning' // [!code warning]
      }
    }
  }
  ```
</CodeGroup>

<Note>
  These transformers are implemented via Shiki's transformer API. See `src/node/markdown/plugins/highlight.ts:80-96` for the implementation.
</Note>

### Line Numbers

Enable line numbers globally or per code block:

```typescript theme={null}
// .vitepress/config.ts
export default {
  markdown: {
    lineNumbers: true
  }
}
```

Override per block with `:line-numbers` or `:no-line-numbers`:

````markdown theme={null}
```ts:line-numbers=2 {1}
// line-numbers start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```
````

## Custom Containers

Custom containers provide callout-style blocks for tips, warnings, and more:

<Tabs>
  <Tab title="Types">
    ```markdown theme={null}
    ::: 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 collapsible details block.
    :::
    ```
  </Tab>

  <Tab title="Custom Titles">
    ````markdown theme={null}
    ::: danger STOP
    Danger zone, do not proceed
    :::

    ::: details Click me to view code
    ```js
    console.log('Hello, VitePress!')
    ````

    :::

    ````
    </Tab>

    <Tab title="Configuration">
    ```typescript
    // .vitepress/config.ts
    export default {
      markdown: {
        container: {
          tipLabel: 'TIP',
          warningLabel: 'WARNING',
          dangerLabel: 'DANGER',
          infoLabel: 'INFO',
          detailsLabel: 'Details'
        }
      }
    }
    ````
  </Tab>
</Tabs>

<Tip>
  Container implementation is in `src/node/markdown/plugins/containers.ts:8-27`. The plugin uses `markdown-it-container` to create custom blocks.
</Tip>

## GitHub-Flavored Alerts

VitePress supports GitHub-style alerts that render as callouts:

```markdown theme={null}
> [!NOTE]
> Highlights information that users should take into account.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate attention.

> [!CAUTION]
> Negative potential consequences of an action.
```

## Code Groups

Group related code blocks with tabs for better organization:

<Accordion title="Code Group Example">
  ````markdown theme={null}
  ::: code-group

  ```js [config.js]
  const config = {
    theme: 'default'
  }

  export default config
  ```

  ```ts [config.ts]
  import type { UserConfig } from 'vitepress'

  const config: UserConfig = {
    theme: 'default'
  }

  export default config
  ```

  :::
  ````
</Accordion>

## Import Code Snippets

Import code from external files using the `<<<` syntax:

<Steps>
  <Step title="Basic Import">
    ```markdown theme={null}
    <<< @/snippets/example.js
    ```

    The `@` symbol maps to your source directory.
  </Step>

  <Step title="With Line Highlighting">
    ```markdown theme={null}
    <<< @/snippets/example.js{2}
    ```
  </Step>

  <Step title="Region Import">
    Import only a specific region marked with comments:

    ```markdown theme={null}
    <<< @/snippets/example.js#snippet{1}
    ```

    In your source file:

    ```javascript theme={null}
    // #region snippet
    export function demo() {
      return 'Hello'
    }
    // #endregion snippet
    ```
  </Step>

  <Step title="Specify Language">
    ```markdown theme={null}
    <<< @/snippets/example.cs{c#}
    <<< @/snippets/example.cs{1,2,4-6 c#:line-numbers}
    ```
  </Step>
</Steps>

<Note>
  Snippet plugin implementation: `src/node/markdown/plugins/snippet.ts:122-216`
</Note>

## Markdown File Inclusion

Include markdown content from other files:

```markdown theme={null}
# Documentation

## Basics

<!--@include: ./parts/basics.md-->
```

You can also include specific line ranges or regions:

```markdown theme={null}
<!--@include: ./parts/basics.md{3,}-->
<!--@include: ./parts/basics.md#region-name-->
```

## Header Anchors

Headers automatically get anchor links for navigation:

### Custom Anchors

```markdown theme={null}
# Using custom anchors {#my-anchor}
```

This allows linking to `#my-anchor` instead of the auto-generated slug.

### Configuration

```typescript theme={null}
// .vitepress/config.ts
import markdownItAnchor from 'markdown-it-anchor'

export default {
  markdown: {
    anchor: {
      permalink: markdownItAnchor.permalink.headerLink()
    }
  }
}
```

## Links

### Internal Links

Internal links are converted to router links for SPA navigation:

```markdown theme={null}
[Home](/) <!-- root index.md -->
[Getting Started](/quickstart) <!-- can omit .md -->
[API Reference](../api/index.html) <!-- or use .html -->
```

### External Links

External links automatically get `target="_blank" rel="noreferrer"`:

```markdown theme={null}
[VitePress on GitHub](https://github.com/vuejs/vitepress)
```

## Tables

GitHub-flavored Markdown tables with alignment support:

```markdown theme={null}
| Feature       | Supported     | Status |
| ------------- | :-----------: | -----: |
| Syntax        | Highlighting  | Active |
| Custom        | Containers    | Active |
| Vue           | Components    | Active |
```

## Emoji

Emoji shortcuts are supported out of the box:

```markdown theme={null}
:tada: :rocket: :100:
```

See the [full emoji list](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs).

## Table of Contents

Generate a table of contents from headers:

```markdown theme={null}
[[toc]]
```

Configure TOC depth:

```typescript theme={null}
// .vitepress/config.ts
export default {
  markdown: {
    toc: { 
      level: [2, 3] 
    }
  }
}
```

## Math Equations

Enable LaTeX math support with `markdown-it-mathjax3`:

<Steps>
  <Step title="Install Package">
    ```bash theme={null}
    npm add -D markdown-it-mathjax3@^4
    ```
  </Step>

  <Step title="Enable in Config">
    ```typescript theme={null}
    // .vitepress/config.ts
    export default {
      markdown: {
        math: true
      }
    }
    ```
  </Step>

  <Step title="Use in Markdown">
    ```markdown theme={null}
    When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$:
    $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
    ```
  </Step>
</Steps>

## Image Lazy Loading

Enable lazy loading for images:

```typescript theme={null}
// .vitepress/config.ts
export default {
  markdown: {
    image: {
      lazyLoading: true
    }
  }
}
```

## Advanced Configuration

Customize the markdown-it instance with plugins:

```typescript theme={null}
// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import markdownItFoo from 'markdown-it-foo'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(markdownItFoo)
    }
  }
})
```

<Warning>
  The markdown renderer is created in `src/node/markdown/markdown.ts:243-400`. Custom plugins are applied after built-in VitePress plugins.
</Warning>

## Vue Components in Markdown

Use Vue components directly in markdown files:

```markdown theme={null}
<script setup>
import CustomComponent from './CustomComponent.vue'
</script>

# My Page

<CustomComponent :count="5" />
```

### The `raw` Container

Prevent style conflicts when documenting component libraries:

```markdown theme={null}
::: raw
Wraps content in a `<div class="vp-raw">`
:::
```

For style isolation, install PostCSS:

```bash theme={null}
npm add -D postcss
```

Create `docs/postcss.config.mjs`:

```javascript theme={null}
import { postcssIsolateStyles } from 'vitepress'

export default {
  plugins: [postcssIsolateStyles()]
}
```