Skip to main content

​
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

1
Step 1: Prerequisites
2
Ensure you have the required tools installed:
3
  • Node.js: v20 or higher
  • pnpm: Package manager (recommended)
    • 4
    # Install pnpm globally
npm install -g pnpm
    5
    VitePress uses pnpm for package management. While npm and yarn may work, pnpm is recommended for consistency.
    6
    Step 2: Fork and Clone
    7
  • Fork the VitePress repository on GitHub
  • Clone your fork locally:
    • 8
    git clone https://github.com/YOUR_USERNAME/vitepress.git
cd vitepress
    9
    Step 3: Install Dependencies
    10
    Install all project dependencies:
    11
    # Install dependencies
pnpm install

# Setup git hooks
pnpm simple-git-hooks
    12
    The git hooks will:
    13
  • Format code automatically on commit
  • Run linters to ensure code quality
    • 14
    Step 4: Start Development
    15
    VitePress offers multiple development modes:
    17
    The easiest way to test VitePress is by working on its documentation:
    18
    pnpm run docs
    19
    This will:
    20
  • Start the VitePress dev environment
  • Boot up the documentation site at http://localhost:5173
  • Enable live reloading when you modify source code
    • 21
    Option 2: Core Development
    22
    If you don’t need the docs site:
    23
    pnpm run dev
    24
    This starts just the VitePress development environment without the documentation server.

    ​
    Pull Request Guidelines

    1
    Step 1: Create a Topic Branch
    2
    Create a branch from main for your changes:
    3
    # Create and switch to a new branch
git checkout -b feat/my-awesome-feature

# Or for a bug fix
git checkout -b fix/issue-123
    4
    Step 2: Make Your Changes
    5
    For New Features:
    6
    Open a suggestion issue first and get approval before working on new features. This ensures your work aligns with project goals.
    7
  • Provide a convincing reason for the feature
  • Ideally, wait for maintainer approval
  • Consider the impact on existing functionality
    • 8
    For Bug Fixes:
    9
  • Provide a detailed description of the bug
  • Include a live demo if possible
  • Reference the issue number in your PR
    • 10
    Step 3: Follow Code Standards
    11
    Your code should:
    12
  • Be properly formatted (automatic via git hooks)
  • Include TypeScript types where applicable
  • Follow existing code style and patterns
  • Include comments for complex logic
    • 13
    Step 4: Write Tests
    14
    Add tests for your changes:
    15
    # Run unit tests
pnpm test:unit

# Run unit tests in watch mode
pnpm test:unit:watch

# Run e2e tests
pnpm test:e2e

# Run all tests
pnpm test
    16
    Step 5: Commit Your Changes
    17
    Commit messages MUST follow the commit message convention for automatic changelog generation.
    18
    git add .
git commit -m "feat(theme): add new sidebar feature"
    19
    Step 6: Push and Create PR
    20
    # Push your branch to your fork
git push origin feat/my-awesome-feature
    21
    Then create a Pull Request on GitHub.

    ​
    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

    Appears under “Features” in changelog:
    feat(theme): add home page feature
    Appears under “Bug Fixes” in changelog:
    fix(theme): remove underline on sidebar hover style

close #28
    Appears under “Performance Improvements” in changelog:
    perf: improve store getters performance by removing 'foo' option

BREAKING CHANGE: The 'foo' option has been removed.
    Documentation changes:
    docs: update migration guide for v2
    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

    ​
    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

    1. Find or create an issue describing the bug
    2. Create a branch: git checkout -b fix/issue-123
    3. Write a failing test that reproduces the bug
    4. Fix the bug and ensure the test passes
    5. Commit: fix: resolve issue with X
    6. Push and create PR

    ​
    Adding a Feature

    1. Open a discussion or issue proposing the feature
    2. Wait for approval from maintainers
    3. Create a branch: git checkout -b feat/awesome-feature
    4. Implement the feature with tests
    5. Update documentation if needed
    6. Commit: feat(scope): add awesome feature
    7. Push and create PR

    ​
    Improving Documentation

    1. Create a branch: git checkout -b docs/improve-guide
    2. Make changes to markdown files in docs/
    3. Test locally: pnpm run docs
    4. Commit: docs: improve migration guide
    5. Push and create PR

    ​
    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:

    ​
    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.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us