markuplint-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

markuplint-setup

Markuplint 搭建指南

Set up Markuplint in a project from scratch.

从零开始在项目中搭建Markuplint。

When to Use

使用场景

"Set up markuplint" / "Add markuplint to this project"
"I want to lint my HTML"
"Install markuplint"

"搭建Markuplint" / "为当前项目添加Markuplint"
"我想要检查我的HTML代码"
"安装Markuplint"

Steps

步骤

1. Check Existing Installation

1. 检查现有安装情况

Check
```
package.json
```
for
```
markuplint
```
and
```
@markuplint/*
```
packages
Check for config files (
```
.markuplintrc*
```
,
```
markuplint.config.*
```
)
If already installed, tell the user and suggest
```
/markuplint-configure
```
instead

检查
```
package.json
```
中是否包含
```
markuplint
```
及
```
@markuplint/*
```
包
检查是否存在配置文件（
```
.markuplintrc*
```
、
```
markuplint.config.*
```
）
如果已安装，告知用户并建议使用
```
/markuplint-configure
```
进行配置

2. Detect Project Type

2. 检测项目类型

Scan the project:

Package manager: check for

package-lock.json

yarn.lock

pnpm-lock.yaml

Framework: check
```
package.json
```
dependencies for
```
react
```
,
```
vue
```
,
```
svelte
```
,
```
astro
```
,
```
@alpinejs/csp
```
, etc. Also check file extensions (
```
.jsx
```
,
```
.tsx
```
,
```
.vue
```
,
```
.svelte
```
,
```
.astro
```
,
```
.pug
```
,
```
.php
```
)

Monorepo: check for

workspaces

package.json

lerna.json

nx.json

turbo.json

扫描项目：

包管理器：检查是否存在

package-lock.json

yarn.lock

pnpm-lock.yaml

框架：检查
```
package.json
```
的依赖项中是否包含
```
react
```
、
```
vue
```
、
```
svelte
```
、
```
astro
```
、
```
@alpinejs/csp
```
等，同时检查文件扩展名（
```
.jsx
```
、
```
.tsx
```
、
```
.vue
```
、
```
.svelte
```
、
```
.astro
```
、
```
.pug
```
、
```
.php
```
）
单仓库多项目（Monorepo）：检查
```
package.json
```
中的
```
workspaces
```
字段，或是否存在
```
lerna.json
```
/
```
nx.json
```
/
```
turbo.json
```
文件

3. Choose Preset and Packages

3. 选择预设与包

Use

WebFetch

to get the latest supported syntaxes and preset information:

Presets: fetch https://markuplint.dev/docs/guides/presets
Framework parsers: fetch https://markuplint.dev/docs/guides/beyond-html

Use AskUserQuestion to confirm:

Detected framework — is it correct?
Which preset to use? (recommend based on framework)

使用

WebFetch

获取最新的支持语法和预设信息：

预设：获取 https://markuplint.dev/docs/guides/presets
框架解析器：获取 https://markuplint.dev/docs/guides/beyond-html

使用AskUserQuestion确认以下内容：

检测到的框架是否正确？
使用哪个预设？（根据框架给出推荐）

4. Install Packages

4. 安装包

Install using the detected package manager. Example:

shell

npm install -D markuplint @markuplint/jsx-parser @markuplint/react-spec

Do NOT use
npx markuplint --init
— it requires interactive terminal input.

使用检测到的包管理器进行安装。示例：

shell

npm install -D markuplint @markuplint/jsx-parser @markuplint/react-spec

请勿使用
npx markuplint --init
——该命令需要交互式终端输入。

5. Create Configuration File

5. 创建配置文件

Write

.markuplintrc

directly. Keep it minimal — only include what's needed for the detected framework.

Static HTML needs no

parser

specs

json

{
  "extends": ["markuplint:recommended"]
}

Framework projects need parser and spec:

json

{
  "extends": ["markuplint:recommended-react"],
  "parser": {
    "\\.[jt]sx$": "@markuplint/jsx-parser"
  },
  "specs": {
    "\\.[jt]sx$": "@markuplint/react-spec"
  }
}

Refer to https://markuplint.dev/docs/guides/beyond-html for the exact parser/spec package names and file patterns for each framework.

直接编写

.markuplintrc

文件。保持配置精简——仅包含检测到的框架所需的内容。

静态HTML无需配置

parser

或

specs

：

json

{
  "extends": ["markuplint:recommended"]
}

框架项目需要配置解析器和规范：

json

{
  "extends": ["markuplint:recommended-react"],
  "parser": {
    "\\.[jt]sx$": "@markuplint/jsx-parser"
  },
  "specs": {
    "\\.[jt]sx$": "@markuplint/react-spec"
  }
}

