Development FAQ

Frequently asked questions about VitePress development workflow.

Getting Started

Q: How do I create a new VitePress project?

A: Use the following commands:

npm create vitepress@latest my-docs
cd my-docs
npm install
npm run docs:dev

Q: What's the recommended project structure?

A: Basic structure:

docs/
├── .vitepress/
│   └── config.js
├── index.md
├── guide/
│   └── index.md
└── package.json

Configuration

Q: How do I customize the theme?

A: You can:

1. Use theme configuration options
2. Override CSS variables
3. Create custom components
4. Build a custom theme

Q: How do I add a custom domain?

A: Steps:

1. Add CNAME file to public directory
2. Configure your DNS settings
3. Update base URL in config
4. Deploy your site

Content Creation

Q: How do I add navigation menus?

A: Configure in .vitepress/config.js:

export default {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ]
  }
}

Q: How do I create a sidebar?

A: Add sidebar configuration:

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

Customization

Q: Can I use custom Vue components?

A: Yes, you can:

1. Create components in .vitepress/components/
2. Register them globally
3. Use them in markdown files

Q: How do I add custom CSS?

A: Methods:

1. Add CSS to .vitepress/theme/style.css
2. Import CSS in custom theme
3. Use CSS variables for theming

Deployment

Q: How do I deploy to GitHub Pages?

A: Steps:

1. Configure base URL
2. Set up GitHub Actions workflow
3. Enable GitHub Pages
4. Push your changes

Q: Can I deploy to other platforms?

A: Yes, VitePress works with:

• Netlify
• Vercel
• AWS S3
• Azure Static Web Apps
• Any static hosting service

Troubleshooting

Q: My changes are not showing up

A: Try:

1. Hard refresh browser (Ctrl+F5)
2. Clear browser cache
3. Restart dev server
4. Check for syntax errors

Q: How do I debug build issues?

A: Use these commands:

npm run docs:build --debug
npm run docs:preview