markuplint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markuplint

Reference knowledge for working with Markuplint.

Markuplint使用参考知识库。

What is Markuplint

什么是Markuplint

An HTML linter that checks conformance with HTML Standard, WAI-ARIA, and project-specific rules. Supports JSX, Vue, Svelte, Astro, Pug, PHP, and more via parser plugins.

Official site: https://markuplint.dev
GitHub: https://github.com/markuplint/markuplint
Playground: https://playground.markuplint.dev

一款HTML代码检查工具，可检查代码是否符合HTML标准、WAI-ARIA规范及项目自定义规则。通过解析器插件支持JSX、Vue、Svelte、Astro、Pug、PHP等多种语法。

官方网站：https://markuplint.dev
GitHub：https://github.com/markuplint/markuplint
在线 playground：https://playground.markuplint.dev

Reading Violation Messages

违规信息解读

Format:

message (ruleId) [named-rule]

The attribute name is duplicated (attr-duplication) [html-standard/attr-duplication]

ruleId
(
```
attr-duplication
```
) — the base rule. Always present.
named-rule
(
```
html-standard/attr-duplication
```
) — preset-defined alias. Present only for named rules. The
```
namespace/
```
prefix indicates which preset defined it (e.g.,
```
a11y/
```
,
```
html-standard/
```
,
```
performance/
```
).
severity
—
```
error
```
(exit code 1),
```
warning
```
(exit code 0 by default), or
```
info
```
.

To look up any rule:

https://markuplint.dev/docs/rules/{ruleId}

格式：

message (ruleId) [named-rule]

The attribute name is duplicated (attr-duplication) [html-standard/attr-duplication]

ruleId
（
```
attr-duplication
```
）——基础规则，始终存在。
named-rule
（
```
html-standard/attr-duplication
```
）——预设规则的别名，仅在命名规则中存在。
```
namespace/
```
前缀表示该规则来自哪个预设（例如
```
a11y/
```
、
```
html-standard/
```
、
```
performance/
```
）。
severity
——严重程度，包括
```
error
```
（退出码1）、
```
warning
```
（默认退出码0）或
```
info
```
。

查询规则详情请访问：

https://markuplint.dev/docs/rules/{ruleId}

CLI Quick Reference

CLI快速参考

shell

undefined

shell

undefined

Basic lint

npx markuplint "src/**/*.html"

JSON output (for programmatic use)

npx markuplint "src/**/*.html" --format JSON

Auto-fix (rules that support it)

npx markuplint "src/**/*.html" --fix

Preview fixes without writing

npx markuplint "src/**/*.html" --fix-dry-run

Suppress current violations for gradual adoption

npx markuplint "src/**/*.html" --suppress

Clean up fixed suppressions

npx markuplint "src/**/*.html" --prune-suppressions

GitHub Actions annotations

npx markuplint "src/**/*.html" --format GitHub

Limit output for large projects

npx markuplint "src/**/*.html" --max-count=50


Always quote glob patterns to prevent shell expansion.

npx markuplint "src/**/*.html" --max-count=50


请始终为通配符模式添加引号，避免shell自动展开。

Config Patterns

配置模式

Disable a named rule

禁用命名规则

json

{ "rules": { "a11y/html-lang": false } }

json

{ "rules": { "a11y/html-lang": false } }

Disable all rules in a namespace

禁用命名空间下的所有规则

json

{ "rules": { "a11y/*": false } }

json

{ "rules": { "a11y/*": false } }

Change severity

修改严重程度

json

{ "rules": { "a11y/html-lang": "warning" } }

json

{ "rules": { "a11y/html-lang": "warning" } }

Element-specific rules

元素特定规则

nodeRules

— targets the matched element.

childNodeRules

— targets descendants (add

"inheritance": true

for all descendants, not just direct children).

nodeRules

——针对匹配到的元素生效。

childNodeRules

——针对子元素生效（添加

"inheritance": true

可作用于所有后代元素，而非仅直接子元素）。

Ancestor matching

祖先元素匹配

Use

:is(selector *)

. Do NOT use

:closest()

— it is deprecated.

json

{ "selector": "div:is(nav *)" }

使用

:is(selector *)

。请勿使用

:closest()

——该语法已被废弃。

json

{ "selector": "div:is(nav *)" }

Common Issues and Fixes

常见问题及解决方法

