VitePress Template

The VitePress template provides a modern static site generator for documentation, perfect for creating beautiful documentation sites with Vue 3 and Markdown.

Technical Stack

• VitePress - Static site generator
• Vue 3 - Progressive JavaScript framework
• TypeScript - Type-safe development
• Vite - Fast build tool and dev server
• Markdown - Content authoring
• Tailwind CSS - Utility-first CSS framework
• SCSS - CSS preprocessor

Quick Start

1. Create Project

# Initialize project
vup init my-docs-project
cd my-docs-project

# Add VitePress template
vup add my-docs

2. Install Dependencies

# Install dependencies
pnpm install

3. Start Development

# Start development server
cd apps/my-docs
pnpm dev

The documentation site will be available at http://localhost:9302.

Project Structure

apps/my-docs/
├── src/
│   ├── .vitepress/        # VitePress configuration
│   │   ├── config.ts      # Site configuration
│   │   └── theme/         # Custom theme
│   ├── en/                # English content
│   │   ├── index.md       # English home page
│   │   └── docs.md        # English documentation
│   ├── public/            # Public assets
│   │   └── images/        # Image files
│   ├── index.md           # Home page
│   └── docs.md            # Documentation
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── vite.config.ts         # Vite configuration

Core Features

Markdown Content

# Welcome to VitePress

This is a **VitePress** documentation site.

## Features

- Fast and lightweight
- Vue 3 powered
- TypeScript support
- Markdown with Vue components

Vue Components in Markdown

<template>
  <div class="custom-component">
    <h3>{{ title }}</h3>
    <p>{{ description }}</p>
  </div>
</template>

<script setup lang="ts">
interface Props {
  title: string;
  description: string;
}

const props = defineProps<Props>();
</script>

<style scoped>
.custom-component {
  @apply p-4 bg-blue-50 rounded-lg;
}
</style>

Internationalization

// .vitepress/config.ts
export default defineConfig({
  locales: {
    root: {
      label: 'English',
      lang: 'en',
      title: 'VitePress Docs',
      description: 'A VitePress site',
    },
    zh: {
      label: '中文',
      lang: 'zh',
      title: 'VitePress 文档',
      description: '一个 VitePress 网站',
    },
  },
  themeConfig: {
    locales: {
      root: {
        nav: [
          { text: 'Home', link: '/' },
          { text: 'Docs', link: '/docs' },
        ],
        sidebar: [{ text: 'Introduction', link: '/docs' }],
      },
      zh: {
        nav: [
          { text: '首页', link: '/zh/' },
          { text: '文档', link: '/zh/docs' },
        ],
        sidebar: [{ text: '介绍', link: '/zh/docs' }],
      },
    },
  },
});

Custom Theme

<!-- .vitepress/theme/Layout.vue -->
<template>
  <Layout>
    <template #nav-bar-title-after>
      <div class="custom-nav">
        <a href="/en/">English</a>
        <a href="/zh/">中文</a>
      </div>
    </template>
  </Layout>
</template>

<script setup lang="ts">
import Layout from 'vitepress/dist/client/theme-default/Layout.vue';
</script>

<style scoped>
.custom-nav {
  @apply flex space-x-4;
}
</style>

Development Tools

VitePress Configuration

// .vitepress/config.ts
import { defineConfig } from 'vitepress';

export default defineConfig({
  title: 'VitePress Docs',
  description: 'A VitePress site',
  base: '/',
  lang: 'en',
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Docs', link: '/docs' },
    ],
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/docs' },
          { text: 'Getting Started', link: '/docs/getting-started' },
        ],
      },
    ],
    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
    ],
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2024 VitePress',
    },
  },
});

Vite Configuration

// vite.config.ts
import { defineConfig } from 'vite';
import { resolve } from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
      '@shared': resolve(__dirname, '../../_shared'),
    },
  },
  css: {
    postcss: resolve(__dirname, '../../postcss.config.js'),
  },
  server: {
    host: '0.0.0.0',
    port: 9302,
    open: false,
  },
});

Available Scripts

{
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview",
    "lint": "eslint src/ --ext .vue,.ts,.js",
    "lint:fix": "eslint src/ --ext .vue,.ts,.js --fix",
    "format": "prettier --write \"src/**/*.{js,ts,vue,json,css,scss,md}\"",
    "format:check": "prettier --check \"src/**/*.{js,ts,vue,json,css,scss,md}\""
  }
}

Best Practices

Content Organization

src/
├── .vitepress/
│   ├── config.ts          # Site configuration
│   └── theme/             # Custom theme
├── en/                    # English content
│   ├── index.md
│   ├── docs/
│   │   ├── index.md
│   │   └── getting-started.md
│   └── api/
│       └── index.md
├── zh/                    # Chinese content
│   ├── index.md
│   ├── docs/
│   │   ├── index.md
│   │   └── getting-started.md
│   └── api/
│       └── index.md
└── public/                # Static assets
    └── images/

Markdown Writing

# Page Title

Brief description of the page.

## Section 1

Content for section 1.

### Subsection 1.1

Content for subsection 1.1.

## Section 2

Content for section 2.

::: tip This is a tip box. :::

::: warning This is a warning box. :::

::: danger This is a danger box. :::

Vue Components

<template>
  <div class="component-demo">
    <h3>{{ title }}</h3>
    <p>{{ description }}</p>
    <button @click="handleClick" class="btn">
      {{ buttonText }}
    </button>
  </div>
</template>

<script setup lang="ts">
interface Props {
  title: string;
  description: string;
  buttonText: string;
}

const props = defineProps<Props>();

const handleClick = () => {
  console.log('Button clicked!');
};
</script>

<style scoped>
.component-demo {
  @apply p-4 border rounded-lg;
}

.btn {
  @apply px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600;
}
</style>

Deployment

Build for Production

# Build the documentation site
pnpm build

# The built files will be in the .vitepress/dist directory

Deploy to Vercel

See Vercel Deployment Guide for detailed deployment instructions.

Related Resources

• VitePress Official Documentation
• Vue 3 Documentation
• Vite Documentation
• Markdown Guide
• Tailwind CSS Documentation