close notice

This article is also available in
English.

It was translated with technical assistance and editorially reviewed before publication.

Don’t show this again.

In der Webentwicklung schreiben wir nicht nur neue Software, sondern es erreichen uns natürlich auch Fehlermeldungen. Meistens können wir schnell helfen oder den Bugfix auf jeden Fall für einen der nächsten Sprints einplanen. Aber manche Fehler sind hartnäckiger und haben am Ende eine ganz simple Ursache. Um solch einen Fehler geht es heute.

Eine Zeit lang erreichten uns immer mal wieder Berichte, dass bei Usern die Verbindung zu www.heise.de mit der Meldung ERR_HTTP2_PROTOCOL_ERROR nicht zustande kam. Schnell kristallisierte sich heraus, dass die betroffenen User noch ein paar Gemeinsamkeiten hatten: Alle nutzten Chrome als Browser und waren regelmäßige Besucher unseres Angebots. Damit war der Fehler zwar schon etwas eingegrenzt, aber unser größtes Problem war: Wir selbst konnten den Fehler lange Zeit nicht nachstellen.

Viele Kekse

Die Überlegungen gingen dennoch weiter. Was sammeln User (leider heutzutage) zuhauf, wenn sie auf einem weitgehend werbefinanzierten Angebot wie heise online unterwegs sind? – Cookies. Ein Test mit betroffenen Usern sorgte dann immerhin für einen Workaround: Cookies löschen half.

Zunächst hatten wir die Cookie-Größe im Verdacht und testeten mit besonders großen Cookies, aber auch damit ließ sich das Problem für uns nicht reproduzieren. Doch dann meldete sich ein Kollege aus der Redaktion mit demselben Fehler – er bekam ihn sogar regelmäßig. Wir baten ihn um Hilfe bei der Lösung, und er gab Bescheid, sobald der Bug erneut auftrat. Endlich konnten wir das Problem direkt beobachten.

Mit tcpdump schnitten wir den Netzwerkverkehr zwischen uns und dem Browser auf dem Load-Balancer (BigIP) mit, der TLS und HTTP2 termininiert. Dabei stellte sich heraus, dass BigIP selbst die HTTP2-Verbindung wegen eines „Protokollfehlers“ beendete. Da heise online nicht einfach eine direkte Verbindung vom Browser des Users zu unserem Webserver hat, sondern noch diverse (Netzwerk-)Infrastruktur dazwischen liegt, war es für uns schon mal sehr hilfreich, den Punkt ausfindig zu machen, an dem die Verbindung bricht und welcher Teil in der Kette diesen Abbruch auslöst.

Blick in die Bug-Reports

Mit den gewonnenen Erkenntnissen durchforsteten wir die Chrome-Bug-Reports. Bei einem Report war ein HTTP2-Protokoll-Mitschnitt angefügt, bei dem wir sehen konnten, dass Chrome jeden Cookie im HTTP2-Request mit einem separaten Set-Cookie-Header sendete. Das brachte uns auf die Idee, statt der Cookie-Größe einfach mit der schieren Anzahl zu experimentieren, und siehe da: Mit sehr vielen, kleinen Cookies ließ sich das Problem reproduzieren.

Ab hier wurde es dann einfach. Mithilfe unserer Admins fanden wir eine Einstellung in der BigIP, die die maximal zulässige Anzahl der Header setzte. Dieses Limit verschoben wir nun deutlich nach oben und schon war das Problem gelöst. Jedenfalls fürs Erste, denn natürlich ist das neue höhere Limit mit noch mehr Cookie-Headern ebenfalls wieder erreichbar, und der Fehler käme zurück.

Am Fehler sind aber noch ein paar Dinge interessant. In HTTP/1.x waren mehrere Cookie-Header noch unzulässig (siehe RFC 6265), in HTTP/2 hingegen kann der User Agent jedes Cookie als einzelnen Header senden (siehe RFC 7540) und genau das hat Chrome hier getan. Dieses Verhalten ist offensichtlich eine Optimierung, denn das Übertragen sich wiederholender Header lässt sich in HTTP/2 mit der HPACK-Header-Komprimierung (siehe RFC 7541) enorm optimieren. Das funktioniert aber nur für Header, die sich nicht ständig ändern. Ein großer Cookie-Header für alle Cookies müsste also immer wieder komplett neu übertragen werden, sobald sich auch nur ein einzelnes Cookie ändert.

