Markuplint Setup
Developmentmarkuplint-setupMarkuplint Setup is an Agent Skill for development published in the markuplint/markuplint repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Set up Markuplint in a project from scratch. Detects framework, creates config, runs initial lint, and guides the user through rule adoption with Bulk Suppressions support.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/markuplint/markuplint/blob/HEAD/skills/markuplint-setup/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/markuplint-setup, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
markuplint-setup
Set up Markuplint in a project from scratch.
When to Use
- "Set up markuplint" / "Add markuplint to this project"
- "I want to lint my HTML"
- "Install markuplint"
Steps
1. Check Existing Installation
- Check
package.jsonformarkuplintand@markuplint/*packages - Check for config files (
.markuplintrc*,markuplint.config.*) - If already installed, tell the user and suggest
/markuplint-configureinstead
2. Detect Project Type
Scan the project:
- Package manager: check for
package-lock.json/yarn.lock/pnpm-lock.yaml - Framework: check
package.jsondependencies forreact,vue,svelte,astro,@alpinejs/csp, etc. Also check file extensions (.jsx,.tsx,.vue,.svelte,.astro,.pug,.php) - Monorepo: check for
workspacesinpackage.jsonorlerna.json/nx.json/turbo.json
3. Choose Preset and Packages
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)
4. Install Packages
Install using the detected package manager. Example:
npm install -D markuplint @markuplint/jsx-parser @markuplint/react-spec
Do NOT use npx markuplint --init — it requires interactive terminal input.
5. Create Configuration File
Write .markuplintrc directly. Keep it minimal — only include what's needed for the detected framework.
Static HTML needs no parser or specs:
{
"extends": ["markuplint:recommended"]
}
Framework projects need parser and spec:
{
"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.
When to use JavaScript/TypeScript config
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.
6. Run Initial Lint
Run Markuplint and capture the results:
npx markuplint "$ARGUMENTS" --format JSON
If $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
7. Rule-by-Rule Adoption Decision
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
8. Apply Decisions
- Update
.markuplintrcwith disabled/warning rules - If Bulk Suppressions were chosen, run:
npx markuplint "$TARGET" --suppress - Tell the user to commit
markuplint-suppressions.json
9. Add npm Script
Add a lint script to package.json:
{
"scripts": {
"lint:html": "markuplint \"src/**/*.html\""
}
}
Adjust the glob to match the project's source files and framework extensions.