Frequently Asked Questions

Find answers to common questions about VitePress and this documentation site.

General Questions

What is VitePress?

VitePress is a static site generator built on top of Vite and Vue.js. It's designed specifically for creating fast, content-focused websites like documentation sites, blogs, and marketing pages.

Key Features:

• ⚡ Fast development and build times
• 📝 Markdown-centered content
• 🎨 Vue.js powered theming
• 🔍 Built-in search
• 📱 Mobile-friendly responsive design

How is VitePress different from VuePress?

VitePress is the spiritual successor to VuePress, built from the ground up with modern tooling:

Feature	VitePress	VuePress
Build Tool	Vite	Webpack
Vue Version	Vue 3	Vue 2/3
Performance	Faster	Slower
Bundle Size	Smaller	Larger
Plugin System	Simpler	More Complex

Is VitePress production ready?

Yes! VitePress is stable and used by many production websites including:

• Vue.js official documentation
• Vite documentation
• Pinia documentation
• Many open-source projects

Installation & Setup

What are the system requirements?

• Node.js: Version 18 or higher
• Package Manager: npm, yarn, or pnpm
• Operating System: Windows, macOS, or Linux

How do I install VitePress?

# Using npm
npm install -D vitepress

# Using yarn
yarn add -D vitepress

# Using pnpm
pnpm add -D vitepress

Can I use VitePress with existing projects?

Yes! VitePress can be added to any project. Just install it as a dev dependency and create a docs folder for your documentation.

How do I migrate from VuePress?

1. Install VitePress: npm install -D vitepress
2. Update config: Convert .vuepress/config.js to .vitepress/config.js
3. Update theme: Adapt custom theme components
4. Test thoroughly: Check all pages and functionality

Configuration

How do I customize the theme?

You can customize VitePress in several ways:

1. CSS Variables: Override default styles

:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
}

2. Custom Theme: Create a custom theme

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

3. Layout Slots: Add custom content to layout slots

How do I add a custom domain?

1. Configure base URL:

// .vitepress/config.js
export default {
  base: '/', // For custom domain, use '/'
}

2. Add CNAME file (for GitHub Pages):

yourdomain.com

3. Configure DNS: Point your domain to hosting provider

How do I set up multi-language support?

// .vitepress/config.js
export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    zh: {
      label: '简体中文',
      lang: 'zh-CN',
      link: '/zh/'
    }
  }
}

Content & Markdown

What Markdown features are supported?

VitePress supports standard Markdown plus:

• Tables: GitHub-flavored tables
• Code blocks: Syntax highlighting
• Custom containers: Tips, warnings, etc.
• Math: LaTeX math expressions
• Emoji: 🎉 emoji support
• Vue components: Use Vue in Markdown

How do I add code syntax highlighting?

VitePress uses Shiki for syntax highlighting:

// Specify language for highlighting
const config = {
  title: 'My Site'
}

Supported languages include JavaScript, TypeScript, Vue, Python, and many more.

Can I use Vue components in Markdown?

Yes! You can use Vue components directly in Markdown:

# My Page

<MyCustomComponent :prop="value" />

Regular markdown content continues here.

How do I add images?

1. Static images: Place in public folder

![Alt text](/image.jpg)

2. Relative images: Place near markdown files

![Alt text](./images/local-image.jpg)

Deployment

Where can I deploy VitePress sites?

VitePress sites can be deployed to any static hosting service:

• GitHub Pages: Free hosting for public repos
• Netlify: Automatic deployments from Git
• Vercel: Fast global CDN
• Cloudflare Pages: Edge computing platform
• AWS S3: Scalable cloud storage
• Custom servers: Any web server

How do I deploy to GitHub Pages?

1. Create workflow file: .github/workflows/deploy.yml
2. Configure build: Set build command and output directory
3. Enable Pages: In repository settings
4. Push changes: Automatic deployment on push

Why is my site not loading after deployment?