Chrome zeigte leider in den Developer-Tools nichts davon an. Dort wird immer nur ein Cookie-Header gelistet, was die Fehlersuche nicht unbedingt erleichtert hat.

Ob das nun eine Problemlösung oder lediglich ein großes Pflaster ist, wird die Zeit zeigen. Die Ursachenforschung war aber definitiv mal wieder eine der interessanteren Recherchen im Developer-Alltag.

(rme)

Die Patches zum Schließen einer kritischen Sicherheitslücke im React-Server sind unvollständig, erklärt Meta. Admins sollen umgehend die neuen Aktualisierungen anwenden, um weitere entdeckte Sicherheitsprobleme auszubessern, empfiehlt das Unternehmen.

In einem Blog-Beitrag erklären die React-Entwickler, dass die zuvor veröffentlichten Patches anfällig sind. „Wenn du bereits die Updates gegen die kritische Sicherheitslücke in der vergangenen Woche angewendet hast, musst du nochmal aktualisieren“, schreiben sie in einem hervorgehobenen Eintrag. „Wenn du auf 19.0.2, 19.1.3 oder 19.2.2 aktualisiert hast, sind diese [Patches] unvollständig und du musst noch einmal aktualisieren“, präzisieren sie.

Weitere Lücken gefunden

IT-Sicherheitsforscher haben demnach drei weitere Sicherheitslücken in den React-Server-Komponenten entdeckt, als sie versucht haben, die Patches aus der Vorwoche zu missbrauchen. Die neuen Schwachstellen ermöglichen kein Einschleusen und Ausführen von Schadcode, die bisherigen Patches unterbinden diesen Angriff zudem effektiv, ergänzen die React-Entwickler. Neu sind Denial-of-Service-Lücken (CVE-2025-55184, CVE-2025-67779, CVSS 7.5, Risiko „hoch“) und eine Schwachstelle, die Sourcecode exponieren kann (CVE-2025-55183, CVSS 5.3, Risiko „mittel“). Die Schwachstellen finden sich in denselben Paketen und Versionen wie die bereits aktiv missbrauchte Sicherheitslücke (CVE-2025-55182, CVSS 10.0, Risiko „kritisch“).

Betroffen sind die Versionen 19.0.0, 19.0.1, 19.0.2, 19.1.0, 19.1.1, 19.1.2, 19.2.0, 19.2.1 und 19.2.2 von „react-server-dom-webpack“, „react-server-dom-parcel“ und „react-server-dom-turbopack“. In den Fassungen 19.0.3, 19.1.4 und 19.2.3 haben die Programmierer die sicherheitsrelevanten Fehler korrigiert.

​Googles Threat-Intelligence-Team hat zum vergangenen Wochenende Erkenntnisse über laufende Angriffe auf die „React2Shell“ genannte Lücke CVE-2025-55182 zusammengefasst. Demnach hat Google kurz nach Bekanntwerden des Sicherheitslecks Anfang Dezember weitreichende Exploit-Versuche auf viele Cluster beobachtet, die von opportunistischem Cybercrime bis zu der Spionage verdächtigen Gruppierungen ausgehen. Google nennt von China ausgehende Spionageversuche, finanziell motivierte Aktivitäten und auch Attacken aus dem Iran. In den Kampagnen haben die Täter versucht, etwa Minocat-Tunneler, Snowlight-Downloader, Hisonic- und Compood-Backdoors sowie Krypto-Miner zu installieren. Einige der Beobachtungen überschneiden sich mit denen des IT-Sicherheitsunternehmens Huntress sowie mit weiteren bereits beobachteten Angriffen auf die Lücke.

(dmk)

