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.

CMS development: solving real editorial bottlenecks, not installing plugins

A news publisher had a WordPress site with 5 editors. Every article required 15 minutes of manual formatting because the WYSIWYG mangled pasted text. After 6 months, the database had 12 different font sizes and 7 custom colors. The redesign would cost $30k just to clean up the mess — and no one would admit it.

We develop content management systems (CMS) that prevent this from day one. Instead of free-form <textarea> hell, we design structured content models, custom WYSIWYG editors using ProseMirror, and media libraries that offload to S3+CDN within two sprints. This is CMS development without shortcuts.

When is headless CMS justified and when not?

Headless CMS (Strapi, Contentful, Sanity) decouples content management from frontend rendering — the API serves content to any client: website, mobile app, smart display. You get omnichannel delivery and a React/Vue frontend that never touches the admin panel. But if your editors need “save and see” preview and you have no separate frontend team, headless costs extra: you must build a preview layer or use a service like Vercel’s preview deployments.

Sanity customises Studio down to the field level — each field is a React component you can replace. Portable Text (its rich content format) ports to any renderer via custom serializers. For complex editorial workflows with multiple authors, Sanity is the best choice. Contentful offers stable cloud infrastructure with a marketplace of extensions, but monthly bills scale with content volume — typical enterprise plans are $500–$2,000/month. Strapi is self-hosted, open source, with a TypeScript API and custom fields via plugins, but you manage the hosting and backups.

Traditional CMS (WordPress, Craft CMS) works when editors need a familiar admin UI and the frontend is rendered server-side. Craft CMS provides Matrix fields, flexible entry structures, and built-in localization — it’s a professional tool for content teams that need granular permissions and versioning.

How do we build a WYSIWYG editor that doesn’t break layout?

The editor is the most complex component — not a <textarea>. The sweet spot is Tiptap, built on ProseMirror. Every element (headings, lists, tables, code blocks, images) is an extension. Collaborative editing via Yjs works out of the box. Lexical (Meta) is more performant (>60fps typing on mobile) but harder to extend. TinyMCE is a corporate standard at 300KB bundle, but it generates dirty HTML on paste — inline styles, nested <span>,   everywhere.

The root cause: pasting from Word. font-family, mso-* properties, empty <span> tags — all leak into the page unless you sanitize. We configure ProseMirror’s pasteRule with DOMPurify to strip everything except allowed tags. Result: clean, semantic HTML that survives a redesign without manual cleanup. Editors save 2–4 hours per week per person.

Media library: from upload to CDN with transformation

Saving files to the server disk is the classic mistake. The disk fills, scaling fails, and CDN becomes impossible. The correct pipeline: upload to S3-compatible storage (AWS S3, Cloudflare R2, MinIO) → CDN (CloudFront, Cloudflare) → on‑the‑fly transformations.

Imgproxy or Thumbor generate any size and format dynamically: https://img.example.com/resize:800:600/format:webp/plain/s3://bucket/photo.jpg. The original lives once, derivatives never occupy disk. Cloudflare Images costs $5 per 100k images, including transformations. Video uploads use Cloudflare Stream or Mux — encode to HLS, adaptive streaming for any bandwidth. Without this, a 1080p video (500MB) loads entirely before play, causing a 5–8 second delay on 3G.

What’s included in media library development

Why structured content outperforms free-form HTML

Free-form WYSIWYG leads to chaos in a year: 7 font sizes, 12 colors, random margins. Redesign requires manual cleanup of thousands of posts. Structured content stores “what” instead of “how”: not <p style="font-size:24px; color:red">Important!</p>, but a callout block with variant: warning. The CMS stores the structure; the frontend decides rendering. Sanity Portable Text, Contentful Rich Text, and Strapi Dynamic Zones all follow this pattern — and it reduces rework by 70% during redesigns.

Work process

1. Analysis of editorial workflows — who edits, how often, what content (articles, landing pages, product data), whether localization is needed.
2. CMS selection — based on scenarios, not trends. We compare headless vs traditional with a weighted matrix.
3. Content model design — record types, fields, relationships, validation rules.
4. Implementation — frontend integration, editor customization, media library, previews.
5. Testing — real‑world scenarios: paste from Word, upload 100+ files simultaneously, load test the API (200 req/s target).
6. Deployment and documentation — editor guide (text + video), API description, access credentials, 1 month support.

Timelines and budget

Budget is calculated individually after an audit. Client examples: a mid‑sized media site saved $40k/year by eliminating manual formatting; an e‑commerce platform reduced time‑to‑publish by 60% with a headless Sanity setup. Contact us for a free project estimate.

What you get after delivery

• Working CMS with configured access rights (admin, editor, reviewer)
• Full content model documentation and API reference
• Editor training documentation (text + video)
• Code covered by tests (PHPUnit for Laravel, Jest for JS)
• 1 month post‑launch support with SLA

Our experience and guarantees

Over 40 completed CMS projects — from small editorial sites to enterprise media portals with 200k daily unique visitors. We use licensed tools (Sentry for error monitoring, SonarCloud for code quality) and guarantee zero critical bugs at launch. All code is version‑controlled and deployable via CI/CD.

For your specific needs, contact us to discuss requirements. We’ll provide a technical proposal within 2 business days.