Markdown API

VitePress provides APIs for working with markdown processing, including markdown-it integration and custom plugins.

createMarkdownRenderer()

Create a markdown-it renderer instance with VitePress defaults and plugins.

Function Signature

export async function createMarkdownRenderer(
  srcDir: string,
  options?: MarkdownOptions,
  base?: string,
  logger?: Pick<Logger, 'warn'>
): Promise<MarkdownRenderer>

type MarkdownRenderer = MarkdownItAsync

Parameters

srcDir

string

The source directory containing markdown files. Used for resolving relative paths and code snippets.

options

MarkdownOptions

Markdown processing options.

options.theme

ThemeOptions

Syntax highlighting theme. Can be a single theme or an object with light and dark themes.

// Single theme
theme: 'github-dark'

// Dual themes
theme: {
  light: 'github-light',
  dark: 'github-dark'
}

options.languages

(LanguageInput | BuiltinLanguage)[]

Additional languages for syntax highlighting.

languages: ['ruby', 'rust']

options.lineNumbers

boolean

default:"false"

Show line numbers in code blocks.

options.config

(md: MarkdownItAsync) => Awaitable<void>

Callback to configure the markdown-it instance.

options.anchor

AnchorOptions

Options for markdown-it-anchor plugin.

options.attrs

MarkdownItAttrsOptions

Options for markdown-it-attrs plugin.

options.frontmatter

FrontmatterPluginOptions

Options for frontmatter parsing.

options.headers

HeadersPluginOptions | boolean

Options for header extraction. Set to false to disable.

options.math

boolean | any

default:"false"

Enable math equations support. Requires markdown-it-mathjax3 to be installed.

options.gfmAlerts

boolean

default:"true"

Enable GitHub-flavored alerts (note, tip, warning, etc.).

base

string

default:"'/'"

Base URL for the site. Used for resolving relative links.

logger

Pick<Logger, 'warn'>

Logger instance for warnings. Defaults to console.

Return Value

MarkdownRenderer

A markdown-it instance configured with VitePress defaults and plugins.The instance is async-compatible and includes:

Syntax highlighting with Shiki
Frontmatter parsing
Header extraction
Custom containers
Code snippets
Image processing
And more

Examples

Basic Usage

import { createMarkdownRenderer } from 'vitepress'

const md = await createMarkdownRenderer('./docs')

const html = await md.renderAsync('# Hello World')
console.log(html)
// <h1 id="hello-world" tabindex="-1">Hello World <a class="header-anchor" href="#hello-world" aria-label="Permalink to &quot;Hello World&quot;">​</a></h1>

With Custom Theme

import { createMarkdownRenderer } from 'vitepress'

const md = await createMarkdownRenderer('./docs', {
  theme: 'material-theme-palenight',
  lineNumbers: true
})

const code = '```js\nconsole.log("Hello")\n```'
const html = await md.renderAsync(code)

With Custom Plugin

import { createMarkdownRenderer } from 'vitepress'
import customPlugin from 'markdown-it-custom'

const md = await createMarkdownRenderer('./docs', {
  config: (md) => {
    md.use(customPlugin, {
      // plugin options
    })
  }
})

Render with Frontmatter

import { createMarkdownRenderer } from 'vitepress'

const md = await createMarkdownRenderer('./docs')

const markdown = `---
title: My Page
---

# Content`

const env = {}
const html = await md.renderAsync(markdown, env)

console.log(env.frontmatter)
// { title: 'My Page' }

Markdown Options

Syntax Highlighting

theme

ThemeOptions

Shiki theme for syntax highlighting.Type:

type ThemeOptions =
  | ThemeRegistrationAny
  | BuiltinTheme
  | {
      light: ThemeRegistrationAny | BuiltinTheme
      dark: ThemeRegistrationAny | BuiltinTheme
    }

Examples:

// Built-in theme
theme: 'nord'

// Dual themes
theme: {
  light: 'github-light',
  dark: 'github-dark'
}

// Custom theme
theme: {
  name: 'my-theme',
  // ... theme definition
}

languages

(LanguageInput | BuiltinLanguage)[]

Additional languages to load for syntax highlighting.See Shiki languages for available languages.

languageAlias

Record<string, string>

Custom language aliases. Maps custom names to existing languages.

languageAlias: {
  'my_lang': 'python'
}

defaultHighlightLang

string

Fallback language when the specified language is not available.

codeTransformers

ShikiTransformer[]

Shiki transformers for code blocks.See Shiki transformers for details.

shikiSetup

(shiki: Highlighter) => void | Promise<void>

Callback to set up the Shiki highlighter instance.

Markdown-It Plugins

anchor

AnchorOptions

Options for markdown-it-anchor.Controls heading anchor generation.

attrs

MarkdownItAttrsOptions & { disable?: boolean }

Options for markdown-it-attrs.Allows adding attributes to markdown elements.

# Heading {#custom-id}

![Image](./image.png){width=500}

emoji

object

Options for emoji support.

emoji.defs

Record<string, string>

Custom emoji definitions

emoji.enabled

string[]

List of enabled emoji

emoji.shortcuts

Record<string, string | string[]>

Emoji shortcuts

container

ContainerOptions

Options for custom containers (::: tip, ::: warning, etc.).

math

boolean | any

default:"false"

Enable math equations support.Requires installing markdown-it-mathjax3:

npm install markdown-it-mathjax3

Usage:

Inline: $E = mc^2$

Block:
$$
\frac{1}{2}
$$

