markdownlint

Markdownlint

包管理器检测

执行任何操作之前，检测项目使用的包管理器：

1. 检查锁定文件：

   • pnpm-lock.yaml → 使用 pnpm
   • yarn.lock → 使用 yarn
   • package-lock.json → 使用 npm
   • bun.lockb → 使用 bun

2. 检查 package.json 中的 packageManager 字段：

   "packageManager": "[email protected]"
   

3. 如果没有任何标识，请询问用户偏好的包管理器

在整个技能过程中，命令均以 pnpm 为例。请替换为检测到的包管理器：

• pnpm add -D → npm install --save-dev / yarn add -D / bun add -d
• pnpm run → npm run / yarn run / bun run
• pnpm install → npm install / yarn install / bun install

操作选择指南

根据请求的工作内容阅读相应参考文档：

操作	参考文档
安装、配置文件、脚本和验证说明	设置
规则名称、代码、选项、启用或禁用规则	规则
忽略的文件、文件夹、模式和检查排除项	忽略
诊断违规项、自动修复和剩余的手动修复	修复
脚本、钩子、CI 和编辑器集成	集成
文件缺失、钩子失败、安装错误或性能问题	故障排除

如果请求涉及多项操作，请先阅读主要参考文档，再阅读完成并验证设置所需的相关参考文档。

快速参考：常用命令

# Install
pnpm add -D markdownlint markdownlint-cli

# Run linting
pnpm run lint:markdown

# Auto-fix issues
vpx markdownlint '**/*.md' --fix

# Lint specific file
vpx markdownlint README.md

# Lint specific directory
vpx markdownlint 'docs/**/*.md'

快速参考：配置文件基础

项目根目录中的 .markdownlint.yaml：

$schema: ./node_modules/markdownlint/schema/markdownlint-config-schema.json

# Disable a rule
line-length: false

# Enable a rule
no-duplicate-heading: true

# Configure a rule
heading-style:
  style: "atx"

项目根目录中的 .markdownlintignore（gitignore 语法）：

node_modules
dist/
build/
CHANGELOG.md

默认配置理念

设置 markdownlint 时，请使用以下主张鲜明的默认配置：

$schema: ./node_modules/markdownlint/schema/markdownlint-config-schema.json

line-length: false # Modern editors handle wrapping

保留标准规则启用状态，并在此默认配置中禁用 line-length，原因如下：

• 现代编辑器和查看器会自动换行文本
• 固定行长会给大多数项目带来不必要的阻碍
• 捕捉语义问题比处理呈现问题更有价值

当用户提出要求或既定项目要求有此需要时，可自定义其他规则。