Nicht nur Code bestimmt die Softwarequalität, sondern auch die Art, wie Softwareentwicklerinnen und -entwickler ihn dokumentieren und präsentieren. In einer Zeit, in der viele Entwicklerteams vollständig remote arbeiten und die Codebase weiter kontinuierlich wächst, ist die konsistente und automatisierte Qualitätskontrolle eine Notwendigkeit.

Während meiner Arbeit an einem node-basierten Dokumentationsstack mit dem Static-Site-Generator Astro und Starlight, einem darauf aufbauenden Framework speziell für Dokumentationswebsites, bin ich auf die Herausforderung gestoßen, nicht nur sauberen Code, sondern auch hochwertige Prosa zu produzieren. Prosa kommt aus dem Lateinischen und bedeutet „geradeheraus reden“ – also ohne Schnörkel normal sprechen.

Im Rahmen einer Dokumentation bezeichnet Prosa den gesamten ausformulierten Textinhalt der technischen Dokumentation – alle Erklärungen, Anleitungen, Beschreibungen und Kommentare. Ziel ist es, dass Stil-Konsistenz, Grammatik, Wortwahl, Lesbarkeit und die Einhaltung von Dokumentationsrichtlinien sichergestellt sind und die technische Dokumentation nicht nur funktional korrekt, sondern auch verständlich, einheitlich und professionell geschrieben ist.

Die Lösung: Ein mehrstufiges Linting-System, das Code-Qualität, Formatierung und Prosa-Linting für englischsprachige Dokumentation geschickt miteinander verbindet und sich durch Git Pre-Commit Hooks sowie CI/CD-Pipelines automatisieren lässt. Prosa Linting für deutsche Texte ist nicht nativ integriert, lässt sich aber durch eigene Regeln integrieren. Hierbei kann die KI bei der Erstellung der Regeln gute Dienste tun. Eine gute Hilfestellung bietet hier auch der webbasierte Regelgenerator valegen.

Test-Setup: Astrogon als Grundlage für das Linting-System

Bevor es an die detaillierte Umsetzung des dreistufigen Linting-Konzepts geht, ist eine praktische Arbeitsumgebung einzurichten. Als grundlegendes Code- und Dokumentations-Beispiel dient Astrogon – ein vielseitiges Astro-Theme, das sich ideal für die Demonstration des Linting-Systems eignet. Astrogon ist ein schnell anpassbares, Mehrzweck-Website-Template, das auf Astro JS, Tailwind CSS und React basiert. So bildet es eine solide Grundlage für verschiedene Website-Typen – von Blogs über Dokumentationsseiten bis hin zu Portfolio-Websites.

Astrogon eignet sich deshalb als Demo-Basis, weil es:

1. Verschiedene Dateitypen enthält: .astro, .tsx, .js, .md, .mdx, .css
2. Realistische Komplexität bietet: ein echtes Projekt mit authentischen Herausforderungen
3. Einen modernen Stack verwendet: aktuelle Technologien, die typisch für moderne Webprojekte sind
4. Gut strukturiert ist: klare Ordnerstruktur für effektives Linting
5. Content-fokussiert arbeitet: viel Text-Content für Prosa-Linting

Durch einen Fork des originalen Astrogon Repository, den man lokal klont, lässt sich das Projekt einfach aufsetzen.

# Create a fork (via GitHub.com)

#  Clone repository
git clone 
cd my-linting-project

# Install dependencies
npm install

# Fix existing vulnerabilities
npm audit fix

# Start development server
npm run dev

Nach der Installation steht eine vollständig funktionsfähige Website mit folgender Struktur parat:

my-linting-project/
├── docs/ # Documentation
├── public/ # Static public viewable resources
├── src/
│ ├── assets/ # Pictures, icons,...
│ ├── components/ # reusable components
│ ├── content/ # Markdown/MDX content collections
│ ├── lib/ # Utility functions
│ ├── pages/ # Astro-pages (Routing)
│ ├── styles/ # CSS/SCSS files
│ ├── types/ # TypeScript type-definitions
│ ├── content.config.ts # Content Collections configuration
│ └── env.d.ts # Environment variables types
├── .editorconfig # Editor-configuration
├── .prettierrc # Preconfigured prettier
├── .markdownlint.json # Preconfigured markdownlot
├── astro.config.mjs # Astro configuration
├── package.json # Dependencies and scripts
├── tailwind.config.js # Tailwind CSS configuration
├── tsconfig.json # TypeScript Configuration
└── wrangler.jsonc # Cloudflare workers configuration

