Documentation Site with VitePress (Vue 3)

Building documentation is a routine many postpone. Docusaurus slows down on large projects (500 pages take 5 minutes to build), GitBook costs money, and a custom solution eats up days. VitePress solves these problems: static site on Vite and Vue 3, build time in seconds, not minutes. We'll set up such a site turnkey: from structure to deployment. Get a consultation to discuss your project.

Why VitePress for Documentation?

VitePress is not just a generator, but an ecosystem for technical docs. It builds faster than alternatives (3 seconds for 200 pages), natively supports Vue components in Markdown, and is easy to configure. According to VitePress docs, hydration mismatch doesn't occur because it's static — no SSR. LCP and FCP are minimal due to preloading, ensuring perfect Core Web Vitals. Static files require cheap hosting — saving up to 70% compared to dynamic CMS.

Comparison with Other Generators

VitePress wins on speed and customization flexibility, especially if you use the Vue stack.

Common Problems and Solutions

1. Generating a Sidebar from File Structure Manually describing the sidebar for a large project is a nightmare. We automate it: write a script that scans folders and builds the menu. The code below reads all .md files (excluding index.md) and creates a link array.

// .vitepress/utils/generateSidebar.ts import fs from 'fs'; import path from 'path'; export function generateSidebar(dir: string) { const files = fs.readdirSync(dir); return files .filter(f => f.endsWith('.md') && f !== 'index.md') .map(f => ({ text: f.replace('.md', '').replace(/-/g, ' '), link: `/${path.relative('docs', path.join(dir, f)).replace('.md', '')}`, })); } 

2. Setting Up Full-Text Search The built-in search is limited. We integrate Algolia: configure a crawler, set up indices (up to 10,000 records), and add the widget. This provides fast and accurate search across all pages.

3. Custom Vue Components in Markdown Want an interactive code example or a calculator? Add any Vue component directly in the markup. VitePress supports SFC right in the documentation.

# Component Demo <script setup> import { ref } from 'vue' const count = ref(0) </script> <button @click="count++">Count: {{ count }}</button> ::: tip This is a tip container. ::: ::: warning This is a warning. ::: ::: code-group ```sh [npm] npm install my-package 

pnpm add my-package 

:::

 ### How We Do It We use the stack: VitePress latest, Vue 3 Composition API, TypeScript, Tailwind for styling. We configure the config for your brand: logo, favicon, meta tags. We connect analytics, sitemap, RSS feed, set up CI/CD via GitHub Actions with node_modules caching. Example full config: ```typescript // .vitepress/config.ts import { defineConfig } from 'vitepress'; export default defineConfig({ title: 'My Project', description: 'Documentation for My Project', lang: 'ru-RU', themeConfig: { nav: [ { text: 'Guide', link: '/guide/introduction' }, { text: 'API', link: '/api/overview' }, { text: 'Changelog', link: '/changelog' }, ], sidebar: { '/guide/': [ { text: 'Introduction', items: [ { text: 'What is My Project?', link: '/guide/introduction' }, { text: 'Getting Started', link: '/guide/getting-started' }, { text: 'Configuration', link: '/guide/configuration' }, ]}, { text: 'Advanced', items: [ { text: 'Plugins', link: '/guide/plugins' }, { text: 'API', link: '/guide/api' }, ]}, ], }, search: { provider: 'algolia', options: { appId: 'APP_ID', apiKey: 'API_KEY', indexName: 'my-project', }, }, editLink: { pattern: 'https://github.com/my-org/my-project/edit/main/docs/:path', text: 'Edit this page', }, socialLinks: [ { icon: 'github', link: 'https://github.com/my-org/my-project' }, ], }, markdown: { theme: { light: 'github-light', dark: 'github-dark' }, config(md) { md.use(require('markdown-it-container'), 'tip'); }, }, }); 

How to Set Up Search on a VitePress Site

Search is critical for documentation. We configure Algolia: create an app, upload a crawler, configure indexing by selectors. Then integrate the widget into the theme. An alternative is local search via @algolia/autocomplete-js, but it requires a backend. For static sites, Algolia is optimal.

Process

1. Analysis — review your documentation structure, decide what to keep and what to rewrite.
2. Design — develop sidebar schema, navigation, SEO-friendly URL structure.
3. Implementation — configure VitePress, write custom components, connect search.
4. Testing — check all links, responsiveness, performance via Lighthouse.
5. Deployment — push static files to your hosting, configure CI/CD (e.g., via GitHub Actions).

Approximate Timelines

Pricing is calculated individually, depending on documentation volume and customization complexity.

What's Included

• Ready repository with VitePress configuration
• Custom theme (styles, logo, favicon)
• Automatic sidebar generation
• Search integration (Algolia or local)
• Deployment setup (Vercel/Cloudflare Pages)
• Documentation on content editing
• 1 hour of post-launch support

Common Mistakes When Setting Up Yourself

• Incorrect base path — if the site is not at the domain root, you must specify base in the config, otherwise resources won't load.
• Missing editLink — users cannot suggest edits, reducing trust.
• Ignoring SEO — missing meta tags, Open Graph, sitemap, causing poor indexing.
• Manual sidebar building — when adding new pages, they forget to update the config. Automation solves this.

Our Experience

We have been developing documentation sites for over 5 years. We have implemented projects for API services, libraries, and corporate products. We guarantee the site will meet modern performance and SEO standards.

Contact us to discuss your project. We'll assess the scope and suggest the optimal solution. Or simply order development — and get a ready documentation site in a short time.