Website H1-H6 Heading Checker

Check the heading structure of any web page or whole site. The actor reads every H1 to H6 tag, scores each page from 0 to 100, names the exact problems it found and tells you how to fix them.

Run it on a single URL, or crawl up to 50 internal pages and get a site-wide summary on top of the per-page detail.

What you get

For every page: the full list of headings by level, their order on the page, a 0–100 structure score, the issues found and a recommendation per issue.

For the whole site: heading totals and averages, the share of pages missing an H1 or carrying several, the count of issues by severity, and every issue grouped by type with the pages concerned.

Output goes to the dataset and to the key-value store under the OUTPUT key.

What it detects

Issue	Severity	Meaning
missing H1	critical	The page has no H1 at all
multiple H1 tags	critical	More than one H1 on the same page
heading hierarchy skipped levels	critical	A level is jumped, e.g. H2 straight to H4
too many consecutive same level headings	warning	A long run of same-level headings with no sub-structure
heading text too short	warning	Under 10 characters
heading text too long	warning	Over 100 characters
H1 identical to page title	info	The H1 repeats the <title> word for word

The 0–100 score is built from four things: whether a single H1 is present, how consistent the hierarchy is, the length and quality of the heading text, and the depth of H2/H3 use. The letter grade is given once for the site, in domain.analysis_summary.average_score_grade, and follows the site average: A from 90, B from 80, C from 70, D from 60, F below. Individual pages get a number, not a letter.

Input

Field	Type	Default	What it does
startUrl	string	—	Page to analyze, or the page the crawl starts from. Required.
crawlUrls	boolean	false	Follow internal links instead of analyzing a single page
maxPages	integer	2	Pages to analyze when crawling, up to 50. Ignored when crawlUrls is false
includeHeadingText	boolean	true	Return the text of each heading
includeHeadingStructure	boolean	true	Return the ordered headingStructure array
includeHeadingScore	boolean	true	Compute scores, issues and recommendations
userAgent	string	own UA	User agent sent with each request
timeout	integer	10000	Request timeout in milliseconds, 1000 to 30000
maxRedirects	integer	5	Redirects followed per page, 0 to 10

Single page:

{ "startUrl": "https://example.com/" }

Whole site, 20 pages:

{ "startUrl": "https://example.com/", "crawlUrls": true, "maxPages": 20 }

Output

Trimmed extract of a real run on a 3-page crawl:

{
  "domain": {
    "domain_name": "https://www.smashingmagazine.com",
    "total_pages_analyzed": 3,
    "total_headings": 104,
    "total_h1": 1,
    "total_h2": 54,
    "total_h3": 43,
    "total_h4": 6,
    "average_headings_per_page": 35,
    "average_heading_score": 60,
    "pages_with_h1": 1,
    "pages_with_h1_percentage": 33,
    "pages_with_no_h1": 2,
    "pages_with_multiple_h1": 0,
    "pages_with_good_structure": 1,
    "total_heading_issues": 7,
    "critical_issues": 4,
    "warning_issues": 3,
    "info_issues": 0,
    "issues_by_type": {
      "missing H1": [
        { "issue": "missing H1", "page": "https://www.smashingmagazine.com/", "severity": "critical" }
      ]
    },
    "analysis_summary": {
      "has_heading_issues": true,
      "needs_h1_improvement": true,
      "has_good_structure": true,
      "average_score_grade": "D"
    }
  },
  "pages": [
    {
      "url": "https://www.smashingmagazine.com/",
      "analyzed": true,
      "pageStatusCode": 200,
      "pageTitle": "Smashing Magazine — For Web Designers And Developers",
      "h1": [],
      "h2": ["New EU Guidelines For AI Labelling", "Accessible Front-End Components"],
      "h3": ["Front-End Boilerplates & Starter Kits"],
      "h1Count": 0,
      "h2Count": 22,
      "h3Count": 1,
      "totalHeadings": 27,
      "headingStructure": [
        { "tag": "h2", "level": 2, "text": "New EU Guidelines For AI Labelling", "position": 1, "length": 34, "wordCount": 6 }
      ],
      "headingScore": 45,
      "headingIssues": ["missing H1", "heading hierarchy skipped levels"],
      "headingRecommendations": [
        "Add a single H1 tag to each page for better SEO",
        "Improve heading structure and hierarchy for better SEO"
      ],
      "analysis_date": "2026-08-14T05:36:00.771Z",
      "data_source": "msd_headings"
    }
  ],
  "failed_pages": [],
  "analysis": {
    "total_pages_processed": 3,
    "total_pages_failed": 0,
    "analysis_completed_at": "2026-08-14T05:36:01.682Z",
    "headings_engine_version": "1.1.0",
    "data_format_version": "1.0"
  }
}

h4, h5, h6 and their counts are always present, empty when the page has none.

Pages that cannot be read

A page hit by a transient network error (DNS, reset connection, timeout) is tried up to three times, then listed in failed_pages with its reason. It is excluded from the statistics, so a network problem never shows up as "0 headings, grade F". If no page at all could be read, the run fails instead of returning an empty report.

Limits

• Static HTML only. Headings injected client-side by JavaScript are not seen.
• The crawl follows internal links from startUrl and stops at maxPages, capped at 50. It is not a full site crawler and does not read your sitemap.
• Scores and grades come from the rules listed above. They are a structure check, not a ranking prediction.
• Heading length thresholds (10 and 100 characters) are fixed and not configurable.

Typical uses

Auditing heading structure before a redesign or a migration, checking that a new template outputs one H1 and a clean hierarchy, and screening a batch of pages for missing or duplicate H1s.

Support

Open an issue on this actor's page and we will look at the run you report.