Heading Keywords SEO Rule

Check that target keywords appear naturally in headings without keyword stuffing

What This Rule Checks

Checks if configured target keywords appear in the H1 tag and other headings. Reports missing keywords and detects keyword stuffing when density exceeds 30% in headings.

Why It Matters for SEO & GEO

Including target keywords in headings reinforces topical relevance for search engines. However, over-optimization through keyword stuffing can trigger penalties.

How to Fix

Include your primary keyword in the H1 tag naturally. Distribute secondary keywords across H2 and H3 headings. Keep keyword density below 30% in heading text.

Examples

Bad

<h1>SEO SEO SEO Tips SEO Guide SEO</h1>

Good

<h1>Essential SEO Tips for Small Business Websites</h1>

How VibeLinter Checks Heading Keywords

VibeLinter’s headings/keywords rule performs these checks when target keywords are configured:

Primary keyword in H1 — Checks if the first configured keyword appears in the H1 heading text (case-insensitive)
Missing keywords — Reports keywords that do not appear in any heading across the page
Keyword density analysis — Calculates keyword density across all heading text and warns when it exceeds 30%
Skip when unconfigured — The rule skips all checks when no target keywords are provided in the configuration

Configuration

// vibelinter.config.cjs
module.exports = {
  rules: {
    'headings/keywords': {
      enabled: true,
      severity: 'info',
      checkKeywordPresence: true,
      keywords: ['seo', 'optimization', 'web performance']
    }
  }
}

SEO Impact

Strategic keyword placement in headings affects:

Topical relevance — Keywords in headings signal content relevance to search engines
Ranking potential — H1 keyword presence correlates with higher rankings for target queries
Over-optimization risk — Excessive keyword repetition can trigger algorithmic penalties
GEO (Generative Engine Optimization) — AI models analyze heading keywords to determine content topics; natural keyword usage helps your content appear in relevant AI-generated answers without being flagged as spam