Разработка сайта на VitePress (документация)

Разработка сайта на VitePress (документация)

VitePress — генератор статических сайтов на Vite + Vue 3, оптимизированный для технической документации. Быстрее Docusaurus при сборке, нативно поддерживает Vue-компоненты в Markdown.

Инициализация

npm init vitepress@latest
# Выбираем: Default Theme, TypeScript
cd docs
npm install
npm run dev

.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');
    },
  },
});

Vue-компоненты в Markdown

# 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

:::

### Генерация sidebar из файловой структуры

```typescript
// .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', '')}`,
    }));
}

Разработка VitePress-сайта документации — 2–4 дня.