VitePress Features

gfmAlerts

boolean

default:"true"

Enable GitHub-flavored alerts.

> [!NOTE]
> Highlights information

> [!TIP]
> Helpful advice

> [!IMPORTANT]
> Key information

> [!WARNING]
> Urgent warning

> [!CAUTION]
> Negative potential consequences

image

ImageOptions

Options for image processing.

cjkFriendlyEmphasis

boolean

default:"true"

Enable CJK-friendly emphasis marks.Adds support for bold in Japanese, Chinese, and Korean text.

Advanced Configuration

preConfig

(md: MarkdownItAsync) => Awaitable<void>

Setup markdown-it instance before applying VitePress plugins.

preConfig: (md) => {
  // Configure before VitePress plugins
}

config

(md: MarkdownItAsync) => Awaitable<void>

Setup markdown-it instance after applying VitePress plugins.

config: (md) => {
  md.use(myPlugin)
}

cache

boolean

Disable markdown cache (experimental).

externalLinks

Record<string, string>

Default attributes for external links.

externalLinks: {
  target: '_blank',
  rel: 'noopener noreferrer'
}

Built-in Plugins

VitePress includes the following markdown-it plugins by default:

Core Plugins

@mdit-vue/plugin-component - Vue component support
@mdit-vue/plugin-frontmatter - Frontmatter parsing
@mdit-vue/plugin-headers - Header extraction
@mdit-vue/plugin-sfc - SFC block extraction
@mdit-vue/plugin-title - Title extraction
@mdit-vue/plugin-toc - Table of contents

Enhancement Plugins

markdown-it-anchor - Heading anchors
markdown-it-attrs - Attribute support
markdown-it-emoji - Emoji support

VitePress Plugins

preWrapper - Code block wrapper
snippet - Code snippet import
container - Custom containers
image - Image processing
link - Link processing
lineNumbers - Line numbers in code
gitHubAlerts - GitHub-flavored alerts

Examples

Custom Renderer with Math

import { createMarkdownRenderer } from 'vitepress'

const md = await createMarkdownRenderer('./docs', {
  math: true,
  theme: {
    light: 'github-light',
    dark: 'github-dark'
  }
})

const markdown = `
# Math Example

Inline: $E = mc^2$

Block:
$$
\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}
$$
`

const html = await md.renderAsync(markdown)

Adding Custom Plugin

import { createMarkdownRenderer } from 'vitepress'
import markdownItTaskLists from 'markdown-it-task-lists'

const md = await createMarkdownRenderer('./docs', {
  config: (md) => {
    md.use(markdownItTaskLists, {
      enabled: true
    })
  }
})

const markdown = `
- [x] Completed task
- [ ] Incomplete task
`

const html = await md.renderAsync(markdown)

Custom Code Transformers

import { createMarkdownRenderer } from 'vitepress'
import type { ShikiTransformer } from '@shikijs/types'

const highlightLinesTransformer: ShikiTransformer = {
  name: 'highlight-lines',
  line(node, line) {
    if (line === 3) {
      this.addClassToHast(node, 'highlighted')
    }
  }
}

const md = await createMarkdownRenderer('./docs', {
  codeTransformers: [highlightLinesTransformer]
})

Content Loader

createContentLoader()

Create a data loader for markdown content.

import { createContentLoader, type ContentData } from 'vitepress'

export default createContentLoader('posts/*.md', {
  includeSrc: true,
  render: true,
  excerpt: true,
  transform(data: ContentData[]) {
    return data.sort((a, b) => {
      return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
    })
  }
})

See the Data Loading guide for more details.

Markdown Extensions - Built-in markdown features
Configuration Reference - Markdown config options
Using Vue in Markdown - Vue component integration

Configuration

Node API

Client API

Markdown API

Markdown API

createMarkdownRenderer()

Function Signature

Parameters

Return Value

Examples

Basic Usage

With Custom Theme

With Custom Plugin

Render with Frontmatter

Markdown Options

Syntax Highlighting

Markdown-It Plugins

VitePress Features

Advanced Configuration

Built-in Plugins

Core Plugins

Enhancement Plugins

VitePress Plugins

Examples

Custom Renderer with Math

Adding Custom Plugin

Custom Code Transformers

Content Loader

createContentLoader()

Build docs developers (and LLMs) love

Configuration

Node API

Client API

​Markdown API

​createMarkdownRenderer()

​Function Signature

​Parameters

​Return Value

​Examples

​Basic Usage

​With Custom Theme

​With Custom Plugin

​Render with Frontmatter

​Markdown Options

​Syntax Highlighting

​Markdown-It Plugins

​VitePress Features

​Advanced Configuration

​Built-in Plugins

​Core Plugins

​Enhancement Plugins

​VitePress Plugins

​Examples

​Custom Renderer with Math

​Adding Custom Plugin

​Custom Code Transformers

​Content Loader

​createContentLoader()

​Related

Build docs developers (and LLMs) love

Markdown API

createMarkdownRenderer()

Function Signature

Parameters

Return Value

Examples

Basic Usage

With Custom Theme

With Custom Plugin

Render with Frontmatter

Markdown Options

Syntax Highlighting

Markdown-It Plugins

VitePress Features

Advanced Configuration

Built-in Plugins

Core Plugins

Enhancement Plugins

VitePress Plugins

Examples

Custom Renderer with Math

Adding Custom Plugin

Custom Code Transformers

Content Loader

createContentLoader()

Related