migrate4-5

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

migrate4-5

Guides you through migrating markuplint configuration from v4 to v5.

指导您将markuplint配置从v4迁移至v5。

When to Use

使用场景

Use this skill when the user requests any of the following:

"Upgrade markuplint to v5"
"Migrate markuplint from v4 to v5"
"Update markuplint version"
"markuplint migration"

当用户提出以下任一请求时使用此技能：

"升级markuplint至v5"
"将markuplint从v4迁移到v5"
"更新markuplint版本"
"markuplint迁移"

Steps

步骤

1. Detect Current Versions

1. 检测当前版本

Detect the current versions of markuplint-related packages (
```
markuplint
```
,
```
@markuplint/*
```
) from
```
package.json
```
and list them

Locate and review configuration files (

.markuplintrc

.markuplintrc.json

markuplint.config.js

, etc.)

从
```
package.json
```
中检测markuplint相关包（
```
markuplint
```
、
```
@markuplint/*
```
）的当前版本并列出

定位并查阅配置文件（

.markuplintrc

、

.markuplintrc.json

、

markuplint.config.js

等）

2. Review the Migration Guide

2. 查阅迁移指南

Use WebFetch to retrieve https://markuplint.dev/docs/migration/ or https://next.markuplint.dev/docs/migration/ and review breaking changes between the versions
Check the version-specific migration guide (e.g., v4-to-v5) if available
Pay special attention to Named Rule Group changes
Identify newly added rules and list those not included in the recommended preset
Inspect source code and preset definitions in
```
node_modules/markuplint
```
for accurate information

使用WebFetch获取https://markuplint.dev/docs/migration/或https://next.markuplint.dev/docs/migration/，查阅版本间的破坏性变更
若有版本专属迁移指南（如v4-to-v5），请查阅该指南
特别关注命名规则组（Named Rule Group）的变更
识别新增规则，并列出推荐预设中未包含的规则
查看
```
node_modules/markuplint
```
中的源代码和预设定义以获取准确信息

3. Confirm with the User (use AskUserQuestion extensively)

3. 与用户确认（大量使用AskUserQuestion）

Important: Always use AskUserQuestion at each decision point. Never make decisions without user confirmation. AskUserQuestion supports up to 4 questions at once. Batch related questions for efficiency. For rules that require configuration values, always confirm the specific values (whether
true
suffices or custom values are needed).

重要提示：在每个决策点务必使用AskUserQuestion。切勿在未获得用户确认的情况下自行决策。 AskUserQuestion最多支持同时提出4个问题。将相关问题批量处理以提升效率。 对于需要配置值的规则，务必确认具体值（是仅需设为
true
还是需要自定义值）。

Phase 1: Handling Breaking Changes

第一阶段：处理破坏性变更

Confirm the approach for each breaking change (adopt latest behavior vs. preserve legacy behavior)
If ARIA version changes exist, confirm the approach
Confirm the update scope of related parsers/plugins (e.g.,
```
@markuplint/pug-parser
```
)
Discuss alternatives for removed/deprecated features

确认每个破坏性变更的处理方式（采用最新行为 vs. 保留旧版行为）
若存在ARIA版本变更，确认处理方式
确认相关解析器/插件（如
```
@markuplint/pug-parser
```
）的更新范围
讨论已移除/废弃功能的替代方案

Phase 2: Adopting New Rules

第二阶段：采用新规则

Present the list of rules not included in the recommended preset and confirm whether to adopt each
Provide explanations and benefits for each rule to help the user decide
All rules may be presented as options at once

列出推荐预设中未包含的规则，并确认是否采用每条规则
为每条规则提供说明和优势，帮助用户决策
可一次性展示所有规则作为选项

Phase 3: Rule Configuration Values (for each rule adopted in Phase 2)

第三阶段：规则配置值（针对第二阶段采用的每条规则）

Always confirm whether
true
is sufficient or custom configuration is needed
Rules like
```
attr-order
```
significantly change behavior based on their configuration values — have the user specify the exact attribute order
For rules depending on external configuration (e.g., browserslist), explain this and verify the project's setup
After receiving answers, repeat them back to confirm mutual understanding

务必确认仅设为
true
是否足够，还是需要自定义配置
像
```
attr-order
```
这类规则的行为会因配置值发生显著变化，请让用户指定确切的属性顺序
对于依赖外部配置的规则（如browserslist），进行说明并验证项目的相关设置
收到回复后，重复内容以确认双方理解一致

