Markdown API

Markdown processing and markdown-it integration APIs

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

md · 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.

Related

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