Primary HTML validation functionality for analyzing HTML content against configurable rulesets with comprehensive issue detection and reporting.
Main singleton instance providing core HTMLHint functionality including verification, rule management, and message formatting.
/**
* Interface that all HTMLHint rules must implement
*/
interface Rule {
id: string;
description: string;
link?: string;
init(parser: HTMLParser, reporter: Reporter, options: unknown): void;
}
/**
* Configuration object defining which rules to apply and their options
*/
interface Ruleset {
[ruleId: string]: unknown;
}
/**
* Represents a validation issue found during HTML analysis
*/
interface Hint {
type: ReportType;
message: string;
raw: string;
evidence: string;
line: number;
col: number;
rule: {
id: string;
description: string;
link: string;
};
}
/**
* Formatting options for message display
*/
interface FormatOptions {
colors?: boolean;
indent?: number;
}
/**
* Severity levels for validation issues
*/
enum ReportType {
error = "error",
warning = "warning",
info = "info"
}
/**
* Main HTMLHint singleton instance for HTML validation
*/
declare const HTMLHint: HTMLHintCore;
class HTMLHintCore {
/** Map of all registered validation rules */
rules: { [id: string]: Rule };
/** Default ruleset applied when no custom ruleset is provided */
readonly defaultRuleset: Ruleset;
/**
* Validate HTML content against specified ruleset
* @param html - HTML content to validate
* @param ruleset - Optional ruleset configuration, defaults to defaultRuleset
* @returns Array of validation hints/issues found
*/
verify(html: string, ruleset?: Ruleset): Hint[];
/**
* Register a new validation rule
* @param rule - Rule instance to register
*/
addRule(rule: Rule): void;
/**
* Format validation messages for display
* @param arrMessages - Array of hint messages to format
* @param options - Formatting options for colors and indentation
* @returns Array of formatted message strings
*/
format(arrMessages: Hint[], options?: FormatOptions): string[];
}Core verification functionality that parses HTML and applies validation rules.
/**
* Validate HTML content against specified ruleset
* @param html - HTML content to validate (supports inline rule configuration)
* @param ruleset - Optional ruleset configuration
* @returns Array of validation hints found during analysis
*/
HTMLHint.verify(html: string, ruleset?: Ruleset): Hint[];Usage Examples:
import { HTMLHint } from "htmlhint";
// Basic validation with default rules
const html = '<div><p>Hello world</div>';
const hints = HTMLHint.verify(html);
// Custom ruleset
const customRules = {
'tagname-lowercase': true,
'tag-pair': true,
'attr-value-double-quotes': false
};
const customHints = HTMLHint.verify(html, customRules);
// Inline rule configuration in HTML
const htmlWithInlineRules = `
<!-- htmlhint tag-pair:false,id-unique:true -->
<html>
<div id="test">
<div id="test">Duplicate ID allowed due to inline config</div>
</div>
</html>`;
const inlineHints = HTMLHint.verify(htmlWithInlineRules);Register custom validation rules to extend HTMLHint's capabilities.
/**
* Register a new validation rule with HTMLHint
* @param rule - Custom rule implementation
*/
HTMLHint.addRule(rule: Rule): void;Usage Examples:
import { HTMLHint } from "htmlhint";
// Define custom rule
const customRule = {
id: 'custom-no-empty-title',
description: 'Title element should not be empty',
init(parser, reporter, options) {
parser.addListener('tagstart', (event) => {
if (event.tagName === 'title') {
// Rule logic here
parser.addListener('text', (textEvent) => {
if (!textEvent.raw.trim()) {
reporter.error(
'Title element should not be empty',
event.line,
event.col,
this,
event.raw
);
}
});
}
});
}
};
// Register the custom rule
HTMLHint.addRule(customRule);
// Use the custom rule
const ruleset = { 'custom-no-empty-title': true };
const hints = HTMLHint.verify('<title></title>', ruleset);Format validation messages for human-readable display with color support and indentation.
/**
* Format validation messages for display
* @param arrMessages - Array of hint messages to format
* @param options - Formatting options
* @returns Array of formatted message strings ready for display
*/
HTMLHint.format(arrMessages: Hint[], options?: FormatOptions): string[];
interface FormatOptions {
/** Enable colored output for terminal display */
colors?: boolean;
/** Indentation level for nested display */
indent?: number;
}Usage Examples:
import { HTMLHint } from "htmlhint";
const html = '<div><p>Unclosed paragraph</div>';
const hints = HTMLHint.verify(html);
// Format with colors for terminal
const coloredOutput = HTMLHint.format(hints, { colors: true });
console.log(coloredOutput.join('\n'));
// Format with indentation
const indentedOutput = HTMLHint.format(hints, { indent: 2 });
console.log(indentedOutput.join('\n'));
// Plain formatting
const plainOutput = HTMLHint.format(hints);
plainOutput.forEach(line => console.log(line));HTMLHint includes a carefully curated default ruleset covering essential HTML validation rules.
/**
* Default ruleset applied when no custom ruleset is specified
*/
readonly defaultRuleset: Ruleset = {
'tagname-lowercase': true,
'attr-lowercase': true,
'attr-value-double-quotes': true,
'doctype-first': true,
'tag-pair': true,
'spec-char-escape': true,
'id-unique': true,
'src-not-empty': true,
'attr-no-duplication': true,
'title-require': true
};The default ruleset ensures basic HTML compliance and common best practices are enforced when no specific configuration is provided.
HTMLHint supports inline rule configuration within HTML comments at the beginning of documents:
<!-- htmlhint tag-pair:false,id-class-value:underline,attr-lowercase:true -->
<html>
<head><title>Document with inline config</title></head>
<body>
<div ID="MainContent">Mixed case ID allowed</div>
</body>
</html>The inline configuration overrides any ruleset passed to the
verifyHTMLHint gracefully handles various edge cases:
When errors occur during parsing or rule execution, HTMLHint continues processing and reports what it can analyze, ensuring partial validation results are still useful.