markuplint-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

markuplint-configure

Markuplint配置

Add, remove, or adjust Markuplint rules.

添加、移除或调整Markuplint规则。

When to Use

使用场景

"Add a rule for ..." / "Enable the ... rule"
"Disable this warning" / "Ignore this error"
"Configure markuplint for this file"
"This markuplint warning is wrong"
"Apply ... rule only to this section"
User points to a specific file/line and asks about a Markuplint violation

“为……添加规则” / “启用……规则”
“禁用此警告” / “忽略此错误”
“为此文件配置Markuplint”
“这个Markuplint警告有误”
“仅对该区块应用……规则”
用户指向特定文件/行并询问Markuplint违规问题

Steps

操作步骤

1. Understand the Context

1. 了解上下文

Determine the documentation site based on the installed markuplint version:

shell

npx markuplint --version

If the version contains
```
alpha
```
,
```
beta
```
, or
```
rc
```
(e.g.,
```
5.0.0-alpha.1
```
) → use
```
https://next.markuplint.dev
```
as the doc base
Otherwise (stable release) → use
```
https://markuplint.dev
```
as the doc base

Use the determined doc base for all documentation URLs in subsequent steps.

$ARGUMENTS

contains a file path or line reference, read that file first.

Run Markuplint on the target to see current violations:

shell

npx markuplint "path/to/file.html" --format JSON

If no specific file, run on the project and summarize.

根据已安装的Markuplint版本确定文档站点：

shell

npx markuplint --version

如果版本包含
```
alpha
```
、
```
beta
```
或
```
rc
```
（例如
```
5.0.0-alpha.1
```
）→ 使用
```
https://next.markuplint.dev
```
作为文档基准地址
其他情况（稳定版本）→ 使用
```
https://markuplint.dev
```
作为文档基准地址

在后续步骤中，所有文档URL均使用确定的基准地址。

如果

$ARGUMENTS

包含文件路径或行引用，请先读取该文件。

在目标文件上运行Markuplint以查看当前违规情况：

shell

npx markuplint "path/to/file.html" --format JSON

如果没有指定文件，则在整个项目上运行并汇总结果。

2. Identify What the User Wants

2. 明确用户需求

Determine the intent:

Add a rule — enable a new rule or change its value
Disable a rule — turn off a rule globally or for specific elements
Adjust scope — change where a rule applies

If unclear, use AskUserQuestion to clarify.

确定用户意图：

添加规则 — 启用新规则或修改规则参数
禁用规则 — 全局关闭规则或针对特定元素关闭规则
调整范围 — 修改规则的适用范围

如果意图不明确，请使用AskUserQuestion工具进行确认。

3. Determine the Scope

3. 确定配置范围

Use AskUserQuestion to confirm the intended scope.

User intent	Scope	Where to configure
"I don't want this rule anywhere"	Project-wide	`rules` in config
"I don't want this in certain files"	File-level	`excludeFiles` or `overrides`
"I don't want this on specific elements"	Element-level	`nodeRules` or `childNodeRules`

Important distinction for file-level scope — ask the user:

excludeFiles
: Markuplint completely ignores the file. VS Code extension won't show warnings either. Use when the file should never be linted.
overrides
with
```
overrideMode: "merge"
```
: Markuplint still processes the file but with different rules. VS Code shows remaining warnings. Use when you want partial coverage.
npm script glob: Only affects CLI/CI runs. VS Code still lints everything. Use when VS Code warnings are acceptable but CI should skip certain files.

使用AskUserQuestion工具确认预期的配置范围。

用户意图	配置范围	配置位置
“我不想在任何地方使用这个规则”	项目全局	配置文件中的 `rules` 字段
“我不想在某些文件中使用这个规则”	文件级	`excludeFiles` 或 `overrides` 字段
“我不想在特定元素上使用这个规则”	元素级	`nodeRules` 或 `childNodeRules` 字段

文件级配置范围的重要区别——请询问用户：

excludeFiles
：Markuplint会完全忽略该文件，VS Code扩展也不会显示任何警告。适用于永远不需要检查的文件。
带
overrideMode: "merge"
的
overrides
：Markuplint仍会处理该文件，但使用不同的规则，VS Code会显示剩余的警告。适用于需要部分检查覆盖的场景。
npm脚本通配符：仅影响CLI/CI运行，VS Code仍会检查所有文件。适用于可以接受VS Code警告但CI需要跳过某些文件的场景。

4. Determine Element-Level Configuration

4. 确定元素级配置

If the scope is element-level, choose between:

nodeRules
— applies to the matched element itself
childNodeRules
— applies to children of the matched element. Add
```
"inheritance": true
```
to affect all descendants, not just direct children.

The AI agent should propose a CSS selector based on the code context. Use the element's class, ID, tag name, or attributes to build the selector.

