Configuration and Theming

Almost everything about a VitePress site is controlled from one file: docs/.vitepress/config.mts. It is always resolved from the project root, the extensions .js, .ts, .mjs, and .mts are all supported, and TypeScript works out of the box. The file default-exports a single configuration object; the defineConfig helper is worth using because it gives you editor completion for the option names and their types.

// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // site-level options
  title: 'My Docs',
  description: 'Documentation for the thing I built.',
  lang: 'en-US',

  themeConfig: {
    // theme-level options
  }
})

The two halves of that object correspond to the two layers described in the previous chapter. Site-level options configure the generator: where the pages live, the base URL, dead-link behaviour, Markdown parsing. Theme-level options configure the presentation: navigation, sidebar, search, footer.

The site-level options you will actually use

OptionTypeWhat it does
titlestringSite title, used in the nav bar and as the default page title suffix
titleTemplatestring | booleanControls the suffix appended to each page title
descriptionstringDefault meta description for pages that do not set their own
langstringThe lang attribute on the html element
basestringThe public base path the site is served from; always start and end with a slash
srcDirstringDirectory holding the Markdown pages, relative to the project root
srcExcludestring[]Glob patterns for files that should not become pages
outDirstringBuild output directory, relative to the project root
cleanUrlsbooleanDrop the .html suffix from URLs; requires host support
ignoreDeadLinksboolean | arrayLet the build succeed when a link points at nothing
lastUpdatedbooleanRead each page’s last commit time from Git
appearanceboolean | stringControl the dark mode behaviour
headArrayExtra elements to inject into the head of every page
markdownobjectOptions for the markdown-it parser and the code highlighter
vite / vueobjectPass raw configuration to the underlying Vite and Vue plugins

Two deserve a note. The base option is the one you will set if your site is served from a sub-path rather than a domain root — a GitHub Pages project site, for example, is served from a repository path, and the base has to match it or every asset URL will 404. The ignoreDeadLinks option is a safety valve: the build fails on a broken internal link by default, so a link to a page generated at runtime will stop your deploy until you whitelist it.

export default defineConfig({
  base: '/my-repo/',
  lastUpdated: true,
  ignoreDeadLinks: [
    // ignore one specific path
    '/playground',
    // ignore links to a local development server
    /^https?:\/\/localhost/,
    // ignore anything containing a keyword
    (url) => url.toLowerCase().includes('ignore')
  ]
})

Theme configuration

Everything under themeConfig is passed to the theme. The default theme reads a long list of options from it, and the most important ones are the navigation and the sidebar:

export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      {
        text: 'More',
        items: [
          { text: 'GitHub', link: 'https://github.com/your-org/your-repo' }
        ]
      }
    ],

    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/introduction' },
            { text: 'Installation', link: '/guide/installation' }
          ]
        }
      ]
    },

    socialLinks: [{ icon: 'github', link: 'https://github.com/your-org/your-repo' }],

    editLink: {
      pattern: 'https://github.com/your-org/your-repo/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    },

    outline: { level: [2, 3] },

    footer: {
      message: 'Licensed under MIT.',
      copyright: 'Copyright © 2026'
    }
  }
})

The sidebar option accepts either a single array, shown on every page, or an object keyed by path prefix, as above. With the keyed form the sidebar depends on the path of the page being viewed, so a documentation area and an API reference can have entirely different navigation. Within a group, collapsed controls whether a section starts folded, and base sets the prefix that child links resolve against.

The outline option controls the “on this page” panel: a number selects one heading level, a tuple selects a range, and false removes the panel. The editLink pattern is a template in which :path is replaced with the file path relative to the source directory, linking a page back to the file that produced it.

Build hooks

Some things cannot be expressed as static configuration because they depend on the page being built or on data fetched at build time. VitePress exposes hooks for that, all at the top level of the configuration:

export default defineConfig({
  async transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      { name: 'og:title', content: `${pageData.title} | My Docs` }
    ])
  },

  async transformHead(context) {
    return [['meta', { name: 'generator', content: 'VitePress' }]]
  },

  async buildEnd(siteConfig) {
    // runs after the static build finishes
  }
})

transformPageData runs for every page and can mutate or extend the page data, which is where per-page metadata such as social card tags belongs. transformHead returns extra head entries and runs during the static build only. transformHtml receives the final HTML of each page and can rewrite it, though modifying it carelessly causes hydration mismatches in the browser. buildEnd runs once after the whole build.

Customizing the theme

The default theme is styled entirely with CSS custom properties, so the cheapest way to change it is to override the variables:

/* docs/.vitepress/theme/custom.css */
:root {
  --vp-c-brand-1: #646cff;
  --vp-c-brand-2: #747bff;
  --vp-c-brand-3: #535bf2;

  --vp-font-family-base: 'Inter', system-ui, sans-serif;
  --vp-font-family-mono: 'JetBrains Mono', monospace;
}

When you need more than variables — a custom component, extra content in a specific position, a modified layout — you extend the theme from the theme directory. The entry point is docs/.vitepress/theme/index.ts, and its enhanceApp hook registers global components with the Vue application:

// docs/.vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import MyGlobalComponent from './MyGlobalComponent.vue'
import './custom.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('MyGlobalComponent', MyGlobalComponent)
  }
} satisfies Theme

To place content at a specific position, wrap the default layout in your own component and fill one of its slots:

<!-- docs/.vitepress/theme/Layout.vue -->
<script setup>
import DefaultTheme from 'vitepress/theme'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #doc-before>
      <MyBanner />
    </template>
  </Layout>
</template>

The default theme exposes many slots — doc-top, doc-bottom, doc-before, doc-after, doc-footer-before, sidebar-nav-before, sidebar-nav-after, the aside-* and layout-* families, and the home-layout equivalents. Using them is almost always preferable to overriding an internal component, whose name is an implementation detail that can change between minor releases.

The idea to take away is that the configuration file is the primary interface, and that it is split by responsibility rather than by feature area. When an option is not in the list above, the first question is which layer it belongs to; the second is whether the theme exposes it as a slot or a CSS variable. The next page covers the authoring side of the same system, and the one after that publishes the finished site.

Found an issue with this content?

Tell us what could be improved.