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/
├── .vitepress/            # VitePress configuration
│   ├── config.mts         # Site configuration
│   └── theme/             # Custom theme
├── src/
│   ├── 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
└── README.md              # Project documentation

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.mts
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/components/CustomLayout.vue (example) -->
<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 DefaultTheme from 'vitepress/theme';
const Layout = DefaultTheme.Layout;
</script>

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

Development Tools

VitePress Configuration

// .vitepress/config.mts
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',
    },
  },
});

VitePress Build Configuration

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

export default defineConfig({
  srcDir: 'src',
  outDir: '.output',
  vite: {
    resolve: {
      alias: {
        '@_shared': '../../_shared',
      },
    },
    server: {
      port: 9302,
    },
  },
});

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}\"",
    "format:check": "prettier --check \"src/**/*.{js,ts,vue,json,css,scss}\""
  }
}

Deployment

Build for Production

cd apps/my-docs

# Build the documentation site
pnpm build

# The built files will be in the .output 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