Integration der Linter in den Stack

Modernes Linting geht weit über die reine Syntaxprüfung hinaus und umfasst drei komplementäre Dimensionen der Qualitätskontrolle: Code-Qualität für die Logik, Formatierung für die Konsistenz und Prosa-Linting für die menschliche Lesbarkeit. Für diese drei Aspekte kommen verschiedene Linter zum Einsatz: ESLint für die Code-Qualität, Prettier für die Formatierung und Vale für das Prosa-Linting.

Code-Qualität mit ESLint: ESLint bildet das Fundament des Linting-Stacks. Es analysiert TypeScript-, JavaScript- und Astro-Dateien auf potenzielle Fehler, Style-Inkonsistenzen und Best-Practice-Verletzungen. Die Installation leitet der folgende Befehl ein:

npm install -D eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser astro-eslint-parser eslint-plugin-astro

Im nächsten Schritt folgt das Anlegen der Datei .eslintrc.js, die die Konfiguration für die verschiedenen Dateitypen definiert. Dies gelingt am einfachsten über den offiziellen Konfigurations-Wizard von ESLint:

npm init @eslint/config@latest

module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
  ],
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
  },
  env: {
    node: true,
    browser: true,
    es2022: true,
  },
  rules: {
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-empty-interface": "off",
  },
  overrides: [
    {
      files: ["*.astro"],
      extends: ["plugin:astro/recommended"],
      parser: "astro-eslint-parser",
      parserOptions: {
        parser: "@typescript-eslint/parser",
        extraFileExtensions: [".astro"],
      },
    },
  ],
};

Anschließend sind die aufrufenden npm-Skripte in der Datei package.json zu hinterlegen.

{
  "scripts": {
    "lint": "eslint ./src --ext .js,.ts,.jsx,.tsx,.astro --fix",
    "lint:check": "eslint ./src --ext .js,.ts,.jsx,.tsx,.astro"
  }
}

Der Befehl npm run lint korrigiert dann automatisch behebbare Probleme, während npm run lint:check nur überprüft, ohne Änderungen vorzunehmen, und die Ergebnisse im Terminal ausgibt.

Code-Formatierung mit Prettier: Prettier sorgt für einheitliche Code-Formatierung und nimmt Entwicklern die Diskussion über Code-Style ab. Besonders in Astro-Projekten mit gemischten Dateitypen ist eine konsistente Formatierung essenziell. Prettier lässt sich mit folgendem Befehl installieren:

npm install -D prettier prettier-plugin-astro prettier-plugin-tailwindcss

Die Konfiguration von .prettierrc\ im Root-Verzeichnis des Repository berücksichtigt die spezifischen Anforderungen von Astro-Projekten:

{
  "plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80,
  "useTabs": false,
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": ["*.astro"],
      "options": {
        "parser": "astro"
      }
    },
    {
      "files": ["*.md", "*.mdx"],
      "options": {
        "printWidth": 100,
        "proseWrap": "always"
      }
    }
  ]
}

Sind die Abhängigkeiten installiert und die Konfiguration angelegt, werden die entsprechenden npm-Skripte in der Datei package.json eingefügt:

{
  "scripts": {
      ...
      ...
    "format": "prettier --write ./src --log-level silent",
    "format:check": "prettier --check ./src --log-level silent"
  }
}

Der Befehl npm run format korrigiert anschließend automatisch behebbare Probleme, während npm run format:check nur überprüft, ohne Änderungen vorzunehmen, und die Ergebnisse im Terminal ausgibt.

