htmlhint · coliff · Jun 22, 2025 · Jun 22, 2025 · Jun 22, 2025 · Jun 22, 2025
@@ -0,0 +1,65 @@
+# Custom Rules Examples
+
+This directory contains example custom rules for HTMLHint to demonstrate how to create and use custom rules.
+
+## Example Rule
+
+The `example-rule.js` file demonstrates a custom rule that:
+
+1. Checks if images have either a `title` or `alt` attribute for accessibility
+2. Validates class names against a configurable pattern
+
+## Usage
+
+### Loading the Example Rule
+
+```shell
+# Load the example rule
+npx htmlhint --rulesdir ./examples/custom-rules/example-rule.js test.html
+```
+
+### Configuration
+
+You can configure the example rule in your `.htmlhintrc` file:
+
+```json
+{
+  "example-rule": {
+    "classPattern": "^[a-z][a-z0-9-]*$"
+  }
+}
+```
+
+Or via command line:
+
+```shell
+npx htmlhint --rulesdir ./examples/custom-rules/ --rules "example-rule:{classPattern:'^[a-z][a-z0-9-]*$'}" test.html
+```
+
+### Testing
+
+Create a test HTML file to see the rule in action:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <title>Test</title>
+</head>
+<body>
+  <!-- This will trigger a warning -->
+  <img src="image.jpg">
+
+  <!-- This will trigger a warning if classPattern is set -->
+  <div class="InvalidClass">Content</div>
+
+  <!-- This should not trigger warnings -->
+  <img src="image.jpg" alt="Description">
+  <div class="valid-class">Content</div>
+</body>
+</html>
+```
+
+## Creating Your Own Rules
+
+See the [Custom Rules documentation](https://htmlhint.com/docs/usage/custom-rules/) for detailed information on creating custom rules.
@@ -0,0 +1,47 @@
+/**
+ * Example custom rule for HTMLHint
+ * This rule demonstrates how to create a custom rule that checks for specific patterns
+ */
+
+module.exports = function (HTMLHint) {
+  HTMLHint.addRule({
+    id: 'example-rule',
+    description: 'Example custom rule that demonstrates custom rule creation',
+    init: function (parser, reporter, options) {
+      // Listen for start tags - Note: Use arrow functions for event listeners
+      parser.addListener('tagstart', (event) => {
+        const tagName = event.tagName.toLowerCase()
+        const mapAttrs = parser.getMapAttrs(event.attrs)
+
+        // Example: Check if elements have a title attribute when they should
+        if (tagName === 'img' && !mapAttrs.title && !mapAttrs.alt) {
+          reporter.warn(
+            'Images should have either a title or alt attribute for accessibility',
+            event.line,
+            event.col,
+            this,
+            event.raw
+          )
+        }
+
+        // Example: Check for specific class naming convention
+        if (mapAttrs.class && options && options.classPattern) {
+          const classPattern = new RegExp(options.classPattern)
+          const classes = mapAttrs.class.split(/\s+/)
+
+          for (const className of classes) {
+            if (!classPattern.test(className)) {
+              reporter.warn(
+                `Class "${className}" does not match the required pattern: ${options.classPattern}`,
+                event.line,
+                event.col,
+                this,
+                event.raw
+              )
+            }
+          }
+        }
+      })
+    },
+  })
+}
@@ -40,7 +40,15 @@ Set all of the rules available
 
 ### `--rulesdir, -R`
 
-Load custom rules from file or folder
+Load custom rules from file or folder. See the [custom rules documentation](/usage/custom-rules/) for detailed information on creating and using custom rules.
+
+```shell
+# Load a single custom rule file
+npx htmlhint --rulesdir ./my-custom-rule.js index.html
+
+# Load all custom rules from a directory
+npx htmlhint --rulesdir ./custom-rules/ index.html
+```
 
 ### `--version, -V`