4. Update Dependency Versions

4. 更新依赖版本

Update markuplint-related package versions in
```
package.json
```
Run the package manager to update dependencies
Ensure parser versions match the markuplint core version (e.g.,
```
@markuplint/pug-parser
```
should be the same version)

在
```
package.json
```
中更新markuplint相关包的版本
运行包管理器更新依赖
确保解析器版本与markuplint核心版本匹配（如
```
@markuplint/pug-parser
```
应使用相同版本）

5. Update Configuration Files

5. 更新配置文件

Update configuration files based on the user's responses. Key areas:

Preset name changes
```
overrideMode
```
behavior changes
```
nodeRules
```
/
```
childNodeRules
```
selector and format changes
Conversion to Named Rule Groups (see reference below)
```
parser
```
configuration format changes
Addition of new rules

根据用户的回复更新配置文件，重点关注以下领域：

预设名称变更
```
overrideMode
```
行为变更
```
nodeRules
```
/
```
childNodeRules
```
选择器和格式变更
转换为命名规则组（Named Rule Groups，见下方参考）
```
parser
```
配置格式变更
新增规则的添加

6. Update Tests

6. 更新测试

Run markuplint and review the output for each test case
Include
```
ruleId
```
and Named Rule Group names in test output format
Update fixture files to comply with new rules (especially attr-order)
Changing attribute order affects column numbers — update expected values in related tests accordingly
Ensure all tests pass

运行markuplint并查看每个测试用例的输出
在测试输出格式中包含
```
ruleId
```
和命名规则组名称
更新测试夹具文件以符合新规则（尤其是attr-order规则）
属性顺序变更会影响列号——相应更新相关测试中的预期值
确保所有测试通过

7. Commit

7. 提交代码

Split commits by package and change type:

feat(markuplint)!: upgrade markuplint to vX.X.X

— package.json + lockfile

test(markuplint): update test expectations

— test expectation updates

feat(markuplint): convert rules to new format

— configuration file changes

test(markuplint): add tests for new rules

— tests for new rules

按包和变更类型拆分提交：

feat(markuplint)!: upgrade markuplint to vX.X.X

—— package.json + 锁文件

test(markuplint): update test expectations

—— 测试预期更新

feat(markuplint): convert rules to new format

—— 配置文件变更

test(markuplint): add tests for new rules

—— 新增规则的测试

Reference: Named Rule Groups

参考：命名规则组（Named Rule Groups）

In versions that support Named Rule Groups, adding a

name

property to

nodeRules

entries creates a Named Rule Group. The

name

serves as a reference key from the

rules

section and is displayed as

[name]

in violation messages.

在支持命名规则组的版本中，为

nodeRules

条目添加

name

属性即可创建命名规则组。

name

可作为

rules

部分的引用键，并会在违规消息中显示为

[name]

。

Pattern 1: Add name to nodeRules

模式1：为nodeRules添加name属性

// Before
nodeRules: [
  {
    selector: 'img',
    rules: {
      'required-attr': { value: 'alt', reason: '...' },
    },
  },
]

// After
nodeRules: [
  {
    name: 'my-project/img-require-alt',  // added
    selector: 'img',
    rules: {
      'required-attr': { value: 'alt', reason: '...' },
    },
  },
]

// 之前
nodeRules: [
  {
    selector: 'img',
    rules: {
      'required-attr': { value: 'alt', reason: '...' },
    },
  },
]

// 之后
nodeRules: [
  {
    name: 'my-project/img-require-alt',  // 新增
    selector: 'img',
    rules: {
      'required-attr': { value: 'alt', reason: '...' },
    },
  },
]

Pattern 2: Convert rules to Named Rule Groups

模式2：将规则转换为命名规则组

// Before — defined directly in rules section
rules: {
  'disallowed-element': {
    value: ['br'],
    reason: '...',
  },
}

// After — nested as Named Rule Group
rules: {
  'my-project/no-br': {
    rules: {
      'disallowed-element': {
        value: ['br'],
        reason: '...',
      },
    },
  },
}

Named Rule Groups defined in presets can be individually controlled in the

rules

section:

rules: {
  'performance/img-aspect-ratio': false,                    // disable entirely
  'a11y/require-accessible-name': { severity: 'warning' },  // change severity
}