Prosa-Linting mit Vale: Vale ist ein Open-Source-Tool für das Prosa-Linting, das wie ein Code-Linter funktioniert, aber Fließtext verarbeitet. Es prüft Texte auf stilistische Fehler, wiederkehrende Muster und Verstöße gegen vordefinierte oder eigene Stilrichtlinien. Es funktioniert mit Markdown, HTML, AsciiDoc oder reStructuredText und analysiert diese Formate anhand konfigurierter Regeln. Die Style-Guides, anhand derer Vale überprüft, können frei gewählt, angepasst oder erweitert werden – beispielsweise nach Vorbildern von Google, Microsoft oder eigenen Anforderungen.

Typische Regeln erkennen etwa unnötige Passiv-Konstruktionen, zu viele Wiederholungen, fehlende Oxford-Kommas – also das Komma vor der Konjunktion in einer Aufzählung, das helfen soll, Missverständnisse zu vermeiden – oder „Weak Words“ wie „viele“ oder „manchmal“. Die Ergebnisse zeigt Vale direkt im Editor, in der Kommandozeile oder als Teil automatisierter CI-Prozesse.

Vale erfordert eine plattformspezifische Installation sowie den Download der Style-Guides und LibreOffice-kompatibler Hunspell-Wörterbücher (.dic/.aff-Dateien) für die Rechtschreibprüfung in anderen Sprachen als Englisch. Ja, die Kombination von Prosa-Linting-Style-Guides (wie Vale, Google oder Microsoft Style Guides) mit einem deutschen Wörterbuch ist durchaus sinnvoll und funktioniert einwandfrei – Vale nutzt Hunspell-Dictionaries unabhängig voneinander für Rechtschreibung und Stilregeln. Rechtschreibprüfung prüft Wörter auf Korrektheit, während Prosa-Linting Stil, Lesbarkeit und Konventionen überwacht; beide ergänzen sich nahtlos in einem Workflow. Für das beispielhafte Repository habe ich entsprechende Linux/macOS– und Windows-Skripte angelegt, die das Setup erledigen. Getestet ist aktuell nur das Bash-Skript, das PowerShell-Skript wurde via KI automatisiert auf Basis des Bash-Skripts erstellt.

Abweichend von der standardmäßigen Vorgehensweise, bei der Probleme mit dem in Vale integrierten Installer vale sync auftraten, laden die Skripte die git-Repositories für die Styleguides manuell herunter und löschen alle git-spezifischen Inhalte.

# Linux/macOS
chmod +x .vale/install-vale.sh
./.vale/install-vale.sh

# Windows
powershell -ExecutionPolicy Bypass -File .vale/install-vale.ps1

Nach Ausführen der Skripte entsteht folgendes Verzeichnis im Root-Verzeichnis des Repositories:

my-linting-project/
├── .vale/
  ├── dictionaries
  │    ├── de_DE.aff
  │    ├── de_DE.dic
  ├── styles
       ├── Base
       │    ├── accept.txt
	   │    ├── reject.txt
       │    ├── Microsoft/
       │    ├── write-good/ 
  ├── install-vale.ps1
  ├── install-vale.sh
  └── vale

Zu beachten ist dabei noch, alle dynamisch generierten Inhalte in die .gitignore-Datei aufzunehmen.

# Vale binary (install with npm run install-vale)
.vale/dictionaries
.vale/styles/Microsoft
.vale/styles/write-good
.vale/vale
.vale/vale.exe

Vale-Styleguides auswählen und installieren

Das Installationsskript lädt nicht nur Vale herunter, sondern auch die benötigten Styleguides. Auf der Vale-Website sind, neben einigen weiteren spezifischen, vier wesentliche Style-Guides referenziert:

Google

• Starker Fokus auf technische Konsistenz und Präzision für Entwickler.
• Große Ausnahmeliste für Akronyme und Begriffe aus APIs.
• Substitutionslisten mit Google-typischer Terminologie.
• Stil: direkt, technisch, an Entwickler gerichtet, prägnant, präzise.
• Quelle Git, Quelle Style-Guide

Microsoft

• Sehr starke Gewichtung auf Inklusivität und Barrierefreiheit.
• Klare Satzlängen- und Limits für Wörter.
• Hunderte produkt- und communityspezifische Begriffe.
• Stil: freundlich, inklusiv, leserorientiert, markengerecht, barrierefrei.
• Quelle Git, Quelle Style-Guide

