> ## 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. # Site Configuration > Complete guide to VitePress site configuration # Site Configuration Site configuration is where you define global settings for your VitePress site. The config file is located at `.vitepress/config.js` (or `.ts`, `.mjs`, `.mts`) and controls everything from metadata to build options. ## Basic Setup ### Config File Location VitePress looks for your configuration file at: ``` /.vitepress/config.[ext] ``` Supported extensions: `.js`, `.ts`, `.mjs`, `.mts` ### Using defineConfig The `defineConfig` helper provides TypeScript-powered intellisense: ```ts .vitepress/config.ts theme={null} import { defineConfig } from 'vitepress' export default defineConfig({ title: 'My Documentation', description: 'A VitePress site', base: '/' }) ``` ```js .vitepress/config.js theme={null} import { defineConfig } from 'vitepress' export default defineConfig({ title: 'My Documentation', description: 'A VitePress site', base: '/' }) ``` TypeScript is supported out of the box - no additional configuration needed. ### Dynamic Configuration You can export an async function for dynamic configuration: ```ts theme={null} import { defineConfig } from 'vitepress' export default async () => { const data = await fetchSomeData() return defineConfig({ title: data.title, description: data.description }) } ``` Or use top-level `await`: ```ts theme={null} import { defineConfig } from 'vitepress' const data = await fetchSomeData() export default defineConfig({ title: data.title, description: data.description }) ``` ## Site Metadata ### title The title for your site. Displayed in the nav bar and used as the suffix for page titles. ```ts theme={null} export default defineConfig({ title: 'My Awesome Docs' }) ``` With this configuration and a page containing `# Hello`, the page title becomes: ``` Hello | My Awesome Docs ``` ### titleTemplate Customize the page title suffix or format. Use `:title` as a placeholder for the page title. ```ts theme={null} export default defineConfig({ title: 'My Docs', titleTemplate: ':title - Custom Suffix' }) ``` Set to `false` to disable title suffixes: ```ts theme={null} export default defineConfig({ titleTemplate: false }) ``` ### description Site description. Renders as a `` tag in the page HTML. ```ts theme={null} export default defineConfig({ description: 'Comprehensive documentation for my project' }) ``` ### lang The language attribute for the site. Renders as ``. ```ts theme={null} export default defineConfig({ lang: 'en-US' }) ``` ### head Additional elements to render in the `` tag. ```ts theme={null} type HeadConfig = | [string, Record] | [string, Record, string] ``` #### Add a Favicon ```ts theme={null} export default defineConfig({ head: [ ['link', { rel: 'icon', href: '/favicon.ico' }] ] }) ``` #### Add Google Fonts ```ts theme={null} export default defineConfig({ head: [ ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }], ['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }], ['link', { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' }] ] }) ``` #### Add Analytics ```ts theme={null} export default defineConfig({ head: [ ['script', { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' }], ['script', {}, ` window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'TAG_ID'); `] ] }) ``` ## Directory Structure ### base The base URL for deployment. Required when deploying to a subdirectory. ```ts theme={null} export default defineConfig({ base: '/my-project/' }) ``` The base must start and end with a slash. It's automatically prepended to all URLs that start with `/`. ### srcDir The directory where your markdown pages are stored, relative to project root. ```ts theme={null} export default defineConfig({ srcDir: './src' }) ``` ### outDir The build output location, relative to project root. ```ts theme={null} export default defineConfig({ outDir: '../public' }) ``` ### assetsDir Directory to nest generated assets under. Must be inside `outDir`. ```ts theme={null} export default defineConfig({ assetsDir: 'static' }) ``` ### cacheDir Directory for cache files, relative to project root. ```ts theme={null} export default defineConfig({ cacheDir: './.vitepress/.vite' }) ``` ### srcExclude Glob patterns for markdown files to exclude from source content. ```ts theme={null} export default defineConfig({ srcExclude: ['**/README.md', '**/TODO.md'] }) ``` ## Routing ### cleanUrls Remove trailing `.html` from URLs. ```ts theme={null} export default defineConfig({ cleanUrls: true }) ``` Your server must be able to serve `/foo.html` when visiting `/foo` without a redirect. ### rewrites Define custom directory to URL mappings. ```ts theme={null} export default defineConfig({ rewrites: { 'source/:page': 'destination/:page', 'packages/:pkg/README.md': ':pkg/index.md' } }) ``` ## Theming ### appearance Control dark mode behavior. ```ts theme={null} export default defineConfig({ appearance: true // User can toggle, follows system preference }) ``` ```ts theme={null} export default defineConfig({ appearance: 'dark' // Dark by default, user can toggle }) ``` ```ts theme={null} export default defineConfig({ appearance: 'force-dark' // Always dark, no toggle }) ``` ```ts theme={null} export default defineConfig({ appearance: 'force-auto' // Follows system, no toggle }) ``` ```ts theme={null} export default defineConfig({ appearance: { initialValue: 'dark', // Additional VueUse UseDark options } }) ``` ### scrollOffset Configure scroll offset for sticky headers. ```ts theme={null} export default defineConfig({ scrollOffset: 100 // pixels }) // Or use a selector export default defineConfig({ scrollOffset: '.navbar' }) // Or multiple selectors with fallback export default defineConfig({ scrollOffset: ['.navbar', '.header'] }) // Or with custom padding export default defineConfig({ scrollOffset: { selector: '.navbar', padding: 20 } }) ``` ## Build Options ### ignoreDeadLinks Control how dead links are handled during build. ```ts theme={null} export default defineConfig({ ignoreDeadLinks: true }) ``` ```ts theme={null} export default defineConfig({ ignoreDeadLinks: 'localhostLinks' }) ``` ```ts theme={null} export default defineConfig({ ignoreDeadLinks: [ '/playground', /^https?:\/\/localhost/, /\/repl\//, (url) => url.toLowerCase().includes('ignore') ] }) ``` ### lastUpdated Get last updated timestamp for each page using Git. ```ts theme={null} export default defineConfig({ lastUpdated: true }) ``` ### mpa (Experimental) Build in MPA mode (Multi-Page Application). Ships 0kb JavaScript but disables client-side navigation. ```ts theme={null} export default defineConfig({ mpa: true }) ``` ### metaChunk (Experimental) Extract page metadata to separate JavaScript chunks for better caching. ```ts theme={null} export default defineConfig({ metaChunk: true }) ``` ### buildConcurrency (Experimental) Configure build concurrency. Lower values reduce memory usage but increase build time. ```ts theme={null} export default defineConfig({ buildConcurrency: 32 }) ``` ## Integrations ### vite Pass configuration to the internal Vite dev server/bundler. ```ts theme={null} export default defineConfig({ vite: { plugins: [myVitePlugin()], server: { port: 3000 }, build: { chunkSizeWarningLimit: 1000 } } }) ``` ### vue Pass options to `@vitejs/plugin-vue`. ```ts theme={null} export default defineConfig({ vue: { template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('custom-') } } } }) ``` ### markdown Configure Markdown-it parser and Shiki syntax highlighting. ```ts theme={null} export default defineConfig({ markdown: { lineNumbers: true, theme: 'github-dark', config: (md) => { md.use(myMarkdownPlugin) } } }) ``` ## Build Hooks ### buildEnd Hook called after build finishes but before CLI process exits. ```ts theme={null} export default defineConfig({ async buildEnd(siteConfig) { // Generate sitemap, search index, etc. console.log('Build completed!') } }) ``` ### postRender Hook called when SSG rendering is done. Handle teleports content. ```ts theme={null} export default defineConfig({ async postRender(context) { // Process teleported content return context } }) ``` ### transformHead Transform head before generating each page. Return extra head entries to merge. ```ts theme={null} export default defineConfig({ async transformHead(context) { return [ ['meta', { property: 'og:title', content: context.title }], ['meta', { property: 'og:description', content: context.description }] ] } }) ``` ### transformHtml Transform HTML content before saving to disk. ```ts theme={null} export default defineConfig({ async transformHtml(code, id, context) { // Modify HTML content return code.replace(/foo/g, 'bar') } }) ``` ### transformPageData Transform page data for each page. Can directly mutate or return values to merge. ```ts theme={null} export default defineConfig({ async transformPageData(pageData) { pageData.contributors = await getContributors(pageData.relativePath) // Or return data to merge return { readingTime: calculateReadingTime(pageData.content) } } }) ``` ## Advanced Features ### Config Extension Extend another configuration file. ```ts theme={null} import baseConfig from './base.config' export default defineConfig({ extends: baseConfig, title: 'Extended Config' }) ``` ### Sitemap Generation (Experimental) Configure automatic sitemap generation. ```ts theme={null} export default defineConfig({ sitemap: { hostname: 'https://example.com', transformItems: (items) => { // Filter or modify sitemap items return items.filter(item => !item.url.includes('secret')) } } }) ``` ### Content Props Props to pass to the content component. ```ts theme={null} export default defineConfig({ contentProps: { customProp: 'value' } }) ``` ### Router Configuration Configure router behavior. ```ts theme={null} export default defineConfig({ router: { prefetchLinks: false // Disable link prefetching } }) ``` ## TypeScript Configuration ### Custom Theme Config Type For custom themes, use `defineConfig` with a generic type: ```ts theme={null} import { defineConfig } from 'vitepress' import type { ThemeConfig } from 'your-theme' export default defineConfig({ themeConfig: { // Typed according to ThemeConfig } }) ``` ### Environment-Specific Config Access command and mode via function config: ```ts theme={null} import { defineConfig } from 'vitepress' export default defineConfig(async ({ command, mode }) => { if (command === 'serve') { return { // Dev-specific config } } else { return { // Build-specific config } } }) ``` ## Next Steps Configure the default theme's appearance and behavior Create a completely custom theme Customize the default theme with slots and overrides