Back to Details

markuplint

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Markuplint

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

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

Basic lint

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

JSON output (for programmatic use)

JSON output (for programmatic use)

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

Auto-fix (rules that support it)

Auto-fix (rules that support it)

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

Preview fixes without writing

Preview fixes without writing

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

Suppress current violations for gradual adoption

Suppress current violations for gradual adoption

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

Clean up fixed suppressions

Clean up fixed suppressions

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

GitHub Actions annotations

GitHub Actions annotations

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

Limit output for large projects

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

文档链接

TopicURL
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
访问上述链接。