Red Hat

• Strikte Regeln zu „Open Source“-neutraler Sprache und Kollaboration.
• Erlaubt keinen Produkt-Bias, eigene Accessibility- und Bias-Listen.
• Regeln für CLI-Beispiele, Dateipfade und produktneutrale Formulierungen.
• Bevorzugt kollaborativen Duktus und Community-Perspektive.
• Stil: offen, kollaborativ, communitygetrieben, produktneutral, inklusiv.
• Quelle Git, Quelle Style-Guide

Write-good

• Fokussiert sich rein auf sprachliche Klarheit und verbessert Lesbarkeit und Stil, ohne produkt- oder technikspezifische Prüfkriterien.
• In modernen Dokumentations-Workflows eignen sich Write-Good-Regeln ergänzend, um die sprachliche Qualität unabhängig von der Plattform zu verbessern.
• Write-Good Vale Style-Guide

Im Folgenden kommt der „Microsoft Style Guide“ zum Einsatz – erweitert um die Style-Guides „write-good“, „MDX“ und „Vale Core“. Diese sind wie folgt charakterisiert:

Microsoft Style Guide: Unternehmensstandards für technische Dokumentation

write-good: allgemeine Regeln für klares Schreiben

Vale Core: grundlegende Prosa-Regeln

MDX: Prüfung der Sprache innerhalb von JSX Tags

Beim Einsatz unterschiedlicher Style-Guides in Kombination lässt sich in manchen Situationen schwer identifizieren, warum welche Regel benötigt wird. Ein Beispiel macht dies klarer. Gegeben ist folgende MDX-Datei:

---
title: "Using Feature Y"
author: "Adesso"
---

# Feature Y Benefits

You will be able to use this feature very effectively. It was developed by adeso and their team.


  DO NOT use this feature if your environment isn't set correctly.


Step 1: Initializing the data source
Step 2 Call the performOperation() function
Step 3: Confirm the output's accuracy

> Note: The process can be slow. It is important that you wait patiently.