如需了解各框架对应的解析器/规范包名称及文件匹配模式，请参考 https://markuplint.dev/docs/guides/beyond-html。

When to use JavaScript/TypeScript config

何时使用JavaScript/TypeScript配置

If the project uses external config plugins or shared configs that require fine-grained merging, recommend

markuplint.config.ts

(or

.js

) with spread syntax — similar to ESLint's flat config pattern:

import type { Config } from '@markuplint/ml-config';
import reactConfig from '@example/markuplint-config-react';

const config: Config = {
  ...reactConfig,
  rules: {
    ...reactConfig.rules,
    'class-naming': '/^[a-z][a-z0-9-]*$/',
  },
};

export default config;

This gives full control over merge order and avoids the limitations of JSON

extends

(which uses a fixed merge strategy). Use JSON for simple setups; use JS/TS when composing multiple configs.

如果项目使用需要精细合并的外部配置插件或共享配置，建议使用扩展语法的

markuplint.config.ts

（或

.js

）——类似于ESLint的扁平配置模式：

import type { Config } from '@markuplint/ml-config';
import reactConfig from '@example/markuplint-config-react';

const config: Config = {
  ...reactConfig,
  rules: {
    ...reactConfig.rules,
    'class-naming': '/^[a-z][a-z0-9-]*$/',
  },
};

export default config;

这种方式可以完全控制合并顺序，避免JSON

extends

的局限性（其使用固定的合并策略）。简单场景使用JSON配置；组合多个配置时使用JS/TS配置。

6. Run Initial Lint

6. 运行初始代码检查

Run Markuplint and capture the results:

shell

npx markuplint "$ARGUMENTS" --format JSON

$ARGUMENTS

is empty, ask the user for the target glob (e.g.,

"src/**/*.html"

Summarize:

Total violation count
Breakdown by rule (which rules have the most violations)
Whether violations are concentrated in specific files/directories

运行Markuplint并捕获结果：

shell

npx markuplint "$ARGUMENTS" --format JSON

如果

$ARGUMENTS

为空，请询问用户目标文件匹配模式（例如：

"src/**/*.html"

）。

总结内容：

违规总数
按规则分类统计（哪些规则违规最多）
违规是否集中在特定文件/目录

7. Rule-by-Rule Adoption Decision

7. 逐条规则适配决策

Use AskUserQuestion for each rule that has violations. Present rules one at a time (or batch related rules).

For each rule, explain what it checks (fetch the rule page if needed:

https://markuplint.dev/docs/rules/{rule-id}

) and offer options:

Keep as error — fix all violations now
Downgrade to warning — keep but don't block CI
Bulk suppress — record current violations, enforce only on new code
Disable — turn off the rule

When to recommend Bulk Suppressions:

Many violations in legacy code that won't be touched soon
The rule is valuable for new code

When to recommend disabling:

The rule doesn't fit the project's architecture or conventions
The rule conflicts with a template engine being used

对每个存在违规的规则使用AskUserQuestion。逐条展示规则（或批量展示相关规则）。

对于每条规则，说明其检查内容（必要时获取规则页面：

https://markuplint.dev/docs/rules/{rule-id}

），并提供以下选项：

保留为错误——立即修复所有违规
降级为警告——保留规则但不阻止CI流程
批量抑制——记录当前违规，仅对新代码强制执行规则
禁用——关闭该规则

何时推荐批量抑制：

遗留代码中存在大量违规，且短期内不会修改这些代码
该规则对新代码有价值

何时推荐禁用：

该规则不符合项目的架构或约定
该规则与项目使用的模板引擎冲突

8. Apply Decisions

8. 应用决策

Update
```
.markuplintrc
```
with disabled/warning rules
If Bulk Suppressions were chosen, run:
```
npx markuplint "$TARGET" --suppress
```
Tell the user to commit
```
markuplint-suppressions.json
```

在
```
.markuplintrc
```
中更新禁用/设为警告的规则
如果选择了批量抑制，运行命令：
```
npx markuplint "$TARGET" --suppress
```
告知用户提交
```
markuplint-suppressions.json
```
文件

9. Add npm Script

9. 添加npm脚本

Add a lint script to

package.json

json

{
  "scripts": {
    "lint:html": "markuplint \"src/**/*.html\""
  }
}

Adjust the glob to match the project's source files and framework extensions.

在

package.json

中添加代码检查脚本：

json

{
  "scripts": {
    "lint:html": "markuplint \"src/**/*.html\""
  }
}

调整文件匹配模式以匹配项目的源文件和框架扩展名。