Skip to content

VALIDATION_PROPOSAL.md

Latest commit

 

History

History
240 lines (167 loc) · 5.28 KB

VALIDATION_PROPOSAL.md

File metadata and controls

240 lines (167 loc) · 5.28 KB

Implementierungs-Zusammenfassung: PR Validation

🎯 Überblick

Dieser Proposal implementiert ein automatisches Validierungssystem für Pull Requests in der NFDI4Chem Knowledge Base.

✅ Implementierte Komponenten

1. Validierungsskript

Datei: scripts/validate-content.js

  • ✅ Prüft alle md und mdx-Dateien im docs/-Verzeichnis
  • ✅ Validiert Frontmatter auf gültiges YAML und erforderlichen Slug
  • ✅ Prüft Seitentitel (h1 oder title im Frontmatter)
  • ✅ Warnt bei identischen h1 und title Werten
  • ✅ Benutzerfreundliche Fehlerausgabe mit Zusammenfassung
  • ✅ Exit-Code-basierte Fehlerbehandlung für CI/CD

Verwendung:

npm run validate-content

2. GitHub Actions Workflow

Datei: .github/workflows/pr-validation.yml

  • ✅ Triggert automatisch bei Pull Requests
  • ✅ Installiert Dependencies
  • ✅ Führt Content-Validierung durch
  • ✅ Führt Docusaurus Build durch
  • ✅ Meldet Ergebnisse im PR

Features:

  • Lädt Dependencies aus Cache (schneller)
  • Node.js 18 (aktuell und stabil)
  • Automatische Status-Updates im PR

3. Package.json Updates

  • ✅ Neue devDependencies: glob und gray-matter
  • ✅ Neue npm Scripts:
    • npm run validate-content - Nur Validierung
    • npm run test:ci - Validierung + Build

4. Dokumentation

  • ✅ scripts/VALIDATION_SETUP.md - Detaillierte Setup-Anleitung
  • ✅ scripts/EXAMPLES.md - Praktische Beispiele für gültige/ungültige Dateien
  • ✅ scripts/README.md - Schnelle Übersicht
  • ✅ scripts/validation.config.js - Vorschläge für Erweiterungen

📋 Validierungsregeln

Frontmatter

---
slug: /my-page/        # ✅ ERFORDERLICH - eindeutig
title: Page Title      # ⚠️ Optional, aber empfohlen
description: ...       # ⚠️ Optional, gut für SEO
---

Validierungen:

  • Slug muss vorhanden sein
  • Slug muss ein String sein
  • Slug darf nicht leer sein

Seitentitel

  • Mindestens eine der folgenden Optionen erforderlich:
    • h1 Überschrift (# Title)
    • title im Frontmatter
  • Wenn beide vorhanden:
    • Sie dürfen nicht identisch sein
    • Empfehlung: h1 detaillierter, title kürzer für SEO

Build

  • Docusaurus Build muss fehlerfrei laufen
  • Keine Broken Links/Images (basierend auf docusaurus.config.js)

🚀 Erste Schritte

Installation

npm install

Das installiert die neuen devDependencies.

Lokal Testen

# Nur Validierung
npm run validate-content

# Nur Build
npm run build

# Beides zusammen (wie der PR-Check)
npm run test:ci

Bei Fehlern

Siehe scripts/EXAMPLES.md für Lösungsbeispiele.

🔄 Workflow in der Praxis

Für Contributors:

  1. Vor dem Commit:

    npm run validate-content

  2. Vor dem Push:

    npm run test:ci

  3. Push und PR öffnen:

    • GitHub Actions läuft automatisch
    • Status wird im PR angezeigt

Für Maintainer:

  • PR kann nur gemerged werden wenn alle Checks bestanden sind ✅
  • Automatische Validierung spart Zeit bei Code Reviews
  • Konsistente Dokumentation garantiert

📦 Dependencies

Neue NPM-Packages:

  • glob (^10.3.10) - Datei-Pattern-Matching
  • gray-matter (^4.0.3) - Frontmatter-Parsing

Beides sind kleine, etablierte Packages ohne weitere Dependencies.

🎨 Output-Beispiel

🔍 Validiere Dokumente...

📁 Gefundene Dateien: 42

📄 docs/10_domains/example.md
  ❌ Fehler:
     - Slug im Frontmatter fehlt
  ⚠️  Warnungen:
     - h1 und Frontmatter-title sind identisch

📊 Zusammenfassung:
   Dateien geprüft: 42
   Fehler: 1
   Warnungen: 1

❌ Validierung fehlgeschlagen!

🔧 Erweiterungsmöglichkeiten

Das System ist modular und kann leicht erweitert werden:

  1. SEO-Validierung

    • Meta description Länge
    • Keywords prüfen
    • Title length für Suchresultate

  2. Link-Validierung

    • Interne Links auf Existenz
    • Externe Links erreichbar

  3. Image-Validierung

    • Dateien existieren
    • Alt-Text vorhanden
    • Bildgröße optimiert

  4. Code-Qualität

    • Spellcheck (deutsche Rechtschreibung)
    • MDX-Lint
    • Remark-Plugins

Siehe scripts/validation.config.js für Implementierungs-Ideen.

📊 Statistik

Komponente Dateien Zeilen
Validierungsskript 1 ~150
GitHub Actions 1 ~25
Dokumentation 4 ~600+
Config-Beispiel 1 ~150
Total 7 ~925

✨ Vorteile

  1. Qualitätssicherung

    • Konsistente Dokumentenstruktur
    • Keine fehlenden Slugs/Titel
    • Build garantiert fehlerfrei

  2. Automatisierung

    • Keine manuellen Checks nötig
    • Sofortiges Feedback in PRs
    • Spart Zeit im Review-Prozess

  3. Developer Experience

    • Klare Fehler-Meldungen
    • Einfache lokale Tests
    • Gute Dokumentation

  4. Wartbarkeit

    • Modular und erweiterbar
    • Gute Code-Struktur
    • Keine Abhängigkeiten auf externe Services

🎓 Nächste Schritte (Optional)

  1. Pre-commit Hooks (Husky) - lokale Validierung vor Commit
  2. Spellcheck (Cspell) - Deutsche Rechtschreibung
  3. Link-Checker - Interne Links validieren
  4. Image-Optimizer - Bildgrößen optimieren
  5. SEO-Tools - Meta-Tags prüfen

Status: ✅ Produktionsbereit - Sofort einsatzbar

Kompatibilität: Node.js 18+, alle OS (Linux, macOS, Windows)

Wartung: Minimal - nur 2 externe Dependencies