Verwenden des Inhalts-Linters

Informationen zum GitHub Docs-Inhalts-Linter

Unser Inhalts-Linter erzwingt Styleguideregeln in unseren Markdown-Inhalten.

Der Linter verwendet markdownlint als Framework, um Überprüfungen durchzuführen, Fehler zu melden und Inhalte nach Möglichkeit automatisch zu korrigieren. Dieses Framework führt bestimmte Regeln flexibel aus, gibt beschreibende Fehlermeldungen aus und behebt Fehler. Der GitHub Docs-Inhalts-Linter verwendet verschiedene vorhandene markdownlint-Regeln sowie zusätzliche benutzerdefinierte Regeln, um die Markdown-Inhalte in unseren data- und content-Verzeichnissen zu überprüfen. Unsere benutzerdefinierten Regeln implementieren Überprüfungen, die entweder noch nicht im markdownlint-Framework verfügbar sind oder speziell für GitHub Docs-Inhalte gelten. Regeln überprüfen die Syntax sowohl für Markdown als auch für Liquid.

Ausführen des GitHub Docs-Inhalts-Linters

Der GitHub Docs-Inhalts-Linter wird automatisch beim Pre-Commit ausgeführt, du kannst ihn aber auch manuell ausführen.

Automatische Ausführung des Linters beim Pre-Commit

Wenn Sie Inhalte lokal schreiben und Dateien über die Befehlszeile committen, werden diese gestageten Dateien automatisch vom Inhalts-Linter gelöscht. Sowohl Warnungen als auch Fehler werden gemeldet, aber nur Fehler verhindern, dass Ihr Commit abgeschlossen wird.

Wenn Fehler gemeldet werden, wird dein Commit nicht abgeschlossen. Sie müssen die gemeldeten Fehler beheben, die geänderten Dateien erneut hinzufügen und Ihre Änderungen erneut committen. Alle gemeldeten Fehler müssen behoben werden, um zu verhindern, dass Fehler in den Inhalt gelangen, die gegen den Styleguide von GitHub Docs verstoßen. Wenn Warnungen gemeldet werden, können Sie optional auswählen, ob sie behoben werden sollen oder nicht.

Wenn Sie Inhalte lokal schreiben, gibt es mehrere Regeln, die Sie über die Befehlszeile automatisch beheben können. Wenn Sie behebbare Fehler automatisch beheben möchten, lesen Sie „Automatische Korrektur von Fehlern, die korrigiert werden können“.

Wenn Sie eine Datei auf der Benutzeroberfläche von GitHub bearbeiten, können Sie nicht automatisch Fehler beheben oder den Linter für einen Commit ausführen. Sie erhalten dann eine CI-Fehlermeldung, wenn der Inhalt mit einem Schweregrad von error gegen Regeln verstößt.

Manuelles Ausführen des Linters

Ausführen des Linters in gestageten und geänderten Dateien

Verwende den folgenden Befehl, um den Linter lokal für deine gestageten und geänderten Dateien auszuführen. Ausgegeben werden Fehler mit den Schweregraden warning und error.

npm run lint-content

Führe den Linter für gestageten und geänderte Dateien aus, und lass nur Fehler melden.

Verwende den folgenden Befehl, um den Linter lokal für deine gestageten und geänderten Dateien auszuführen, und lass nur Fehler mit dem Schweregrad error melden.

npm run lint-content -- --errors

Ausführen des Linters in bestimmten Dateien oder Verzeichnissen

Verwende den folgenden Befehl, um den Linter lokal in bestimmten Dateien oder Verzeichnissen auszuführen. Trenne mehrere Pfade mit einem Leerzeichen. Du kannst sowohl Dateien als auch Verzeichnisse im selben Befehl einschließen.

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

Automatische Korrektur von Fehlern, die korrigiert werden können

Wenn fixable: true in der Beschreibung eines Fehlers enthalten ist, kannst du die folgenden Befehle verwenden, um den Fehler automatisch zu korrigieren.

Führe diesen Befehl aus, um nur gestagete und geänderte Dateien zu korrigieren:

npm run lint-content -- --fix

Führe diesen Befehl aus, um bestimmte Dateien oder Verzeichnisse zu korrigieren:

npm run lint-content -- \
  --fix --paths content/FILENAME.md content/DIRECTORY

Ausführen eines bestimmten Satzes Linter-Regeln

