HTML-SEO-Prüfung
Überblick
Erstelle eine handlungsorientierte, nach Schweregrad sortierte Liste von Ergebnissen für eine oder mehrere statische HTML-Dateien. Die Fähigkeit bündelt einen Parser (nur Stdlib), der jedes SEO-relevante Signal in ein einzelnes JSON-Dokument extrahiert, eine umfassende Bewertungsmatrix und eine Berichtsvorlage – gemeinsam ermöglichen sie eine Prüfung mit vorhersehbarem Ergebnis bei jeder Ausführung.
Verwendung
Verwende diese Fähigkeit, wenn die Eingabe eine oder mehrere statische .html-Dateien (oder ein Verzeichnis davon) ist und der Benutzer umsetzbare On-Page-SEO-Ergebnisse wünscht. Auslöser sind: „SEO-Prüfung“, „SEO-Review“, „SEO für diese HTML-Seite überprüfen“, „Meta-Tags dieser Seite bewerten“, „On-Page-SEO auditieren“.
Nicht verwenden bei:
- Quellen eines Static-Site-Generators (Jekyll/Hugo/Astro/Eleventy/Next.js). Diese benötigen eine quellenbewusste Prüfung; verschieben auf eine zukünftige Fähigkeit
ssg-seo-review. - Der Benutzer wünscht Live-Leistungskennzahlen (LCP, CLS, INP). HTML allein kann diese nicht liefern; empfehle Lighthouse oder PageSpeed Insights.
- Der Benutzer wünscht Backlinks, Domain-Autorität oder andere Off-Page-Analysen. Dafür sind Drittanbieter-Tools (Ahrefs, SEMrush usw.) erforderlich.
Arbeitsablauf
1. Signale extrahieren
Führe den Parser gegen das Ziel aus. Er akzeptiert eine einzelne Datei oder ein Verzeichnis (rekursiv *.html):
python3 scripts/extract_seo_signals.py <pfad> --pretty
Die Ausgabe ist ein JSON-Dokument mit den folgenden Hauptschlüsseln: lang, title, meta, links, scripts, headings, images, links_audit, body_word_count. Jedes Element enthält eine line-Nummer zum Zitieren in den Ergebnissen.
Bei einem Verzeichnis ist die Ausgabe {"files": [<pro-Datei-Objekt>]}.
Das Skript verwendet nur die Python-Standardbibliothek – kein pip install erforderlich. Wenn das Parsen einer bestimmten Datei fehlschlägt, enthält das Ergebnis für diese Datei ein error-Feld, und die Prüfung wird für die restlichen Dateien fortgesetzt.
2. Signale mit der Bewertungsmatrix abgleichen
Lade references/seo-checklist.md. Gehe jede Kategorie der Reihe nach durch und überprüfe den entsprechenden JSON-Pfad. Die Matrix listet für jede Prüfung explizit den zu inspizierenden Pfad auf (z. B. images.missing_alt, meta.description.length, scripts.render_blocking_candidates).
Notiere für jede fehlgeschlagene Prüfung:
- Den Schweregrad (P0/P1/P2/P3) aus der Matrix.
- Die Zeilennummer aus der JSON-Ausgabe.
- Das exakte, in Anführungszeichen gesetzte Markup oder Attribut aus der Datei (lies die Datei erneut mit der Zeilennummer, um wörtlich zu zitieren – nie paraphrasieren).
- Die Korrektur, geschrieben als konkreter Vorher/Nachher-Diff, wenn die Änderung mechanisch ist.
3. Jedes Ergebnis vor der Meldung überprüfen
Bevor du ein Ergebnis formulierst, bestätige das Problem mechanisch:
- Eine Behauptung, dass ein Attribut „fehlt“, muss aus der strukturierten Ausgabe des Parsers stammen, nicht aus dem Überfliegen des HTML.
- Eine Behauptung, dass ein Wert „zu kurz/lang“ ist, muss die tatsächliche Zeichenanzahl aus dem JSON zitieren.
- Zitiertes Markup muss exakt sein; wenn ein Zitat nicht zeichengenau aus der Datei reproduziert werden kann, lass es weg.
Dies schützt vor dem häufigsten Prüfungsfehler: ein Problem zu erfinden, das tatsächlich nicht existiert.
4. Den Ergebnisbericht erstellen
Verwende assets/findings-template.md als Struktur. Fülle aus:
- Zusammenfassender Absatz mit Gesamtbewertung und Anzahl der Schweregrade.
- Ein Block pro Ergebnis, sortiert nach Schweregrad (P0 → P3), dann nach Dateireihenfolge.
- Optional ein Abschnitt „Schnelle Erfolge“ bei mehr als ~10 Ergebnissen – wähle die 3-5 Korrekturen mit der größten Hebelwirkung.
- Ein Abschnitt „Nicht im Umfang enthaltene Punkte“ mit allem, was der Benutzer mit externen Tools nachverfolgen sollte (Lighthouse für echte CWV, curl für Canonical-Auflösung usw.).
Wenn die Prüfung mehrere Dateien umfasst, erstelle einen Bericht für alle Dateien, wobei die Ergebnisse pro Datei unter der jeweiligen Schweregradstufe gruppiert werden – nicht ein Bericht pro Datei.
5. Überspringen mit Anstand
Wenn eine Prüfung Informationen erfordert, die der Parser nicht liefern kann (z. B. „Wird diese kanonische URL mit 200 ausgeliefert?“), rate nicht. Notiere dies im Abschnitt „Nicht im Umfang enthaltene Punkte“ des Berichts und fahre fort.
Referenz
scripts/extract_seo_signals.py– HTML-Parser. Nur Stdlib. Gibt strukturiertes JSON mit Zeilennummern aus.references/seo-checklist.md– Vollständige Bewertungsmatrix, nach Kategorien organisiert, mit Schweregraden und JSON-Pfaden für jede Prüfung.assets/findings-template.md– Ausgabeformat für den Prüfbericht.