// 之前——直接在rules部分定义
rules: {
  'disallowed-element': {
    value: ['br'],
    reason: '...',
  },
}

// 之后——嵌套为命名规则组
rules: {
  'my-project/no-br': {
    rules: {
      'disallowed-element': {
        value: ['br'],
        reason: '...',
      },
    },
  },
}

预设中定义的命名规则组可在

rules

部分单独控制：

rules: {
  'performance/img-aspect-ratio': false,                    // 完全禁用
  'a11y/require-accessible-name': { severity: 'warning' },  // 更改严重级别
}

Reference: attr-order Rule

参考：attr-order规则

Attributes are ordered according to the specified array
```
{ group: 'aria' }
```
groups
```
aria-*
```
attributes together
```
{ group: 'data' }
```
groups
```
data-*
```
attributes together
Attributes not in the array are placed after the specified groups in alphabetical order
Existing fixture attribute order may need to be changed
Changing attribute order shifts column numbers, so expected values in other rule tests may also need updating

属性按指定数组的顺序排列
```
{ group: 'aria' }
```
将
```
aria-*
```
属性归为一组
```
{ group: 'data' }
```
将
```
data-*
```
属性归为一组
未在数组中的属性会按字母顺序排在指定组之后
现有测试夹具的属性顺序可能需要调整
属性顺序变更会改变列号，因此其他规则测试中的预期值可能也需要更新

Reference: Test Output Format

参考：测试输出格式

Violation messages for rules with Named Rule Groups include the group name. To verify in tests:

const formatted = violations.map(
  (v) =>
    `${n(v.filePath)}:${v.line}:${v.col} ${v.message} (${v.ruleId})${v.name ? ` [${v.name}]` : ''}`,
);

Example output:

file.html:9:9 ... (permitted-contents) [html-standard/permitted-contents]

file.html:26:3 ... (disallowed-element) [my-project/no-br]

带有命名规则组的规则的违规消息会包含组名称。可通过以下方式在测试中验证：

const formatted = violations.map(
  (v) =>
    `${n(v.filePath)}:${v.line}:${v.col} ${v.message} (${v.ruleId})${v.name ? ` [${v.name}]` : ''}`,
);

示例输出：

file.html:9:9 ... (permitted-contents) [html-standard/permitted-contents]

file.html:26:3 ... (disallowed-element) [my-project/no-br]

Reference:

-c

Flag Behavior

参考：

-c

标记行为

In some versions, the

-c

flag completely replaces the project's configuration file with the specified configuration. When using

-c

in tests, be aware that only the specified configuration may be applied.

在部分版本中，

-c

标记会用指定配置完全替换项目的配置文件。在测试中使用

-c

时，请注意可能只会应用指定的配置。

Reference: no-unsupported-features

参考：no-unsupported-features规则

A rule that detects browser-unsupported elements and attributes based on browserslist configuration
Becomes a no-op in projects without browserslist configuration

基于browserslist配置检测浏览器不支持的元素和属性的规则
在没有browserslist配置的项目中，该规则不会生效

migrate4-5

Original

Translation

migrate4-5

migrate4-5

When to Use

使用场景

Steps

步骤

1. Detect Current Versions

1. 检测当前版本

2. Review the Migration Guide

2. 查阅迁移指南

3. Confirm with the User (use AskUserQuestion extensively)

3. 与用户确认（大量使用AskUserQuestion）

Phase 1: Handling Breaking Changes

第一阶段：处理破坏性变更

Phase 2: Adopting New Rules

第二阶段：采用新规则

Phase 3: Rule Configuration Values (for each rule adopted in Phase 2)

第三阶段：规则配置值（针对第二阶段采用的每条规则）

4. Update Dependency Versions

4. 更新依赖版本

5. Update Configuration Files

5. 更新配置文件

6. Update Tests

6. 更新测试

7. Commit

7. 提交代码

Reference: Named Rule Groups

参考：命名规则组（Named Rule Groups）

Pattern 1: Add name to nodeRules

模式1：为nodeRules添加name属性

Pattern 2: Convert rules to Named Rule Groups

模式2：将规则转换为命名规则组

Reference: attr-order Rule

参考：attr-order规则

Reference: Test Output Format

参考：测试输出格式

Reference: -c Flag Behavior

参考：-c标记行为

Reference: no-unsupported-features

参考：no-unsupported-features规则

Reference:
`-c`
Flag Behavior

参考：
`-c`
标记行为