Verwende den folgenden Befehl, um eine oder mehrere spezifische Linter-Regeln auszuführen. Diese Beispiele führen die Regeln heading-increment und code-fence-line-length aus. Ersetze heading-increment code-fence-line-length durch einen oder mehrere Linter-Aliase, die du ausführen möchtest. Führe npm run lint-content -- --help aus, um die Liste der Linter-Regeln anzuzeigen, die du an diese Option übergeben kannst. Du kannst entweder den kurzen Namen (z. B. MD001) oder den langen Namen (z. B. heading-increment) einer Linter-Regel verwenden.

Führe die angegebenen Linter-Regeln für alle gestageten und geänderten Dateien aus:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length

Führe die angegebenen Linter-Regeln für bestimmte Dateien oder Verzeichnisse aus:

npm run lint-content -- \
  --rules heading-increment code-fence-line-length \
  --path content/FILENAME.md content/DIRECTORY

Umgehen des Commit-Hooks

Wenn der Linter Fehler abfängt, die nicht von Ihnen stammen, können Sie den Git-Commit-Hook beim Committen der Änderungen mit der Option --no-verify umgehen.

git commit -m 'MESSAGE' --no-verify

Anzeigen des Hilfemenüs für das Skript des Inhalts-Linters

npm run lint-content -- --help

Regeln für das Linten

Jede Regel ist in einer Datei in src/content-linter/style konfiguriert, in der die Schweregrade von Regeln definiert sind.

Fehler müssen behoben werden, bevor die Änderungen an der main-Verzweigung zusammengeführt werden. Warnungen sollten behoben werden, verhindern aber nicht, dass eine Änderung an der main-Verzweigung zusammengeführt wird. Die meisten Regeln werden letztendlich zu Fehlern hochgestuft, sobald der Inhalt keine Verletzungen mehr aufweist, die eine Warnung auslösen.

Syntax für Linting-Regeln

Einige Linting-Regeln geben Warnungen oder Fehler basierend auf HTML-Kommentaren zurück, die Sie Artikeln hinzufügen können.

Syntax für ablaufende und abgelaufene Inhalte

Mit den Regeln GHD038 und GHD039 wird nach Inhalten gesucht, für die manuell ein Ablaufdatum erstellt wurde. Vierzehn Tage vor dem angegebenen Datum gibt der Inhalts-Linter eine Warnung zurück, dass der Inhalt bald abläuft. Ab dem angegebenen Datum gibt der Inhalts-Linter einen Fehler zurück und kennzeichnet den Inhalt zur Wartung.

Sie können Inhalten ein Ablaufdatum hinzufügen, indem Sie den jeweiligen Inhalt mit HTML-Tags umschließen, die ein Ablaufdatum in folgendem Format enthalten: <!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->

Verwendung:

This content does not expire.
<!-- expires 2022-01-28 -->
This content expires on January 28, 2022.
<!-- end expires 2022-01-28 -->
This content also does not expire.

Wenn Sie die abgelaufenen Tags in einem HTML–tableElement platzieren, stellen Sie sicher, dass das Tag die gesamte Zeile und nicht nur die Zelle umgibt. Zum Beispiel:

<!-- expires 2024-06-28 -->
<tr>
<td>
macOS
</td>
<td>
The <code>macos-11</code> label has been deprecated and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->

Unterdrücken von Linter-Regeln

In seltenen Fällen müssen Sie vielleicht etwas dokumentieren, das gegen eine oder mehrere Linter-Regeln verstößt. In diesen Fällen können Sie Regeln durch Hinzufügen eines Kommentars in der Markdown-Datei unterdrücken. Sie können alle Regeln oder nur bestimmte Regeln deaktivieren. Versuchen Sie immer, so wenige Regeln wie möglich einzuschränken. Sie können eine Regel für eine gesamte Datei, für einen Abschnitt einer Markdown-Datei, einer bestimmten Zeile oder der nächsten Zeile deaktivieren.

Wenn Sie beispielsweise einen Artikel schreiben, der den regulären Ausdruck (^|/)[Cc]+odespace/ enthält, der die Syntax für umgekehrte Verknüpfungen überprüft, wird die MD011-Regel ausgelöst, die auf umgekehrte Links prüft. Sie können die Regel MD011 für diese bestimmte Zeile deaktivieren, indem Sie den folgenden Kommentar hinzufügen.

(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->

Wenn sich die zu ignorierende Zeile in einem Codeblock befindet, können Sie den Codeblock ignorieren, indem Sie ihn mit den folgenden Kommentaren umgeben.

<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->

Mit diesen Kommentaren können Regeln aktiviert oder deaktiviert werden.