DOCSEARCHbyAlgolia
Submit Docs

markuplint Documentation

website·Indexed 33 days ago

https://next.markuplint.dev/

Documentation for markuplint, a tool for linting HTML. It includes a comprehensive list of built-in rules categorized by Syntax, Structure, Attributes, Forms, Accessibility, Style, Maintainability, and Browser Compatibility, with details on rule IDs, fixability, and configuration options.

Tokens
63.7K
Snippets
396
Records
486
Agent score
53%

What's inside markuplint

  1. Overview of the markuplint:a11y preset checks

    The markuplint:a11y preset validates the following accessibility criteria:

    • WAI-ARIA conformance: Validates role and aria-* attributes.
    • Accessible names: Ensures elements requiring names (form controls, images, landmarks) have them.
    • Landmark structure: Checks for top-level landmarks like banner, main, complementary, and contentinfo.
    • Heading structure: Verifies the presence of <h1> and ensures heading levels are not skipped.
    • Label associations: Ensures <label> elements are correctly linked to controls.
    • Media accessibility: Checks for <track> elements in <audio> and <video> tags.
    • Interactive content: Checks for restricted tabindex, autoplay constraints, and the absence of accesskey.

  2. Validate HTML content models with permitted-contents

    The permitted-contents rule ensures that child elements and text nodes are allowed by their parent's content model according to the HTML Living Standard. It triggers an error when:

    1. A child element or text node is not permitted by the parent.
    2. An element requiring non-empty text content (e.g., <title> or <option> without a label) is empty or contains only whitespace.

    Note: This rule is distinct from no-disallowed-ancestor (forbidden ancestors), require-ancestor (missing required ancestors), and no-duplicate-sibling-attr (repeated sibling-unique attributes).

    <!-- ❌ Incorrect: <div> is not allowed inside <ul> -->
<ul>
  <div>Not allowed DIV element</div>
</ul>

<!-- ✅ Correct: <li> is allowed inside <ul> -->
<ul>
  <li>List item</li>
</ul>

  3. Prevent unknown attributes with no-unknown-attr

    The no-unknown-attr rule warns if an attribute is used that is not defined by the HTML Living Standard or a custom rule. It includes a "Did you mean...?" suggestion for typos.

    Note: This rule only checks if the attribute name exists. For attributes that exist but are disallowed in a specific context, use no-disallowed-attr. For invalid values on known attributes, use no-invalid-attr-value.

    <!-- ❌ Incorrect: unexist-attr is not a valid HTML attribute -->
<div unexist-attr></div>

<!-- ✅ Correct -->
<div></div>

  4. Enforce required attributes with the `require-attr` rule

    The require-attr rule warns when specified attributes or attributes required by the HTML Living Standard (via @markuplint/html-spec) are missing from an element.

    Note: This rule does not evaluate elements using spread attributes (e.g., <img {...props}>) because the final attributes cannot be determined statically.

    <!-- Incorrect: missing src (required by spec) -->
<img />

<!-- Correct -->
<img src="/path/to/image.png" />

  5. Enforce consistent attribute order with attr-order

    The attr-order rule ensures that attributes on HTML elements follow a consistent sequence. By default, attributes are sorted alphabetically. This rule is not included in any preset as attribute order is a project-specific style preference. It supports auto-fixing via the --fix CLI option.
    <!-- ❌ Incorrect: style before class and id -->
<div style="color: red" class="foo" id="bar"></div>

<!-- ✅ Correct: sorted alphabetically (or by config) -->
<div class="foo" id="bar" style="color: red"></div>

  6. Prevent non-standard HTML features with no-nonstandard-features

    The no-nonstandard-features rule warns about elements and attributes marked as non-standard in the HTML specification data bundled with markuplint. This rule was split from the former no-unsupported-features rule's checkNonStandard option; enabling this rule is equivalent to setting checkNonStandard: true in the old version. The default severity for this rule is warning.
    <!-- ❌ Incorrect: uses non-standard attribute -->
<canvas moz-opaque></canvas>

