Markuplint: Modern Modular HTML Linter

Technical Deep Dive & Specifications

Why Markuplint Over Traditional Linters?

1. Full Component Framework Support: Integrates directly with JSX, TSX, Vue Single File Components (.vue), Svelte (.svelte), Astro, and template engines (Pug, EJS).
2. WHATWG Permitted Content Engine: Detects illegal element nesting (e.g., <dt> placed outside <dl>, <a> containing <a>, or <button> inside <summary>).
3. Deep ARIA & A11y Verification: Verifies whether an ARIA role is valid on a given native HTML element according to the ARIA in HTML specification.
4. Scoping via nodeRules & childNodeRules: Allows customizing rules for specific DOM subtrees (e.g., relaxing rules inside third-party widgets).

Configuration File (.markuplintrc.json)

{
  "extends": [
    "markuplint:recommended"
  ],
  "parser": {
    "\\.jsx?$": "@markuplint/jsx-parser",
    "\\.tsx?$": "@markuplint/jsx-parser",
    "\\.vue$": "@markuplint/vue-parser",
    "\\.svelte$": "@markuplint/svelte-parser"
  },
  "rules": {
    "wai-aria": true,
    "permitted-contents": true,
    "use-header-level-step": true,
    "invalid-attr": true,
    "required-attr": true,
    "doctype": "always",
    "landmark-roles": true,
    "no-refer-to-non-existent-id": true
  },
  "nodeRules": [
    {
      "selector": ".legacy-widget",
      "rules": {
        "use-header-level-step": false
      }
    }
  ]
}

Key Markuplint Rules Explained

CLI Execution & Scripts

# Install core and framework parsers
npm install --save-dev markuplint @markuplint/jsx-parser @markuplint/vue-parser

# Execute across all frontend source files
npx markuplint "src/**/*.{html,jsx,tsx,vue,svelte}"

💻 Interactive Code Playground

Starter Code (React JSX Component: UserProfile.jsx)

Line-by-Line Code Breakdown

• Line 9: Skipping from <h1> directly to <h4> violates use-header-level-step. Heading levels communicate document hierarchy to screen readers and must increment sequentially (h1 -> h2).
• Lines 12–14: Adding role="article" and aria-checked="true" to a <button> violates wai-aria. A button cannot assume an article landmark role, and aria-checked is only valid on role="checkbox", role="radio", or role="switch".
• Lines 17–21: Placing a <div> directly inside a <ul> violates permitted-contents. The WHATWG specification strictly mandates that <ul> and <ol> may only contain <li>, <script>, or <template> children.
• Lines 24–28: aria-describedby="tooltip-missing-id" violates no-refer-to-non-existent-id because no element with id="tooltip-missing-id" exists in the component.

Expected Terminal Output from Markuplint CLI

// UserProfile.jsx
import React from 'react';

export function UserProfile({ user }) {
  return (
    <article className="user-profile">
      {/* Violation 1: Sequential heading step skipped (h1 -> h4) */}
      <h1>User Profile</h1>
      <h4>Account Overview</h4>

      {/* Violation 2: Invalid ARIA role on interactive button */}
      <button role="article" aria-checked="true">
        View Activity
      </button>

      {/* Violation 3: Permitted content violation (div directly in ul) */}
      <ul className="stats-list">
        <div className="stat-item">
          <span>Reputation: {user.reputation}</span>
        </div>
      </ul>

      {/* Violation 4: aria-describedby references non-existent ID */}
      <input 
        type="text" 
        aria-describedby="tooltip-missing-id" 
        placeholder="Update display name"
      />
    </article>
  );
}

$ npx markuplint "src/UserProfile.jsx"

src/UserProfile.jsx:9:7
  9:7  error  Expected h2, h3, but received h4  use-header-level-step

src/UserProfile.jsx:12:7
  12:7  error  The "article" role cannot be applied to the <button> element  wai-aria
  12:7  error  The "aria-checked" attribute cannot be used on <button> without an appropriate role  wai-aria

src/UserProfile.jsx:17:9
  17:9  error  The <div> element is not allowed in <ul>  permitted-contents

src/UserProfile.jsx:24:7
  24:7  error  Cannot find the element "#tooltip-missing-id" referenced by "aria-describedby"  no-refer-to-non-existent-id

✖ 5 errors