Prettier 与 VitePress 集成指南

Prettier 可以帮助你统一 VitePress 文档的代码格式，提升可读性和维护性。以下是具体的配置步骤、使用方法和注意事项：

一、安装依赖

在 VitePress 项目中安装 Prettier 及其插件：

npm install prettier --save-dev

二、配置 Prettier

在项目根目录创建 .prettierrc.json 文件（或其他格式的配置文件）：

{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "singleQuote": true,
  "semi": false,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "proseWrap": "always",
  "htmlWhitespaceSensitivity": "css"
}

创建 .prettierignore 文件忽略不需要格式化的文件：

node_modules/
dist/
.vitepress/

三、集成到 VitePress 工作流

1. 命令行脚本

在 package.json 中添加格式化脚本：

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs",
    "format": "prettier --write \"docs/**/*.{md,js,ts,json,vue}\"",
    "format:check": "prettier --check \"docs/**/*.{md,js,ts,json,vue}\""
  }
}

2. 保存时自动格式化（VSCode）

安装 Prettier 插件并配置 .vscode/settings.json：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[markdown]": {
    "editor.formatOnSave": true
  },
  "[vue]": {
    "editor.formatOnSave": true
  }
}

四、Markdown 特殊配置

VitePress 主要使用 Markdown 文件，可通过 Prettier 插件优化 Markdown 格式：

npm install prettier-plugin-mdc --save-dev

在 .prettierrc.js 中配置：

module.exports = {
  plugins: ['prettier-plugin-mdc'],
  // 其他配置...
}

五、与 ESLint 配合（可选）

若项目中同时使用 ESLint，需避免规则冲突：

npm install eslint-config-prettier --save-dev

在 .eslintrc.js 中添加：

module.exports = {
  extends: ['eslint:recommended', 'prettier'],
  // 其他配置...
}

六、使用方法

1、手动格式化：

npm run format  # 格式化所有文档文件
npm run format:check  # 检查格式是否符合规范（用于 CI/CD）

2、自动格式化：

• 保存文件时自动格式化（需编辑器配置）
• 提交代码前自动格式化（通过 Git Hooks）

七、注意事项

1、VitePress 配置文件

• VitePress 配置文件（如 docs/.vitepress/config.js）会被 Prettier 格式化，确保其符合规范。

2、Markdown 内容

• Prettier 可能会改变 Markdown 中的代码块格式，需注意保持示例代码的正确性。
• 使用 注释忽略特定区域：

<!-- prettier-ignore -->
```html
<div class="custom-format">
  保持原有格式
</div>

3、Vue 组件

• VitePress 支持 Vue 组件，Prettier 会格式化 .vue 文件，确保其符合 Vue 语法。

4、插件兼容性

• 确保使用的 Prettier 插件与 VitePress 兼容（如 prettier-plugin-vue）。

八、推荐配置

以下是适合 VitePress 项目的 Prettier 配置示例：

{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "singleQuote": true,
  "semi": false,
  "trailingComma": "es5",
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "proseWrap": "always",
  "htmlWhitespaceSensitivity": "css",
  "vueIndentScriptAndStyle": true,
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "proseWrap": "always"
      }
    }
  ]
}

通过以上配置，你可以在 VitePress 项目中高效使用 Prettier 格式化 Markdown、Vue 组件和代码示例，保持文档风格统一。