<!-- ✅ Correct -->
<canvas></canvas>

  7. Enforce BEM-style class naming and nesting constraints

    To enforce a BEM (Block Element Modifier) architecture where elements must belong to their parent block and cannot be nested inside elements of a different block, use the class-naming rule in combination with childNodeRules and regexSelector.

    This configuration ensures:

    1. Block names start with an uppercase letter followed by lowercase letters or numbers.
    2. Element names follow the block name with two underscores (__) and consist of lowercase letters or numbers.
    3. Elements are not children of a block or element they do not belong to.
    {
  "rules": {
    "class-naming": "/^[A-Z][a-z0-9]+$/"
  },
  "childNodeRules": [
    {
      "regexSelector": {
        "attrName": "class",
        "attrValue":
          // Capture a block name
          "/^(?<BlockName>[A-Z][a-z0-9]+)(?:__[a-z][a-z0-9-]+)?$/"
      },
      "rules": {
        "class-naming": {
          "value": [
            // Expand a block name by Mustache format
            "/^{{BlockName}}__[a-z][a-z0-9-]+$/",
            "/^([A-Z][a-z0-9]+)$/"
          ]
        }
      }
    }
  ]
}

  8. Prevent use of HTML features unsupported by target browsers

    The no-unsupported-browser-features rule warns when HTML elements or attributes are used that are not supported by the project's target browsers. It uses browserslist for target definitions and @mdn/browser-compat-data for compatibility checks.

    Important: If the project lacks a browserslist configuration, this rule will not perform any checks (no-op).

  9. Prevent obsolete DOCTYPE declarations with no-obsolete-doctype

    The no-obsolete-doctype rule warns when a document declares an obsolete DOCTYPE. This includes any DOCTYPE with a public identifier or a system identifier, except for the specific legacy-string exception <!DOCTYPE html SYSTEM "about:legacy-compat"> permitted by the HTML Living Standard for compatibility with old parsers. Note that this rule does not check for missing DOCTYPES; that is handled by the require-doctype rule.
    <!-- ✅ Correct -->
<!doctype html>

<!-- ✅ Correct (Legacy exception) -->
<!DOCTYPE html SYSTEM "about:legacy-compat">

<!-- ❌ Incorrect -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

  10. Prevent use of experimental HTML features with no-experimental-features

    The no-experimental-features rule warns about elements and attributes marked as experimental in the HTML specification data bundled with markuplint. This rule is an explicit opt-in and is not included in any default preset. It was split from the former no-unsupported-features rule's checkExperimental option.

    Note: The reporting of a feature depends on the version of the HTML specification data bundled with the current version of markuplint.

    <!-- ❌ Incorrect: using an experimental attribute -->
<iframe credentialless></iframe>

<!-- ✅ Correct: using standard attributes -->
<iframe></iframe>

  11. Enforce element order in the HTML <head> with head-element-order

    The head-element-order rule warns when elements within the <head> section are not in the expected order. The order is determined by an array of CSS selectors; elements are sorted based on the position of their first matching selector. Elements that do not match any provided selector are placed at the end, preserving their original relative source order. This rule supports auto-fixing via the --fix CLI option.
    <!-- ❌ Incorrect: title before charset -->
<head>
  <title>Title</title>
  <meta charset="UTF-8">
</head>

<!-- ✅ Correct: charset before title -->
<head>
  <meta charset="UTF-8">
  <title>Title</title>
</head>

  12. Prevent invalid attribute values with no-invalid-attr-value

    The no-invalid-attr-value rule warns when an attribute's value does not match the type or pattern required by the HTML Living Standard or a custom configuration. It only validates attributes that are already accepted by no-unknown-attr and no-disallowed-attr.

    Note: Dynamic values (template-interpolated) or spread attributes are not evaluated because their content is unknown at lint time.

    <!-- ❌ Incorrect: tabindex must be an integer -->
<button tabindex="non-integer">The Button</button>

<!-- ❌ Incorrect: referrerpolicy has an invalid value -->
<a href="/" referrerpolicy="invalid-value">The Anchor</a>

<!-- ✅ Correct -->
<button tabindex="0">The Button</button>
<a href="/" referrerpolicy="no-referrer">The Anchor</a>