htmlhint · coliff · Jun 2, 2025 · Jun 2, 2025 · Jun 2, 2025
@@ -14,3 +14,6 @@
 - All user-facing messages and documentation should use clear, concise US English.
 - Keep dependencies up to date and avoid unnecessary packages.
 - All website content should be placed in the website directory and follow Astro Starlight conventions.
+- Rules in the rules directory should always be documented in the website/src/content/docs/rules directory.
+- Rules in src/core/core.ts should be listed alphabetically.
+- Use the provided code snippets as examples for rule documentation.
@@ -22,6 +22,7 @@ export { default as inlineScriptDisabled } from './inline-script-disabled'
 export { default as inlineStyleDisabled } from './inline-style-disabled'
 export { default as inputRequiresLabel } from './input-requires-label'
 export { default as mainRequire } from './main-require'
+export { default as metaDescriptionRequire } from './meta-description-require'
 export { default as scriptDisabled } from './script-disabled'
 export { default as spaceTabMixedDisabled } from './space-tab-mixed-disabled'
 export { default as specCharEscape } from './spec-char-escape'

@@ -0,0 +1,54 @@
+import { Block, Listener } from '../htmlparser'
+import { Rule } from '../types'
+
+export default {
+  id: 'meta-description-require',
+  description:
+    '<meta name="description"> with non-blank content must be present in <head> tag.',
+  init(parser, reporter) {
+    let headSeen = false
+    let metaDescriptionSeen = false
+    let metaDescriptionContent = ''
+    let headEvent: Block | null = null
+
+    const onTagStart: Listener = (event) => {
+      const tagName = event.tagName.toLowerCase()
+      if (tagName === 'head') {
+        headSeen = true
+        headEvent = event
+      } else if (tagName === 'meta') {
+        const mapAttrs = parser.getMapAttrs(event.attrs)
+        if (
+          mapAttrs['name'] &&
+          mapAttrs['name'].toLowerCase() === 'description'
+        ) {
+          metaDescriptionSeen = true
+          metaDescriptionContent = mapAttrs['content'] || ''
+        }
+      }
+    }
+
+    parser.addListener('tagstart', onTagStart)
+    parser.addListener('end', () => {
+      if (headSeen && headEvent) {
+        if (!metaDescriptionSeen) {
+          reporter.error(
+            '<meta name="description"> must be present in <head> tag.',
+            headEvent.line,
+            headEvent.col,
+            this,
+            headEvent.raw
+          )
+        } else if (metaDescriptionContent.trim() === '') {
+          reporter.error(
+            '<meta name="description"> content attribute must not be empty.',
+            headEvent.line,
+            headEvent.col,
+            this,
+            headEvent.raw
+          )
+        }
+      }
+    })
+  },
+} as Rule
@@ -0,0 +1,37 @@
+const HTMLHint = require('../../dist/htmlhint.js').HTMLHint
+const ruleId = 'meta-description-require'
+
+describe('Rule: meta-description-require', () => {
+  it('should not report an error when a valid meta description is present', () => {
+    const code = `<!DOCTYPE html><html><head><meta name="description" content="A description."></head><body></body></html>`
+    const messages = HTMLHint.verify(code, { [ruleId]: true })
+    expect(messages.length).toBe(0)
+  })
+
+  it('should report an error when meta description is missing', () => {
+    const code = `<!DOCTYPE html><html><head></head><body></body></html>`
+    const messages = HTMLHint.verify(code, { [ruleId]: true })
+    expect(messages.length).toBe(1)
+    expect(messages[0].message).toBe(
+      '<meta name="description"> must be present in <head> tag.'
+    )
+  })
+
+  it('should report an error when meta description content is blank', () => {
+    const code = `<!DOCTYPE html><html><head><meta name="description" content=" "></head><body></body></html>`
+    const messages = HTMLHint.verify(code, { [ruleId]: true })
+    expect(messages.length).toBe(1)
+    expect(messages[0].message).toBe(
+      '<meta name="description"> content attribute must not be empty.'
+    )
+  })
+
+  it('should not report an error for other meta tags', () => {
+    const code = `<!DOCTYPE html><html><head><meta name="viewport" content="width=device-width, initial-scale=1"></head><body></body></html>`
+    const messages = HTMLHint.verify(code, { [ruleId]: true })
+    expect(messages.length).toBe(1)
+    expect(messages[0].message).toBe(
+      '<meta name="description"> must be present in <head> tag.'
+    )
+  })
+})
@@ -7,6 +7,8 @@ import { Badge } from '@astrojs/starlight/components'
 
 ## 1.3.0 _(2025-05-31)_
 
+- <Badge text="Feat" size="small" /> New rule: [`meta-description-require`](/rules/meta-description-require/)
+  [#1615](https://github.com/htmlhint/HTMLHint/issues/1615)
 - <Badge text="Feat" size="small" /> New rule: [`main-require`](/rules/main-require/)
   [#1608](https://github.com/htmlhint/HTMLHint/issues/1608)
 - <Badge text="Feat" size="small" /> New rule: [`h1-require`](/rules/h1-require/)

@@ -13,6 +13,7 @@ description: A complete list of all the rules for HTMLHint
 - [`style-disabled`](/docs/user-guide/rules/style-disabled): `<style>` tags cannot be used.
 - [`script-disabled`](/docs/user-guide/rules/script-disabled): `<script>` tags cannot be used.
 - [`title-require`](/docs/user-guide/rules/title-require): `<title>` must be present in `<head>` tag.
+- [`meta-description-require`](/docs/user-guide/rules/meta-description-require): `<meta name="description">` with non-blank content must be present in `<head>` tag.
 
 ## Attributes
 

@@ -12,6 +12,7 @@ description: A complete list of all the rules for HTMLHint
 - [`style-disabled`](style-disabled/): `<style>` tags cannot be used.
 - [`script-disabled`](script-disabled/): `<script>` tags cannot be used.
 - [`title-require`](title-require/): `<title>` must be present in `<head>` tag.
+- [`meta-description-require`](meta-description-require/): `<meta name="description">` with non-blank content must be present in `<head>` tag.
 
 ## Attributes
 

@@ -0,0 +1,40 @@
+---
+id: meta-description-require
+title: meta-description-require
+description: Ensures every HTML document includes a non-blank meta description tag within the head element for better SEO.
+sidebar:
+  hidden: true
+  badge: New
+---
+import { Badge } from '@astrojs/starlight/components';
+
+A `<meta name="description">` with non-blank content must be present in `<head>` tag.
+
+Level: <Badge text="Error" variant="danger" />
+
+## Config value
+
+1. true: enable rule
+2. false: disable rule
+
+### The following patterns are **not** considered rule violations:
+
+```html
+<html><head><meta name="description" content="A description of the page"></head></html>
+```
+
+### The following patterns are considered rule violations:
+
+```html
+<!-- Missing meta description -->
+<html><head></head></html>
+
+<!-- Empty meta description content -->
+<html><head><meta name="description" content=""></head></html>
+
+<!-- Whitespace-only meta description content -->
+<html><head><meta name="description" content=" "></head></html>
+
+<!-- Meta description outside head tag -->
+<html><meta name="description" content="A description"><head></head></html>
+```