VitePress

English

简体中文

English

简体中文

Appearance

Contributing ​

Thank you for your interest in contributing to VitePress Development Guide! This document provides guidelines and information for contributors.

Overview ​

We welcome contributions of all kinds:

  • 📝 Documentation improvements
  • 🐛 Bug reports and fixes
  • ✨ New features and enhancements
  • 🌍 Translations
  • 💡 Ideas and suggestions

Getting Started ​

Prerequisites ​

  • Node.js 18+
  • npm or yarn
  • Git
  • Basic knowledge of Vue.js and Markdown

Development Setup ​

  1. Fork and Clone
bash
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/vitepress-guide.git
cd vitepress-guide
  1. Install Dependencies
bash
npm install
  1. Start Development Server
bash
npm run dev
  1. Create a Branch
bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Project Structure ​

├── docs/
│   ├── .vitepress/
│   │   ├── config.ts          # Site configuration
│   │   ├── theme/             # Custom theme
│   │   └── components/        # Vue components
│   ├── zh/                    # Chinese documentation
│   ├── en/                    # English documentation
│   └── public/                # Static assets
├── package.json
└── README.md

Contributing Guidelines ​

Documentation ​

Writing Style ​

  • Clear and Concise: Use simple, direct language
  • Consistent Tone: Maintain a helpful, professional tone
  • Practical Examples: Include code examples and real-world use cases
  • Progressive Disclosure: Start simple, then add complexity

Markdown Standards ​

markdown
# Page Title (H1 - only one per page)

## Section Title (H2)

### Subsection (H3)

#### Details (H4)

- Use bullet points for lists
- Use `code` for inline code
- Use **bold** for emphasis
- Use *italic* for subtle emphasis

Code Examples ​

markdown
# Always include language identifier
```js
const config = {
  title: 'VitePress'
}

Use comments to explain complex code ​

vue
<template>
  <!-- Main content area -->
  <div class="content">
    {{ message }}
  </div>
</template>

#### File Naming
- Use kebab-case: `getting-started.md`
- Be descriptive: `custom-theme-development.md`
- Group related files in folders

### Code Contributions

#### Code Style
- Follow existing code patterns
- Use TypeScript when possible
- Add comments for complex logic
- Write self-documenting code

#### Vue Components
```vue
<template>
  <div class="component-name">
    <!-- Template content -->
  </div>
</template>

<script setup lang="ts">
// Use Composition API
// Add proper TypeScript types
interface Props {
  title: string
  optional?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  optional: false
})
</script>

<style scoped>
/* Use scoped styles */
.component-name {
  /* CSS properties */
}
</style>

Configuration Changes ​

ts
// .vitepress/config.ts
export default defineConfig({
  // Add comments explaining new options
  newOption: {
    // Describe what this does
    enabled: true
  }
})

Translation Guidelines ​

Adding New Languages ​

  1. Create language directory: docs/[lang-code]/
  2. Copy structure from docs/en/
  3. Update config file with new locale
  4. Translate content maintaining structure

Translation Standards ​

  • Maintain original meaning
  • Adapt examples to local context when appropriate
  • Keep technical terms consistent
  • Use native language conventions

Chinese Translation Example ​

markdown
# 快速开始

欢迎使用 VitePress 开发指南！

## 安装

```bash
npm install vitepress

配置 ​

创建配置文件：


## Pull Request Process

### Before Submitting
- [ ] Test your changes locally
- [ ] Check for broken links
- [ ] Verify responsive design
- [ ] Run linting and formatting
- [ ] Update relevant documentation

### PR Description Template
```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Translation
- [ ] Performance improvement

## Testing
- [ ] Tested locally
- [ ] All links work
- [ ] Responsive design verified
- [ ] No console errors

## Screenshots (if applicable)
Add screenshots to help explain your changes

## Additional Notes
Any additional information or context

Review Process ​

  1. Automated Checks: CI/CD pipeline runs tests
  2. Code Review: Maintainers review changes
  3. Feedback: Address any requested changes
  4. Merge: Approved PRs are merged

Issue Reporting ​

Bug Reports ​

Use the bug report template:

markdown
## Bug Description
Clear description of the bug

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: [e.g. macOS, Windows, Linux]
- Browser: [e.g. Chrome, Firefox, Safari]
- Node.js version: [e.g. 18.17.0]
- VitePress version: [e.g. 1.0.0]

## Additional Context
Screenshots, error logs, etc.

Feature Requests ​

markdown
## Feature Description
Clear description of the proposed feature

## Use Case
Why is this feature needed?

## Proposed Solution
How should this feature work?

## Alternatives Considered
Other solutions you've considered

## Additional Context
Any other relevant information

Development Workflow ​

Local Development ​

bash
# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

Testing Changes ​

bash
# Test specific pages
npm run dev
# Navigate to your changes in browser

# Test build process
npm run build
npm run preview

# Check for broken links
npm run check-links

Commit Guidelines ​

Commit Message Format ​

type(scope): description

[optional body]

[optional footer]

Types ​

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance tasks

Examples ​

bash
git commit -m "feat(guide): add deployment section"
git commit -m "fix(config): resolve navigation issue"
git commit -m "docs(contributing): update PR template"

Community Guidelines ​

Code of Conduct ​

  • Be respectful and inclusive
  • Welcome newcomers
  • Provide constructive feedback
  • Focus on the issue, not the person
  • Help others learn and grow

Communication ​

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and ideas
  • Pull Requests: Code and documentation changes

Getting Help ​

  • Check existing documentation first
  • Search existing issues and discussions
  • Provide detailed information when asking questions
  • Be patient and respectful

Recognition ​

Contributors ​

All contributors are recognized in:

  • GitHub contributors list
  • Documentation credits
  • Release notes (for significant contributions)

Maintainers ​

Current maintainers:

Development Resources ​

Tools and Extensions ​

  • VS Code Extensions:

    • Vetur or Volar for Vue
    • Markdown All in One
    • ESLint
    • Prettier

  • Browser Extensions:

    • Vue.js devtools
    • Accessibility insights

Learning Resources ​

FAQ ​

Common Questions ​

Q: How do I add a new page? A: Create a new .md file in the appropriate directory and add it to the sidebar configuration.

Q: How do I add images? A: Place images in the public directory and reference them with /image-name.jpg.

Q: How do I test my changes? A: Run npm run dev and navigate to your changes in the browser.

Q: Can I contribute if I'm a beginner? A: Absolutely! We welcome contributions from developers of all skill levels.

Q: How long does review take? A: Review time varies, but we aim to respond within a few days.

Troubleshooting ​

Common Issues ​

Build Errors

  • Check Node.js version (18+)
  • Clear node_modules and reinstall
  • Check for syntax errors in markdown

Development Server Issues

  • Check port availability (default 5173)
  • Clear browser cache
  • Restart development server

Git Issues

  • Ensure you're on the correct branch
  • Check remote repository URL
  • Verify Git configuration

Getting Support ​

If you encounter issues:

  1. Check this documentation
  2. Search existing issues
  3. Create a new issue with detailed information
  4. Join community discussions

Thank You ​

Thank you for contributing to VitePress Development Guide! Your contributions help make this resource better for everyone in the community.

This contributing guide is a living document. Please suggest improvements through issues or pull requests.

VitePress Development Guide

Copyright © 2025 mmwk.cn