Custom Themes

Build a theme from scratch when the default theme doesn't fit your needs.

Theme Entry

Create .vitepress/theme/index.ts:

// .vitepress/theme/index.ts
import Layout from './Layout.vue';

export default {
  Layout,
  enhanceApp({ app, router, siteData }) {
    // Register global components, plugins, etc.
  },
};

Theme Interface

interface Theme {
  // Required: Root layout component
  Layout: Component;

  // Optional: Enhance Vue app instance
  enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>;

  // Optional: Extend another theme
  extends?: Theme;
}

interface EnhanceAppContext {
  app: App; // Vue app instance
  router: Router; // VitePress router
  siteData: Ref<SiteData>; // Site-level metadata
}

Basic Layout

The Layout component must render <Content /> for markdown:

<!-- .vitepress/theme/Layout.vue -->
<script setup>
import { useData } from 'vitepress';
const { page, frontmatter } = useData();
</script>

<template>
  <div class="layout">
    <header>
      <nav>My Site</nav>
    </header>

    <main>
      <div v-if="page.isNotFound">
        <h1>404 - Page Not Found</h1>
      </div>

      <div v-else-if="frontmatter.layout === 'home'">
        <h1>Welcome!</h1>
      </div>

      <article v-else>
        <Content />
      </article>
    </main>

    <footer>
      <p>© 2024 My Site</p>
    </footer>
  </div>
</template>

Runtime API

Access VitePress data in your theme:

<script setup>
import { useData, useRoute, useRouter } from 'vitepress';

// Page and site data
const {
  site, // Site config (title, description, etc.)
  theme, // Theme config
  page, // Current page data
  frontmatter, // Current page frontmatter
  title, // Page title
  description, // Page description
  lang, // Current language
  isDark, // Dark mode state
  params, // Dynamic route params
} = useData();

// Routing
const route = useRoute();
const router = useRouter();

// Navigate programmatically
const goToGuide = () => router.go('/guide/');
</script>

Built-in Components

<script setup>
import { Content } from 'vitepress';
</script>

<template>
  <!-- Renders markdown content -->
  <Content />

  <!-- Renders slot only on client (SSR-safe) -->
  <ClientOnly>
    <NonSSRComponent />
  </ClientOnly>
</template>

Extend Another Theme

Build on top of default theme or any other:

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme';

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // Your customizations
  },
};

Register Plugins and Components

// .vitepress/theme/index.ts
import Layout from './Layout.vue';
import GlobalComponent from './GlobalComponent.vue';

export default {
  Layout,
  enhanceApp({ app }) {
    // Register global component
    app.component('GlobalComponent', GlobalComponent);

    // Register plugin
    app.use(MyPlugin);

    // Provide/inject
    app.provide('key', value);
  },
};

Async enhanceApp

For plugins that need async initialization:

export default {
  Layout,
  async enhanceApp({ app }) {
    if (!import.meta.env.SSR) {
      // Client-only plugin
      const plugin = await import('browser-only-plugin');
      app.use(plugin.default);
    }
  },
};

Theme-Aware Layout

Handle different page layouts:

<script setup>
import { useData } from 'vitepress';
import Home from './Home.vue';
import Doc from './Doc.vue';
import Page from './Page.vue';
import NotFound from './NotFound.vue';

const { page, frontmatter } = useData();
</script>

<template>
  <NotFound v-if="page.isNotFound" />
  <Home v-else-if="frontmatter.layout === 'home'" />
  <Page v-else-if="frontmatter.layout === 'page'" />
  <Doc v-else />
</template>

Distributing a Theme

As npm package:

// my-theme/index.ts
import Layout from './Layout.vue';
export default { Layout };

// Export types for config
export type { ThemeConfig } from './types';

Consumer usage:

// .vitepress/theme/index.ts
import Theme from 'my-vitepress-theme';

export default Theme;

// Or extend it
export default {
  extends: Theme,
  enhanceApp({ app }) {
    // Additional customization
  },
};

Theme Config Types

For custom theme config types:

// .vitepress/config.ts
import { defineConfigWithTheme } from 'vitepress';
import type { ThemeConfig } from 'my-theme';

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // Type-checked theme config
  },
});

Key Points

• Theme must export Layout component
• <Content /> renders the markdown content
• Use useData() to access page/site data
• enhanceApp runs on both server and client
• Check import.meta.env.SSR for client-only code
• Use extends to build on existing themes

Contributors

XiSenao

Changelog

Last edited 10 days ago

View full history

2f55cfe-feat(ai-instructions): add skill definitions package