go-html-validate

command module
v0.9.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 18, 2026 License: MIT Imports: 11 Imported by: 0

README

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.

[!NOTE] 🤖 This project was initially set up with a carefully guided LLM (Claude Opus 4.5)

Installation

go install github.com/STR-Consulting/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/STR-Consulting/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")

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.

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

Documentation

Overview

htmlint is an HTML accessibility linter for Go templates.

Usage: 

htmlint [options] <files or directories>

Options: 

-f, --format     Output format: text, json (default: text)
-q, --quiet      Only show errors, not warnings
--no-color       Disable colored output
--ignore         Glob patterns to ignore (can be repeated)
--disable        Disable specific rules (can be repeated)
--config         Path to config file
--no-config      Disable config file loading
--print-config   Print resolved configuration and exit
-h, --help       Show help

Examples: 

htmlint web/
htmlint -q web/**/*.html
htmlint --format=json web/ > lint-results.json

Source Files

View all Source files

Directories

Path Synopsis
Package config handles .htmlvalidate.json configuration file loading.
 Package config handles .htmlvalidate.json configuration file loading.
Package linter provides the core HTML linting orchestration.
 Package linter provides the core HTML linting orchestration.
Package parser provides HTML parsing with Go template syntax support.
 Package parser provides HTML parsing with Go template syntax support.
Package reporter provides output formatting for lint results.
 Package reporter provides output formatting for lint results.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.