htmlint

Fast HTML linter written in Go with special handling for Go templates. Validates HTML for accessibility, best practices, and common mistakes.

Implements rules from html-validate.org.

Installation

go install github.com/toba/go-html-validate@latest

Usage

# Lint files or directories
htmlint web/
htmlint index.html about.html

# Errors only (no warnings)
htmlint -q web/

# JSON output
htmlint --format=json web/

# Disable specific rules
htmlint --disable=prefer-aria --disable=no-inline-style web/

# Ignore files by pattern
htmlint --ignore="*_test.html" web/

# List available rules
htmlint --list-rules

Options

Flag	Description
-f, --format	Output format: text (default), json
-q, --quiet	Only show errors, suppress warnings
--no-color	Disable colored output
--ignore PATTERN	Glob pattern to ignore (repeatable)
--disable RULE	Disable specific rule (repeatable)
--list-rules	List all available rules
-h, --help	Show help
--config PATH	Use specific config file
--no-config	Disable config file loading
--print-config	Print resolved configuration

Configuration

This tool uses the same configuration format as html-validate.

Config File

Create .htmlvalidate.json in your project root:

{
  "$schema": "https://raw.githubusercontent.com/toba/go-html-validate/main/schemas/htmlint.schema.json",
  "extends": ["html-validate:recommended"],
  "rules": {
    "no-inline-style": "warn",
    "prefer-tbody": "off"
  }
}

The linter searches for .htmlvalidate.json in the target directory and parent directories.

Rule Severity

• "error" or 2 - Error (fails CI)
• "warn" or 1 - Warning
• "off" or 0 - Disabled

Framework Support

htmx

Enable htmx attribute validation:

{
  "frameworks": {
    "htmx": true,
    "htmx-version": "2"
  }
}

Option	Values	Description
htmx	true/false	Enable htmx attribute support (default: false)
htmx-version	"2", "4"	htmx version to validate against (default: "2")
htmx-custom-events	["event1", ...]	Custom event names to allow in hx-on:* without warnings

When htmx is enabled, htmx attributes are recognized as valid and won't trigger attribute-misuse errors. Additionally, the htmx-attributes rule will validate htmx attribute values.

Custom events: If you use custom events (e.g., SSE-pushed events), hx-on:myevent will produce an "unknown event" warning by default. Add event names to htmx-custom-events to suppress these warnings:

{
  "frameworks": {
    "htmx": true,
    "htmx-custom-events": ["count", "notification", "status"]
  }
}

Event names are matched case-insensitively.

Supported attributes (htmx 2.x):

• Request: hx-get, hx-post, hx-put, hx-patch, hx-delete
• Targeting: hx-target, hx-swap, hx-swap-oob, hx-select, hx-select-oob
• Behavior: hx-trigger, hx-sync, hx-boost, hx-confirm, hx-prompt
• URLs: hx-push-url, hx-replace-url
• Data: hx-vals, hx-headers, hx-params, hx-include, hx-encoding
• Inheritance: hx-disinherit, hx-inherit
• Other: hx-ext, hx-indicator, hx-preserve, hx-validate, hx-disable, hx-disabled-elt, hx-history, hx-history-elt, hx-request
• Events: hx-on:* patterns (e.g., hx-on:click, hx-on:htmx:after-request)

htmx 4-only attributes (warn when htmx-version is "2"):

• hx-action, hx-config, hx-ignore, hx-method, hx-optimistic, hx-preload
• hx-status:* patterns (e.g., hx-status:404)
• :inherited suffix (e.g., hx-boost:inherited)

Deprecated in htmx 4 (warn when htmx-version is "4"):

• hx-disabled-elt, hx-disinherit, hx-history-elt, hx-request, hx-vars

Go Templates

Go template syntax is validated automatically when linting .gohtml, .tmpl, or any file containing {{ template delimiters. The following template-specific rules are enabled by default:

Rule	Description
template-syntax-valid	Validates balanced {{ and }} braces, matched control structures (if/end, range/end, etc.), and proper trim marker syntax ({{- and -}})
template-whitespace-trim	Suggests using trailing trim markers (-}}) on control flow actions alone on a line to prevent unwanted blank lines in rendered output

