Contributing to VitePress

We’re excited that you’re interested in contributing to VitePress! This guide will help you get started with contributing to the project.

Code of Conduct

VitePress has adopted the same Code of Conduct as the Vue.js project. Please read and follow it.

Ways to Contribute

Report Bugs

Help us identify and fix issues by reporting bugs you encounter.

Suggest Features

Share ideas for new features or improvements to existing ones.

Improve Documentation

Help make the docs better by fixing errors or adding examples.

Submit Code

Contribute bug fixes, new features, or performance improvements.

Development Setup

Pull Request Guidelines

Commit Message Convention

VitePress follows the Angular commit convention for automated changelog generation.

Format

Commit messages must match this pattern:

/^(revert: )?(feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip)(\(.+\))?: .{1,50}/

Structure

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Types

feat - New Feature

Appears under “Features” in changelog:

feat(theme): add home page feature

fix - Bug Fix

Appears under “Bug Fixes” in changelog:

fix(theme): remove underline on sidebar hover style

close #28

perf - Performance Improvement

Appears under “Performance Improvements” in changelog:

perf: improve store getters performance by removing 'foo' option

BREAKING CHANGE: The 'foo' option has been removed.

docs - Documentation

Documentation changes:

docs: update migration guide for v2

Other Types

Other valid types (won’t appear in changelog unless they have BREAKING CHANGE):

style: Code style changes (formatting, semicolons, etc)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks
build: Build system changes
ci: CI configuration changes
dx: Developer experience improvements

Scope

The scope specifies the area of change:

theme: Default theme changes
client: Client-side code
build: Build system
markdown: Markdown processing
search: Search functionality
etc.

Subject Guidelines

Use imperative, present tense: “change” not “changed” or “changes”
Don’t capitalize first letter
No period (.) at the end
Keep under 50 characters

Breaking Changes

If your commit includes breaking changes:

feat(config): change default theme color

BREAKING CHANGE: Default theme color changed from blue to purple.
Users need to update their custom CSS.

Examples

feat(theme): add dark mode toggle

fix(search): resolve input placeholder cutoff on mobile

closes #4106

perf: make git timestamps faster with single call

BREAKING CHANGE: getTimestamp API changed to getTimestamps.

revert: feat(theme): add home page feature

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Testing Guidelines

Unit Tests

Located in __tests__/unit/:

# Run unit tests
pnpm test:unit

# Watch mode for development
pnpm test:unit:watch

E2E Tests

Located in __tests__/e2e/:

# Run e2e tests in dev mode
pnpm test:e2e-dev

# Run e2e tests in build mode
pnpm test:e2e-build

# Watch mode
pnpm test:e2e-dev:watch

Init Tests

Tests for the vitepress init command:

pnpm test:init

Code Style

VitePress uses Prettier for code formatting:

# Format all files
pnpm format

# Check formatting without making changes
pnpm format:fail

Code is automatically formatted on commit via git hooks, so you usually don’t need to run these manually.

Project Structure

vitepress/
├── src/
│   ├── client/        # Client-side code
│   │   ├── app/       # Vue app
│   │   └── theme-default/  # Default theme
│   └── node/          # Node.js API and build logic
├── __tests__/         # Test files
│   ├── unit/          # Unit tests
│   ├── e2e/           # End-to-end tests
│   └── init/          # Init command tests
├── docs/              # Documentation source
│   └── .vitepress/    # Docs config
├── scripts/           # Build and dev scripts
└── types/             # TypeScript type definitions

Development Workflow

Making a Bug Fix

Adding a Feature

Improving Documentation

Building VitePress

Development Build

# Build with watch mode
pnpm run dev

Production Build

# Full production build
pnpm run build

# Build only client code
pnpm run build:client

# Build only node code
pnpm run build:node

Build Documentation

# Build docs site
pnpm run docs:build

# Preview built docs
pnpm run docs:preview

Getting Help

If you need help contributing:

GitHub Discussions: vuejs/vitepress/discussions
Discord: chat.vuejs.org
Issues: Search existing issues or create a new one

Recognition

All contributors are recognized in:

GitHub contributors list
Release notes for their contributions
The VitePress community

Thank you for contributing to VitePress! Every contribution, no matter how small, makes a difference.

License

By contributing to VitePress, you agree that your contributions will be licensed under its MIT License.

Resources

Contributing Guide

Contributing to VitePress

Code of Conduct

Ways to Contribute

Report Bugs

Suggest Features

Improve Documentation

Submit Code

Development Setup

Pull Request Guidelines

Commit Message Convention

Format

Structure

Types

Scope

Subject Guidelines

Breaking Changes

Examples

Testing Guidelines

Unit Tests

E2E Tests

Init Tests

Code Style

Project Structure

Development Workflow

Making a Bug Fix

Adding a Feature

Improving Documentation

Building VitePress

Development Build

Production Build

Build Documentation

Getting Help

Recognition

License

​Contributing to VitePress

​Code of Conduct

​Ways to Contribute

Report Bugs

Suggest Features

Improve Documentation

Submit Code

​Development Setup

​Pull Request Guidelines

​Commit Message Convention

​Format

​Structure

​Types

​Scope

​Subject Guidelines

​Breaking Changes

​Examples

​Testing Guidelines

​Unit Tests

​E2E Tests

​Init Tests

​Code Style

​Project Structure

​Development Workflow

​Making a Bug Fix

​Adding a Feature

​Improving Documentation

​Building VitePress

​Development Build

​Production Build

​Build Documentation

​Getting Help

​Recognition

​License

Contributing to VitePress

Code of Conduct

Ways to Contribute

Development Setup

Pull Request Guidelines

Commit Message Convention

Format

Structure

Types

Scope

Subject Guidelines

Breaking Changes

Examples

Testing Guidelines

Unit Tests

E2E Tests

Init Tests

Code Style

Project Structure

Development Workflow

Making a Bug Fix

Adding a Feature

Improving Documentation

Building VitePress

Development Build

Production Build

Build Documentation

Getting Help

Recognition

License