PagePreflight — Check the Page Before It Goes Live

A free, local HTML and SEO preflight checker for AI agents.

PagePreflight helps you find objective HTML, metadata, structured-data, and page-structure problems before publishing. It reports exact line numbers, severity levels, evidence, and suggested fixes. Your AI agent can then fix clearly safe issues and run the audit again to verify the results.

No API key. No network requests. No ranking-score claims.

✨ What It Checks

SEO Metadata

• Missing or mismatched title, meta description, canonical, Open Graph, and Twitter metadata
• Canonical URL versus og:url inconsistencies
• Social sharing image metadata problems
• Optional focus-keyword checks

HTML Structure

• Missing or duplicate H1 headings
• Heading structure issues
• Duplicate HTML IDs
• Broken in-page anchor targets
• Unclosed and stray closing tags
• Nested forms and duplicate content blocks
• Repeated HTML comments and placeholder content

Images and Links

• Images missing an alt attribute
• Links opening in a new tab without appropriate rel attributes
• Mixed-content references using insecure HTTP
• Empty links and other supported link-structure issues

Structured Data

• Invalid JSON-LD syntax
• Schema properties that need review
• FAQ questions or answers that do not match visible page content
• Breadcrumb paths and positions that conflict with your rules
• Missing VideoObject data for detected YouTube embeds

Your Own Website Rules

Create a JSON configuration to define requirements such as:

• Maximum title length
• Meta description length
• Minimum word count
• Minimum internal and external links
• Required schema types
• Forbidden HTML elements
• Required or forbidden text patterns
• Breadcrumb requirements

Unknown configuration keys produce an error rather than silently changing the audit rules.

🚀 How It Works

1. Audit: Run the local Python checker against an HTML file or folder.
2. Inspect: Review FAIL, WARN, and INFO findings with line numbers and suggested fixes.
3. Fix: Ask your AI agent to correct clearly safe problems while preserving your content and design.
4. Recheck: Run the audit again and compare the before-and-after results.
5. Review: Confirm unresolved issues that require factual information, editorial decisions, or human judgment.

PagePreflight does not silently rewrite your content, invent missing information, or disable checks to make a report look better.

💻 Quick Start

Audit a single HTML file:

python3 pagepreflight.py page.html

Check a focus keyword:

python3 pagepreflight.py page.html --keyword "free regex tester"

Use your own website rules:

python3 pagepreflight.py page.html \
  --keyword "free regex tester" \
  --config examples/house-rules.example.json

Audit every HTML file in a folder:

python3 pagepreflight.py ./site-folder

Export machine-readable JSON:

python3 pagepreflight.py page.html --json

Show checks that passed or were skipped:

python3 pagepreflight.py page.html --verbose

Treat warnings as failures for stricter automation:

python3 pagepreflight.py page.html --strict

The checker uses Python's standard library. The optional development tools have additional dependencies, but the core audit script does not.

📊 Example Results

The package includes a deliberately broken HTML page and its sample audit report.

Sample audit summary

These numbers come from the included test fixture, not a live website or a benchmark. Your results will vary according to the page and configuration.

Examples of issues detected

• Canonical URL and Open Graph URL do not match
• Two H1 headings appear on the page
• An image has no alt attribute
• An in-page link points to a missing anchor
• An HTML ID is duplicated
• A FAQ question in structured data is not visible on the page
• Breadcrumbs conflict with configured website rules
• A repeated header block may be present
• Placeholder text and TODO markers remain
• An element is left unclosed

Every finding includes a check identifier and supporting context, with line numbers where applicable.

🛡️ Built for Reliable, Cautious Auditing

PagePreflight follows several important safeguards:

• Local checking: The Python script makes no network requests.
• No API key required: The checker uses Python's standard library.
• No automatic file modification by the checker: The script analyzes files and reports findings; your agent handles any requested edits.
• Evidence-first reports: Findings include check IDs, relevant locations, and suggested fixes.
• No invented content: Missing dates, authors, image descriptions, FAQ answers, and other facts must be supplied or verified.
• Untrusted content stays data: Instructions embedded in an audited webpage are not treated as commands.
• Minimal changes: Fixes should preserve the page's wording, design, and structure wherever possible.
• Honest verification: Re-run the audit and report remaining issues instead of claiming success without evidence.

🧩 What's Included

The downloadable package contains:

• SKILL.md — Agent instructions, workflow, safety rules, and fix guidance
• pagepreflight.py — The standalone HTML and SEO checker
• tests/test_pagepreflight.py — 82 offline unit tests
• examples/good-page.html — A clean example page
• examples/broken-page.html — A page seeded with known defects
• examples/injection-page.html — An example containing untrusted instructions
• examples/broken-page.report.txt — A sample audit report
• examples/house-rules.example.json — A starter configuration
• Additional GenialThings-specific example rules
• dev/ — Optional parser comparison, fuzzing, and mutation-testing utilities

🎯 Who Is It For?

• SEO professionals auditing HTML pages
• WordPress site owners reviewing exported HTML or local templates
• Content publishers checking pages before launch
• Developers reviewing page structure and metadata
• Digital marketing agencies applying consistent website rules
• AI agents that need a repeatable, machine-readable preflight checklist

⚠️ Important Limitations

PagePreflight is a defined checklist, not a complete SEO testing platform.

It does not:

• Calculate Rank Math, Yoast, or other SEO plugin scores
• Guarantee rankings, traffic, indexing, or AI citations
• Execute JavaScript or render dynamic pages
• See content injected by a CMS theme when it is absent from the supplied HTML
• Open URLs or verify whether external links are reachable
• Validate every possible HTML, schema, or SEO issue
• Determine whether your content is factually accurate or commercially effective

A clean report means the supported checks did not flag a problem. It does not prove the page is perfect.

🔒 Privacy Notes

The checker itself makes no network requests and stores no audit history. However, the AI runtime may read files when carrying out requested edits, and its provider's data-retention policies are outside PagePreflight's control.

Do not submit files containing passwords, API keys, or other secrets. Review the runtime's privacy policy before auditing confidential drafts.

✅ Get Started

Download PagePreflight, select an HTML file or folder, and run the checks before publishing.

Find the problems. Fix what is safe. Run the checks again. Publish with greater confidence.

PagePreflight is a technical preflight checklist, not a guarantee of SEO performance.