Common issues:

• Base URL: Check base configuration in config file
• Asset paths: Ensure assets are correctly referenced
• 404 errors: Configure server for client-side routing
• HTTPS: Some features require HTTPS

Performance

How can I improve build performance?

1. Optimize images: Compress and use appropriate formats
2. Code splitting: Use dynamic imports
3. Bundle analysis: Analyze bundle size
4. Caching: Configure proper caching headers

Why is my site slow?

Common causes:

• Large images: Optimize image sizes
• Heavy JavaScript: Minimize client-side code
• External resources: Minimize external dependencies
• Poor hosting: Choose faster hosting provider

How do I optimize for SEO?

1. Meta tags: Add proper title and description
2. Structured data: Use JSON-LD for rich snippets
3. Sitemap: Enable automatic sitemap generation
4. Performance: Optimize loading speed
5. Mobile-friendly: Ensure responsive design

Troubleshooting

Build fails with "Cannot resolve module"

This usually means:

1. Missing dependency: Install required packages
2. Wrong import path: Check file paths
3. Node.js version: Ensure Node.js 18+

Development server won't start

Check:

1. Port availability: Default port 5173 might be in use
2. Node.js version: Ensure compatible version
3. Dependencies: Run npm install
4. Configuration: Check config file syntax

Links are broken after deployment

Common causes:

1. Base URL: Configure correct base path
2. Case sensitivity: File names must match exactly
3. File extensions: Include .html if needed
4. Relative paths: Use absolute paths for reliability

Custom components not working

Ensure:

1. Registration: Components are properly registered
2. Import paths: Correct import statements
3. Vue version: Compatible with Vue 3
4. Build process: Components are included in build

Advanced Usage

Can I use VitePress for a blog?

Yes! VitePress works great for blogs:

• Use frontmatter for post metadata
• Create dynamic post lists
• Add RSS feed generation
• Implement tagging and categories

How do I add search functionality?

VitePress includes built-in search:

// .vitepress/config.js
export default {
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
}

For advanced search, integrate with Algolia.

Can I use a CMS with VitePress?

Yes! VitePress can work with headless CMS:

• Markdown-based: Forestry, Tina CMS
• API-based: Strapi, Contentful
• Git-based: Netlify CMS, Decap CMS

How do I add analytics?

Add analytics scripts to your config:

// .vitepress/config.js
export default {
  head: [
    ['script', { 
      async: true, 
      src: 'https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID' 
    }],
    ['script', {}, `
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'GA_MEASUREMENT_ID');
    `]
  ]
}

Community & Support

Where can I get help?

• Documentation: Official VitePress docs
• GitHub Issues: Bug reports and feature requests
• Discord: Vue.js community Discord
• Stack Overflow: Tag questions with vitepress

How can I contribute?

See our Contributing Guide for:

• Code contributions
• Documentation improvements
• Translation help
• Bug reports

Is there a community forum?

Join the Vue.js community:

• Discord: Vue Land Discord
• GitHub Discussions: Project-specific discussions
• Reddit: r/vuejs community

Migration & Compatibility

Can I migrate from GitBook?

Yes! Export your GitBook content and:

1. Convert to Markdown format
2. Restructure file organization
3. Update internal links
4. Configure navigation

What about Jekyll migration?

Jekyll sites can be migrated:

1. Keep Markdown files
2. Convert _config.yml to VitePress config
3. Update frontmatter format
4. Rebuild navigation structure

Is VitePress compatible with Vue 2?

No, VitePress requires Vue 3. If you need Vue 2 support, consider VuePress instead.

Still Have Questions?

If you can't find the answer you're looking for:

1. Search the docs: Use the search function
2. Check GitHub issues: Someone might have asked already
3. Ask the community: Join Discord or forums
4. Create an issue: For bugs or feature requests

---

This FAQ is regularly updated. If you have suggestions for new questions, please contribute!