HTMLHint Configuration & Rules

Technical Deep Dive & Specifications

How HTMLHint Operates

HTMLHint is written entirely in JavaScript. Unlike heavy browser-engine validators, it uses a lightweight, high-performance HTML parser that scans tokens linearly. This makes it ideal for real-time editor feedback and fast pre-commit hooks.

The Complete .htmlhintrc Rule Matrix

{
  "doctype-first": true,
  "doctype-html5": true,
  "tag-pair": true,
  "tag-self-close": false,
  "tagname-lowercase": true,
  "attr-lowercase": true,
  "attr-value-double-quotes": true,
  "attr-value-not-empty": false,
  "attr-no-duplication": true,
  "id-unique": true,
  "src-not-empty": true,
  "title-require": true,
  "alt-require": true,
  "spec-char-escape": true,
  "id-class-value": "dash",
  "style-disabled": false,
  "inline-style-disabled": true,
  "inline-script-disabled": true,
  "space-tab-mixed-disabled": "space",
  "id-class-ad-disabled": true,
  "href-abs-or-rel": false,
  "attr-unsafe-chars": true,
  "head-script-disabled": false
}

Deep Dive into Essential Rules

Authoring Custom HTMLHint Rules

When your organization has custom markup constraints (for example: Every external link must include rel="noopener noreferrer"), you can write custom rules using HTMLHint.addRule().

// custom-rules/require-rel-noopener.mjs
import { HTMLHint } from 'htmlhint';

HTMLHint.addRule({
  id: 'custom-external-rel-noopener',
  description: 'External links with target="_blank" must include rel="noopener noreferrer".',
  link: 'https://internal-docs.company.com/security/external-links',
  init(parser, reporter) {
    parser.addListener('tagstart', (event) => {
      const tagName = event.tagName.toLowerCase();
      if (tagName !== 'a') return;

      const attrs = event.attrs;
      const targetAttr = attrs.find(attr => attr.name.toLowerCase() === 'target');
      const relAttr = attrs.find(attr => attr.name.toLowerCase() === 'rel');

      if (targetAttr && targetAttr.value === '_blank') {
        if (!relAttr || !relAttr.value.includes('noopener')) {
          reporter.error(
            'Anchor tag targeting _blank is missing rel="noopener noreferrer".',
            event.line,
            event.col,
            this,
            event.raw
          );
        }
      }
    });
  }
});

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 9: <HEADER> uses uppercase tag characters, violating tagname-lowercase: true.
• Line 11: onclick="logoutUser()" uses an inline JavaScript event handler, violating inline-script-disabled: true.
• Line 16: style="margin-top: 20px;" uses an inline CSS declaration, violating inline-style-disabled: true.
• Line 18: <img src="..."> is missing an alt attribute, violating alt-require: true.
• Line 21: class="userProfileCard" uses camelCase when the policy enforces id-class-value: "dash".
• Line 23: class='status-text' uses single quotes instead of double quotes, and the <p> tag is unclosed, violating attr-value-double-quotes and tag-pair.

Expected Terminal Output from HTMLHint CLI

$ npx htmlhint "index.html" --config .htmlhintrc

index.html:
  line 9, col 3: The tag name of [ <HEADER> ] must be in lowercase. [tagname-lowercase]
  line 11, col 13: Inline script [ onclick="logoutUser()" ] cannot be used. [inline-script-disabled]
  line 16, col 16: Inline style [ style="margin-top: 20px;" ] cannot be used. [inline-style-disabled]
  line 18, col 7: An alt attribute must be present on <img> elements. [alt-require]
  line 21, col 12: The value of attribute [ class="userProfileCard" ] must be in dash format. [id-class-value]
  line 23, col 10: The value of attribute [ class='status-text' ] must be in double quotes. [attr-value-double-quotes]
  line 23, col 7: Tag must be paired, no start tag: [ </section> ] on line 24. [tag-pair]

Scanned 1 file, found 7 errors in 1 file.