OpenParable
Skip to content
← Back to skills

Markuplint

Testing & Quality
markuplint

Markuplint is an Agent Skill for testing & quality published in the markuplint/markuplint repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Reference knowledge for Markuplint HTML linter. Covers violation interpretation, CLI usage, config patterns, and documentation URLs. Auto-loaded when working with HTML linting.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/markuplint/markuplint/blob/HEAD/skills/markuplint/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/markuplint, 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

Reference knowledge for working with Markuplint.

What is 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.

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}

CLI Quick Reference

# 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.

Config Patterns

Disable a named rule

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

Disable all rules in a namespace

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

Change severity

{ "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).

Ancestor matching

Use :is(selector *). Do NOT use :closest() — it is deprecated.

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

Common Issues and Fixes

OGP / Open Graph property attribute

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

invalid-attr with frameworks

Install the framework's spec plugin (e.g., @markuplint/react-spec). See: https://markuplint.dev/docs/guides/beyond-html#why-need-the-spec-plugins

character-reference false positives with template engines

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

--init is interactive only

npx markuplint --init requires terminal input. AI agents should write .markuplintrc directly.

Documentation URLs

TopicURL
All ruleshttps://markuplint.dev/docs/rules
Specific rulehttps://markuplint.dev/docs/rules/{rule-id}
Presetshttps://markuplint.dev/docs/guides/presets
Framework setuphttps://markuplint.dev/docs/guides/beyond-html
Config propertieshttps://markuplint.dev/docs/configuration/properties
Selectorshttps://markuplint.dev/docs/guides/selectors
CLI optionshttps://markuplint.dev/docs/guides/cli
FAQhttps://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.