┌─────────────────────────────────────────────────────────────────┐
│██████╗ █████╗ ██████╗ ██╗ ██╗███████╗███████╗███████╗ ██████╗ │
│██╔══██╗██╔══██╗██╔══██╗██║ ██╔╝╚══███╔╝██╔════╝██╔════╝██╔═══██╗│
│██║ ██║███████║██████╔╝█████╔╝ ███╔╝ ███████╗█████╗ ██║ ██║│
│██║ ██║██╔══██║██╔══██╗██╔═██╗ ███╔╝ ╚════██║██╔══╝ ██║ ██║│
│██████╔╝██║ ██║██║ ██║██║ ██╗███████╗███████║███████╗╚██████╔╝│
│╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚══════╝╚══════╝ ╚═════╝ │
├─────────────────────────────────────────────────────────────────┤
│ Static Codebase Auditor for 2026 Search Standards │
│ SEO · GEO · AIO · AEO — 16 Checks, Zero APIs, Pure Analysis │
└─────────────────────────────────────────────────────────────────┘
A lightweight, local-only Python library and CLI for auditing sites and content packages against 2026 Search Standards . No external APIs required.
Versioned machine contract: run site or content audits through Python or clean JSON stdin/stdout with stable rule IDs and schema version 1.0.
Content-package audits: evaluate platform-ready titles, descriptions, transcripts, sections, brands, and verified sources without scanning private application dashboards.
Integration controls: use --output, --quiet, --exclude, and --fail-on for local tools, CI, and advisory agent workflows.
Windows reliability: machine mode suppresses the Unicode banner, while normal console output now handles Windows encoding safely.
Release safety: automated Linux/Windows tests, verified source/wheel builds, corrected project metadata, and an explicit MIT license.
16 Automated Checks across 4 categories
Zero API Dependencies - runs entirely offline
Color-Coded Console Output for quick severity identification
JSON Report Export for CI/CD integration
Versioned Machine API over Python or clean JSON stdin/stdout
Site and Content Modes for HTML codebases or platform-ready media metadata
Template Agnostic - works with HTML, JSX, Vue, Svelte, Astro, PHP, EJS, and more
pip install -r requirements.txt
# Basic scan
python darkzseo.py --path ./src
# With brand name (for entity salience check)
python darkzseo.py --path ./public --brand " MyCompany"
# Custom output file
python darkzseo.py --path ./templates --output results.json
# Quiet mode (report files only)
python darkzseo.py --path ./src --quiet
# Machine-readable content audit (no report files or banner)
echo ' {"id":"video-1","platform":"youtube","brand":"MyCompany","title":"MyCompany guide","description":"Useful summary","transcript":"..."}' | python darkzseo.py --mode content --input-json - --json-stdout --no-html --fail-on none
# Ignore private/admin paths and fail only on critical findings
python darkzseo.py --path ./src --exclude admin --exclude " *.fixture.html" --fail-on critical
from darkzseo import audit_content , audit_path
site_report = audit_path ('./public' , brand = 'MyCompany' , excludes = ['admin' ])
content_report = audit_content ({
'id' : 'video-1' ,
'platform' : 'youtube' ,
'brand' : 'MyCompany' ,
'title' : 'MyCompany guide' ,
'description' : 'A useful summary.' ,
'transcript' : 'The complete transcript.' ,
'sections' : [{'title' : 'What does it do?' , 'content' : 'A concise answer.' }],
'sources' : [{'url' : 'https://example.gov/source' }]
})
Check
What it Detects
Orphan Pages
Files that exist but are never linked to
Resource Hints
External scripts missing preconnect/dns-prefetch
CLS Risk
Images/videos/iframes missing width/height
Render Budget
@import rules and expensive * selectors
🟣 GEO (Generative Engine Optimization)
Check
What it Detects
Trust Network
Long content lacking authority links (.gov, .edu, etc.)
Entity Salience
Brand not in H1 or first 200 words
Data Density
Low table/list ratio on content pages
Freshness
Missing or stale dateModified
Check
What it Detects
Comparison Gap
"vs"/"best" in title without comparison table
Direct Answer
Question headers not followed by concise paragraphs
Video Schema
Video content missing VideoObject JSON-LD
Skimmability
Paragraphs exceeding 150 words
🔷 AEO (Answer Engine Optimization)
Check
What it Detects
Simplicity Score
Complex vocabulary (Flesch-Kincaid proxy)
QA Proximity
Elements interrupting question-answer flow
Speakable Schema
Missing Speakable markup on Q&A content
Unit Clarity
Bare units without <abbr> tags
Color-coded findings grouped by category and severity:
🔴 CRITICAL/HIGH - Must fix for search visibility
🟡 MEDIUM - Recommended improvements
🔵 LOW/INFO - Nice to have optimizations
{
"schemaVersion" : " 1.0" ,
"engine" : { "name" : " darkzseo" , "version" : " 1.4.0" },
"mode" : " content" ,
"target" : " video-1" ,
"status" : " advisory" ,
"generatedAt" : " 2026-01-20T20:00:00" ,
"itemsScanned" : 1 ,
"totalFindings" : 1 ,
"summary" : {
"severity" : { "CRITICAL" : 0 , "HIGH" : 0 , "MEDIUM" : 1 , "LOW" : 0 , "INFO" : 0 },
"category" : { "SEO" : 0 , "GEO" : 1 , "AIO" : 0 , "AEO" : 0 }
},
"findings" : [
{
"ruleId" : " geo.entity_salience" ,
"category" : " GEO" ,
"severity" : " MEDIUM" ,
"file" : " video-1" ,
"message" : " Entity Salience: Brand missing from title/intro" ,
"applicability" : [" youtube" , " content" ]
}
]
}
DarkzSEO returns exit code 1 if any HIGH or CRITICAL findings are detected by default. Use --fail-on to choose a different threshold or --fail-on none for advisory integrations:
# GitHub Actions example
- name : SEO Audit
run : python darkzseo.py --path ./public --quiet
MIT