These rules examine the raw template content before preprocessing, allowing them to catch syntax errors that would otherwise cause parser failures.

To disable template rules:

{
  "rules": {
    "template-syntax-valid": "off",
    "template-whitespace-trim": "off"
  }
}

Built-in Presets

Preset	Description
html-validate:recommended	All rules enabled (default)
html-validate:standard	Core rules, fewer style preferences
html-validate:a11y	Accessibility-focused rules only

Ignore File

Create .htmlvalidateignore for gitignore-style patterns:

node_modules/
vendor/
**/*.generated.html

For full configuration options, see the html-validate configuration documentation.

Supported File Types

• .html
• .htm
• .gohtml
• .tmpl

Rule Categories

Accessibility (WCAG)

• area-alt - <area> elements must have alt text
• aria-hidden-body - <body> must not have aria-hidden
• aria-label-misuse - aria-label only on interactive elements
• button-name - Buttons must have accessible names
• heading-content - Headings must have text content
• heading-level - Heading levels must not be skipped
• hidden-focusable - Hidden elements must not be focusable
• img-alt - Images must have alt attributes
• input-label - Form inputs must have labels
• link-name - Links must have accessible names
• meta-refresh - Avoid meta refresh redirects
• multiple-labeled-controls - Labels must reference single controls
• no-abstract-role - No abstract ARIA roles
• no-autoplay - Avoid autoplay on media
• no-redundant-role - No redundant ARIA roles
• prefer-native-element - Prefer native HTML over ARIA
• require-lang - <html> must have lang attribute
• svg-focusable - SVGs must have focusable="false"
• tabindex - Avoid positive tabindex values
• unique-landmark - Landmark regions must be unique

Validation

• attribute-allowed-values - Valid attribute values
• attribute-misuse - Attributes used correctly
• doctype - Document must have DOCTYPE
• duplicate-id - IDs must be unique
• element-name - Valid element names
• element-permitted-content - Valid child elements
• element-permitted-occurrences - Element count limits
• element-permitted-order - Correct element order
• element-permitted-parent - Valid parent elements
• element-required-ancestor - Required ancestor elements
• element-required-attributes - Required attributes present
• element-required-content - Required child content
• no-dup-attr - No duplicate attributes
• no-dup-class - No duplicate classes
• valid-autocomplete - Valid autocomplete values
• valid-id - Valid ID syntax
• void-content - Void elements have no content

Deprecated

• deprecated - No deprecated elements
• no-deprecated-attr - No deprecated attributes
• no-conditional-comment - No IE conditional comments

Best Practices

• button-type - Buttons should have explicit type
• empty-title - Title elements must not be empty
• form-dup-name - Unique form control names
• form-submit - Forms should have submit buttons
• long-title - Avoid overly long titles
• map-dup-name - Unique map names
• map-id-name - Map id and name should match
• no-implicit-input-type - Explicit input types
• no-missing-references - Valid ID references
• no-multiple-main - Single main element
• no-redundant-for - No redundant label for
• no-utf8-bom - No UTF-8 BOM
• prefer-aria - Use ARIA attributes
• prefer-button - Prefer button over input
• prefer-semantic - Use semantic elements
• prefer-tbody - Tables should have tbody
• script-element - Valid script elements
• script-type - Valid script types
• tel-non-breaking - Tel links with proper spacing

Security

• allowed-links - Validate link protocols
• no-inline-style - Avoid inline styles
• no-style-tag - Avoid style tags
• require-csp-nonce - CSP nonce on scripts/styles
• require-sri - Subresource integrity

htmx (requires frameworks.htmx: true)

• htmx-attributes - Validates htmx attribute values (hx-swap, hx-trigger, hx-target, hx-on:, hx-vals, hx-headers, hx-include, hx-status:)

Go Template

• template-syntax-valid - Validates Go template syntax (balanced braces, control structures, trim markers)
• template-whitespace-trim - Suggests trim markers to prevent unwanted whitespace

License

MIT - See LICENSE for details.

Rule specifications derived from html-validate (MIT License).