CLI Tools

Overview

VitePress provides a set of Command Line Interface (CLI) tools to help you create, develop, build, and preview your documentation site. This guide covers all the available CLI commands and how to use them effectively.

Installation

Before using the CLI tools, you need to install VitePress:

# Using npm
npm install -D vitepress

# Using yarn
yarn add -D vitepress

# Using pnpm
pnpm add -D vitepress

Basic Commands

Initialize a New Project

Create a new VitePress project:

# Using npx
npx vitepress init

# If VitePress is installed locally
npm exec vitepress init

This interactive command will:

1. Ask for the project name
2. Set up the directory structure
3. Create initial configuration files
4. Generate sample documentation pages

Development Server

Start a local development server:

# Default command
npx vitepress dev [directory]

# With specific options
npx vitepress dev docs --port 3000 --open

Options:

• --port <port>: Specify port (default: 5173)
• --open: Open browser automatically
• --host: Expose to network
• --https: Use HTTPS
• --cors: Enable CORS

Build for Production

Build your site for production:

# Default command
npx vitepress build [directory]

# With specific options
npx vitepress build docs --mpa --outDir ./dist

Options:

• --outDir <dir>: Output directory (default: .vitepress/dist)
• --base <path>: Public base path (default: /)
• --mpa: Build in MPA mode instead of SPA
• --config <file>: Use specified config file
• --force: Force rebuild of dependencies

Preview Built Site

Preview your production build locally:

# Default command
npx vitepress preview [directory]

# With specific options
npx vitepress preview docs --port 8080

Options:

• --port <port>: Specify port (default: 5173)
• --host: Expose to network
• --base <path>: Public base path

Advanced Usage

Custom Scripts

Add convenient scripts to your package.json:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

Then use them with:

npm run docs:dev
npm run docs:build
npm run docs:preview

Environment Variables

VitePress CLI respects environment variables:

# Set base path
BASE_URL=/my-docs/ npx vitepress build

# Set mode
MODE=production npx vitepress build

# Set debug mode
DEBUG=vitepress* npx vitepress build

Debug Mode

Enable debug mode to see detailed logs:

# Using environment variable
DEBUG=vitepress* npx vitepress build

# Using command line flag
npx vitepress build --debug

Custom Configuration File

Specify a custom configuration file:

npx vitepress dev --config my-config.js

Creating Custom Commands

You can extend VitePress CLI with custom commands using Node.js scripts:

// scripts/generate-api-docs.js
const { createServer } = require('vitepress')
const fs = require('fs')
const path = require('path')

async function generateApiDocs() {
  // Your custom logic here
  console.log('Generating API documentation...')
  
  // Example: Generate API docs from JSON schema
  const schema = require('../api-schema.json')
  let output = '# API Reference\n\n'
  
  for (const endpoint of schema.endpoints) {
    output += `## ${endpoint.name}\n\n`
    output += `\`${endpoint.method} ${endpoint.path}\`\n\n`
    output += endpoint.description + '\n\n'
    // Add more details...
  }
  
  fs.writeFileSync(
    path.resolve(__dirname, '../docs/api-reference.md'),
    output
  )
  
  console.log('API documentation generated!')
}

generateApiDocs()

Add it to your package.json:

{
  "scripts": {
    "docs:api": "node scripts/generate-api-docs.js",
    "docs:dev": "npm run docs:api && vitepress dev docs"
  }
}

Integrating with Other Tools

Using with TypeScript

Create a TypeScript-powered CLI script:

// scripts/build.ts
import { build } from 'vitepress'
import { fileURLToPath } from 'url'
import { dirname, resolve } from 'path'

const __dirname = dirname(fileURLToPath(import.meta.url))

async function main() {
  console.log('Building documentation...')
  
  await build(resolve(__dirname, '../docs'), {
    outDir: resolve(__dirname, '../public'),
    base: '/docs/'
  })
  
  console.log('Documentation built successfully!')
}

main().catch(err => {
  console.error(err)
  process.exit(1)
})

Using with Monorepos

In monorepos, you might want to build multiple documentation sites:

// scripts/build-all-docs.js
const { build } = require('vitepress')
const path = require('path')
const fs = require('fs')

async function buildAllDocs() {
  const packagesDir = path.resolve(__dirname, '../packages')
  const packages = fs.readdirSync(packagesDir)
  
  for (const pkg of packages) {
    const docsDir = path.join(packagesDir, pkg, 'docs')
    if (fs.existsSync(docsDir)) {
      console.log(`Building docs for ${pkg}...`)
      await build(docsDir, {
        outDir: path.resolve(__dirname, `../dist/docs/${pkg}`),
        base: `/docs/${pkg}/`
      })
    }
  }
}

buildAllDocs().catch(err => {
  console.error(err)
  process.exit(1)
})

Best Practices

1. Use npm Scripts: Define common operations in your package.json scripts.

2. Automate Repetitive Tasks: Create custom scripts for tasks like generating API documentation.

3. Use Environment Variables: Configure builds for different environments using environment variables.

4. Implement Pre-commit Hooks: Use tools like Husky to run linting and validation before commits.

5. Create Build Pipelines: Chain commands together for complete workflows.

Frequently Asked Questions

How can I change the default port?

Use the --port option:

npx vitepress dev docs --port 3000

Can I build multiple documentation sites from one project?

Yes, you can create custom build scripts that build multiple sites:

// build-multi.js
const { build } = require('vitepress')

async function buildMulti() {
  // Build main docs
  await build('docs', { outDir: 'dist/docs' })
  
  // Build API docs with different config
  await build('api-docs', { 
    outDir: 'dist/api',
    configFile: 'api-docs/.vitepress/config.js'
  })
}

buildMulti()

How do I debug VitePress build issues?

Use the debug mode:

DEBUG=vitepress* npx vitepress build

This will show detailed logs about the build process, which can help identify issues.

Related Resources

• VitePress Official Documentation
• Vue.js Official Documentation
• More Tutorials

---

This document will be continuously updated. If you have any questions, please provide feedback through GitHub Issues.