For rule details, fetch the rule's documentation:

{doc-base}/docs/rules/{rule-id}

(where

{doc-base}

is determined in Step 1)

如果配置范围是元素级，请在以下选项中选择：

nodeRules
— 应用于匹配到的元素本身
childNodeRules
— 应用于匹配到的元素的子元素。添加
```
"inheritance": true
```
可使其影响所有后代元素，而非仅直接子元素。

AI代理应根据代码上下文提出CSS选择器。可使用元素的类名、ID、标签名或属性来构建选择器。

如需规则详情，请获取该规则的文档：

{doc-base}/docs/rules/{rule-id}

（其中

{doc-base}

是步骤1中确定的文档基准地址）

5. Propose the Change

5. 提出配置变更方案

Show the user the exact configuration change before applying.

Always explain:

What the change does
What the trade-off is
If there's a better alternative

Example proposals:

在应用变更前，向用户展示具体的配置变更内容。

务必说明：

该变更的作用
对应的取舍
是否有更优的替代方案

示例方案：

Disable a named rule from a preset

禁用预设中的指定规则

json

{
  "rules": {
    "a11y/specific-rule": false
  }
}

json

{
  "rules": {
    "a11y/specific-rule": false
  }
}

Element-specific rule with nodeRules

使用nodeRules配置元素专属规则

json

{
  "nodeRules": [
    {
      "selector": ".legacy-component",
      "rules": {
        "class-naming": false
      }
    }
  ]
}

json

{
  "nodeRules": [
    {
      "selector": ".legacy-component",
      "rules": {
        "class-naming": false
      }
    }
  ]
}

Descendants of a section with childNodeRules

使用childNodeRules配置区块后代元素规则

json

{
  "childNodeRules": [
    {
      "selector": ".legacy-section",
      "inheritance": true,
      "rules": {
        "wai-aria": false
      }
    }
  ]
}

json

{
  "childNodeRules": [
    {
      "selector": ".legacy-section",
      "inheritance": true,
      "rules": {
        "wai-aria": false
      }
    }
  ]
}

File-level exclusion

文件级排除配置

json

{
  "excludeFiles": ["./src/legacy/**/*"]
}

json

{
  "excludeFiles": ["./src/legacy/**/*"]
}

File-level override

文件级覆盖配置

json

{
  "overrideMode": "merge",
  "overrides": {
    "./src/legacy/**/*": {
      "rules": {
        "character-reference": false
      }
    }
  }
}

json

{
  "overrideMode": "merge",
  "overrides": {
    "./src/legacy/**/*": {
      "rules": {
        "character-reference": false
      }
    }
  }
}

6. Confirm with AskUserQuestion

6. 使用AskUserQuestion工具确认

Never modify the config file without user confirmation.

未经用户确认，请勿修改配置文件。

7. Apply and Verify

7. 应用并验证

Update
```
.markuplintrc
```
using
```
Edit
```
tool
Run lint again on the same target
Report the before/after violation count to confirm the change worked

使用
```
Edit
```
工具更新
```
.markuplintrc
```
文件
在同一目标上重新运行检查
报告变更前后的违规数量，确认变更生效

Quick Reference: Common Configurations

快速参考：常见配置

These are frequently requested. Propose them directly when relevant:

这些是经常被请求的配置，相关场景下可直接提出：

OGP (Open Graph Protocol)

OGP（开放图谱协议）

json

{
  "nodeRules": [
    {
      "selector": "meta[property]",
      "rules": {
        "invalid-attr": {
          "options": {
            "allowAttrs": ["property"]
          }
        }
      }
    }
  ]
}

json

{
  "nodeRules": [
    {
      "selector": "meta[property]",
      "rules": {
        "invalid-attr": {
          "options": {
            "allowAttrs": ["property"]
          }
        }
      }
    }
  ]
}

Allow custom data attributes

允许自定义数据属性

json

{
  "rules": {
    "invalid-attr": {
      "options": {
        "allowAttrs": ["data-testid"]
      }
    }
  }
}

json

{
  "rules": {
    "invalid-attr": {
      "options": {
        "allowAttrs": ["data-testid"]
      }
    }
  }
}

Selector tips

选择器技巧

Ancestor matching: use
```
:is(nav *)
```
(NOT
```
:closest()
```
— it is deprecated)
For selector syntax details:
```
{doc-base}/docs/guides/selectors
```

For all config properties:

{doc-base}/docs/configuration/properties

祖先匹配：使用
```
:is(nav *)
```
（不要用
```
:closest()
```
——该语法已被废弃）
选择器语法详情：
```
{doc-base}/docs/guides/selectors
```

所有配置属性详情：

{doc-base}/docs/configuration/properties