Site Audit

What it checks

site_audit scans your built static site (Astro dist/, Next.js out/, Hugo public/ — anything with HTML files) and reports issues across four groups:

Technical SEO

• Orphan pages (in sitemap, never linked internally)
• Broken internal links and 301-causing missing trailing slashes
• Missing / duplicate / wrong-length titles and meta descriptions
• Missing H1, multiple H1, heading hierarchy skips (H1→H3)
• Canonical conflicts, oversized images, missing alt text and dimensions
• robots.txt sitemap declaration, Open Graph tags, viewport, html lang, favicon

GEO / AI visibility

• llms.txt and llms-full.txt presence and depth
• FAQPage / HowTo schema on Q&A content, commercial pages missing Product/Offer schema
• Content signals in robots.txt (ai-input / search)
• BLUF (conclusion-first) detection, content structure (H2s, lists, tables)
• Crawl blocking (noindex on content, disallow-all)

Agent readiness (v1.4.4)

• llms.txt must carry a When to use section — without it, agents can’t tell which jobs your site fits
• llms.txt needs a how-to-call line (install command / endpoint / MCP entry point)

i18n & performance

• hreflang alternates and x-default fallback
• Page size (crawl budget), staging subdomain leaks, sitemap URL inventory, JSON-LD field validation

Usage

# Basic — point at your build output and sitemap
python3 -m zens_ink.site_audit --dist dist --sitemap dist/sitemap.xml

# JSON report for CI
python3 -m zens_ink.site_audit --dist dist --sitemap dist/sitemap.xml --format json --output audit.json

# Audit one language subtree
python3 -m zens_ink.site_audit --dist dist --sitemap dist/sitemap.xml --base /zh

Reading the report

Issues are grouped by type with severity (error / warning / info) and affected paths. Each group ends with a fix hint. The summary line shows unique-issue counts vs total — deduplicated for quick scanning.

CI integration

Fail the build when errors exceed a threshold:

python3 -m zens_ink.site_audit --dist dist --sitemap dist/sitemap.xml --format json --output audit.json
python3 -c "
import json
r = json.load(open('audit.json'))
errors = [i for i in r['issues'] if i['severity'] == 'error']
exit(1 if len(errors) > 0 else 0)
"