OGP / Open Graph

property

attribute

OGP/Open Graph

property

属性

The

property

attribute is not in the HTML spec. See: https://markuplint.dev/docs/rules/invalid-attr#the-open-graph-protocol

property

属性不属于HTML规范。详情请见：https://markuplint.dev/docs/rules/invalid-attr#the-open-graph-protocol

invalid-attr

with frameworks

框架中的

invalid-attr

问题

Install the framework's spec plugin (e.g.,

@markuplint/react-spec

). See: https://markuplint.dev/docs/guides/beyond-html#why-need-the-spec-plugins

安装对应框架的规范插件（例如

@markuplint/react-spec

）。详情请见：https://markuplint.dev/docs/guides/beyond-html#why-need-the-spec-plugins

character-reference

false positives with template engines

模板引擎中的

character-reference

误报

Some template syntaxes trigger false positives. Disable partially or report: https://markuplint.dev/docs/rules/character-reference

部分模板语法会触发误报。可部分禁用该规则或提交问题反馈：https://markuplint.dev/docs/rules/character-reference

--init

is interactive only

--init

仅支持交互式操作

npx markuplint --init

requires terminal input. AI agents should write

.markuplintrc

directly.

npx markuplint --init

需要终端输入。AI Agent应直接编写

.markuplintrc

配置文件。

Documentation URLs

文档链接

Topic	URL
All rules	`https://markuplint.dev/docs/rules`
Specific rule	`https://markuplint.dev/docs/rules/{rule-id}`
Presets	`https://markuplint.dev/docs/guides/presets`
Framework setup	`https://markuplint.dev/docs/guides/beyond-html`
Config properties	`https://markuplint.dev/docs/configuration/properties`
Selectors	`https://markuplint.dev/docs/guides/selectors`
CLI options	`https://markuplint.dev/docs/guides/cli`
FAQ	`https://markuplint.dev/docs/guides/faq`
Migration (v4→v5)	`https://markuplint.dev/docs/migration/v4-to-v5`

Use

WebFetch

on these URLs when you need current details.

主题	链接
所有规则	`https://markuplint.dev/docs/rules`
特定规则	`https://markuplint.dev/docs/rules/{rule-id}`
预设规则	`https://markuplint.dev/docs/guides/presets`
框架配置	`https://markuplint.dev/docs/guides/beyond-html`
配置属性	`https://markuplint.dev/docs/configuration/properties`
选择器	`https://markuplint.dev/docs/guides/selectors`
CLI选项	`https://markuplint.dev/docs/guides/cli`
常见问题	`https://markuplint.dev/docs/guides/faq`
版本迁移（v4→v5）	`https://markuplint.dev/docs/migration/v4-to-v5`

如需获取最新详情，可通过

WebFetch

访问上述链接。

markuplint

Original

Translation

Markuplint

Markuplint

What is Markuplint

什么是Markuplint

Reading Violation Messages

违规信息解读

CLI Quick Reference

CLI快速参考

Basic lint

Basic lint

JSON output (for programmatic use)

JSON output (for programmatic use)

Auto-fix (rules that support it)

Auto-fix (rules that support it)

Preview fixes without writing

Preview fixes without writing

Suppress current violations for gradual adoption

Suppress current violations for gradual adoption

Clean up fixed suppressions

Clean up fixed suppressions

GitHub Actions annotations

GitHub Actions annotations

Limit output for large projects

Limit output for large projects

Config Patterns

配置模式

Disable a named rule

禁用命名规则

Disable all rules in a namespace

禁用命名空间下的所有规则

Change severity

修改严重程度

Element-specific rules

元素特定规则

Ancestor matching

祖先元素匹配

Common Issues and Fixes

常见问题及解决方法

OGP / Open Graph property attribute

OGP/Open Graph property属性

invalid-attr with frameworks

框架中的invalid-attr问题

character-reference false positives with template engines

模板引擎中的character-reference误报

--init is interactive only

--init仅支持交互式操作

Documentation URLs

文档链接

OGP / Open Graph
`property`
attribute

OGP/Open Graph
`property`
属性

`invalid-attr`
with frameworks

框架中的
`invalid-attr`
问题

`character-reference`
false positives with template engines

模板引擎中的
`character-reference`
误报

`--init`
is interactive only

`--init`
仅支持交互式操作