For details, check our doc [documentation](htp://example.com/feature-y).

Die Ergebnisse des Lintings fasst die folgende Tabelle zusammen:

Fehler	Welcher Regelsatz	Erklärungen & Korrektur
Autor „Adesso“ und „adeso“ inkonsistent geschrieben	Custom Regel	Korrigiert in „adesso“
Großschreibung in JSX-Komponente ``	MDX-Regelsatz	Meldet falsche Großschreibung oder unbekannte JSX-Tags, erwartet `` o.Ä.
Markdown-Liste ohne korrekte Aufzählungszeichen	MDX-Regelsatz	Fehlt das `-` oder die Nummerierung bei Liste (z.B. `Step 2` ist kein Listenelement)
Unsichere URL im Link (htp statt http)	Microsoft Regelsatz	Erkennt ungültige URLs, fordert Korrektur auf gültiges Schema (`
Übermäßiger Gebrauch von Floskeln (z.B. „very effectively“, „It is important that“)	Write-Good	Empfiehlt prägnantere Ausdrucksweise („effectively“, „Wait patiently.“)
Use of first-person pronouns („You will be able…“, „you wait patiently“) in nicht passender Art	Microsoft Regelsatz	Warnt bei unpassender Verwendung von Personalpronomen, schlägt Sparse-Usage vor
Passiver Sprachgebrauch („was developed“)	Write-Good & Microsoft	Empfiehlt aktive Formulierung, z.B. „adesso developed this feature.“

Die korrigierte MDX-Datei sieht nach der Regelprüfung dann wie folgt aus:

---
title: "Using Feature Y"
author: "adesso"
---

# Feature Y Benefits

You can use this feature effectively, adesso and their team developed it.


  Do not use this feature if your environment is not set correctly.


- Step 1: Initialize the data source
- Step 2: Call the performOperation() function
- Step 3: Confirm the output's accuracy

> Note: The process can be slow. Please wait patiently.

For details, check our [documentation](

Mithin ergeben sich folgende Einschränkungen:

• Die Vale-Style-Guides sind nur für englischen Text optimiert, eine Anpassung an Deutsch oder andere Sprachen scheint bisher nicht vorgesehen zu sein.
• Die Style-Guides basieren auf klassischen Regular Expressions. Wer KI-basierte Ansätze erwartet, wird enttäuscht.
• Speziell in größeren Projekten empfiehlt es sich einen eigenen Style-Guide aufzubauen. Die Konfiguration von Vale erfordert eine kontinuierliche Anpassung an die Bedürfnisse des Projekts.

Konfigurieren und Anpassen von Vale (.vale.ini)

Die Vale-Konfigurationsdatei gibt an, in welchen Verzeichnissen und mit welchen Style-Vorgaben das Tool den Text überprüfen soll. Für das Beispiel sei angenommen, dass sich der englische Content in den Unterverzeichnissen des Ordners /src/content befindet.

# Vale configuration file
# See: 
Packages = MDX

StylesPath = .vale/styles
# Add dictionary path for German dictionaries
DictionaryPath = .vale/dictionaries

MinAlertLevel = error

# File type associations - English content (excluding German docs)
[src/content/**]{.md,.mdx}

# Enable/disable specific styles for English content
BasedOnStyles = Vale, write-good, Microsoft

# Enable rules
Vale.Terms = YES  # Disables term-based checks. Example: Avoid using "jargon".
Vale.Spelling = YES  # Disables spelling checks. Example: "recieve" instead of "receive".
Vale.Vocab = YES  # Disables vocabulary checks. Example: Using "utilize" instead of "use".
Vale.Repetition = YES  # Disables repetition checks. Example: "very very good".
Vale.Wordiness = YES  # Disables wordiness checks. Example: "in order to" instead of "to".

# Write-good rules (English-specific)
write-good.Weasel = YES  # Disables detection of weasel words. Example: "some people say".
write-good.TooWordy = YES  # Disables detection of overly wordy phrases. Example: "due to the fact that".
write-good.So = YES  # Disables detection of sentences starting with "so". Example: "So, we decided to...".
write-good.ThereIs = YES  # Disables detection of "there is/are" constructions. Example: "There is a need for...".
write-good.Passive = YES  # Disables detection of passive voice. Example: "The ball was thrown by John".
write-good.Adverbs = YES  # Disables detection of adverbs. Example: "He ran quickly".
write-good.Cliches = YES  # Disables detection of cliches. Example: "Think outside the box".
write-good.E-Prime = YES  # Disables detection of E-Prime violations. Example: "He is a teacher".
write-good.Illusions = YES  # Disables detection of ambiguous phrases. Example: "The results were significant".

# Microsoft style rules (English-specific)
Microsoft.Gender = YES  # Ensures gender-neutral language is used. Example: Use "they" instead of "he/she".
Microsoft.PassiveVoice = YES  # Flags sentences written in passive voice. Example: "The report was written by Sarah".
Microsoft.Cliches = YES  # Detects overused phrases and cliches. Example: "At the end of the day".
Microsoft.Jargon = YES  # Highlights technical jargon that may confuse readers. Example: "Leverage synergies".
Microsoft.Complexity = YES  # Identifies sentences that are overly complex or difficult to read. Example: "The implementation of the solution was carried out in a manner that ensured...".
Microsoft.Redundancy = YES  # Flags redundant phrases or words. Example: "Free gift".
Microsoft.Spelling = YES  # Checks for spelling errors based on Microsoft's style guide. Example: "color" vs. "colour".
Microsoft.Spacing = YES  # Disables because of D2 diagrams - Allows ignoring spacing-related issues. Example: "word  word".
Microsoft.Contracting = YES  # Allows ignoring contracting-related issues. Example: "isn't" vs. "is not".
Microsoft.Quotes = YES  # Allows ignoring quotes-related issues. Example: "'single quotes' vs. "double quotes".
Microsoft.Contractions = YES  # Allows ignoring contractions-related issues. Example: "can't" vs. "cannot".
Microsoft.Foreign = YES  # Allows ignoring foreign phrases and words. Example: "et cetera".
Microsoft.Plurals = YES  # Allows ignoring pluralization-related issues. Example: "criterias" vs. "criteria".
Microsoft.Auto = YES  # Disables automatic suggestions for corrections. Example: "autocorrect".
Microsoft.AMPM = YES  # Allows ignoring AM/PM formatting issues. Example: "2 PM" vs. "14:00".
Microsoft.DateOrder = YES  # Allows ignoring date order-related issues. Example: "MM/DD/YYYY" vs. "DD/MM/YYYY".
Microsoft.Dashes = YES  # Allows ignoring dash-related issues. Example: "em-dash" vs. "en-dash".
Microsoft.DateFormat = YES  # Allows ignoring date format-related issues. Example: "2025-10-01" vs. "01/10/2025".
Microsoft.Units = YES  # Allows ignoring unit-related issues. Example: "5kg" vs. "5 kg".
Microsoft.Avoid = YES  # Allows ignoring "avoid" suggestions. Example: "Avoid using passive voice".
Microsoft.Negative = YES  # Allows ignoring negative phrasing suggestions. Example: "Not bad" vs. "Good".

Nun sind noch die richtigen Cross-Platform npm-Skripte für Vale bereitzustellen, um den Linter zu installieren und aufzurufen.

{
  "scripts": {
	  ...
	  ...
    "postinstall": "npm run install-vale",
	"install-vale": "node -e \"const cmd = process.platform === 'win32' ? 'powershell -ExecutionPolicy Bypass -File .vale/install-vale.ps1' : 'bash .vale/install-vale.sh'; require('child_process').exec(cmd, (err, stdout, stderr) => { if (err) { console.error(stderr); process.exit(1); } console.log(stdout); })\"",
    "prose": "node -e \"const vale = process.platform === 'win32' ? './.vale/vale.exe' : './.vale/vale'; const { exec } = require('child_process'); exec(vale + ' --config=.vale.ini src/content', (err, stdout, stderr) => { console.log(stdout); if (stderr) console.error(stderr); if (err) process.exit(1); });\""
  }
}

• postinstall: Wird automatisch aufgerufen, wenn npm install ausgeführt wird
• install-vale: Ruft je nach Plattform die richtigen Installationsscripte auf
• prose: Ruft das Linting auf und gibt Fehler in der Kategorie „error“, „warning“ und „information“ aus

Ausnahmen für Sonderfälle sind eigens zu definieren, etwa für Situationen, in denen Vale eine Regel bewusst ignorieren soll. Beispielsweise würde die Regel write-good.So für den Satz „So the experiment failed because the measurements were taken incorrectly“ normalerweise den folgenden Fehler melden:

 src/content/blog/myfile.mdx
 188:52  error  Don't start a sentence with     write-good.So 
                'So '.                                        

✖ 1 error, 0 warnings and 0 suggestions in 38 files.

Um für diesen spezifischen Fall die Prüfung abzuschalten, ist die entsprechende Zeile mit einem Kommentar zu umfassen:

{/*  */}

So the experiment failed because the measurements were taken incorrectly

{/*  */}

Zu beachten ist dabei, dass die beiden Kommentar-Tags und die betroffene Zeile durch einen Zeilenumbruch getrennt sein müssen. Da es sich zudem um MDX-Dateien handelt, müssen die Zeilen erst mit einem JSX-Kommentarblock umschlossen werden, damit der Server nicht meckert, und anschließend mit einem HTML-Kommentarblock, damit Vale diesen erkennt. Darüber hinaus benötigt Vale – mit folgenden beiden Zeilen in der vale.ini – einen Hinweis, dass MDX-Dateien letztlich auch als Markdown-Dateien zu behandeln sind:

[formats]
mdx = md

Im Falle kompletter Textblöcke oder wenn der Grund der Deaktivierung der Vale-Regel benannt werden soll, ist es ebenfalls möglich, nur einzelne Regeln abzuschalten:

{/*  */}

So the experiment failed because the measurements were taken incorrectly

{/*  */}