Skip to main content

Verwenden des Inhalts-Linters

Du kannst den Inhalts-Linter verwenden, um deine Beiträge auf Fehler zu prüfen.

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.

Shell
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.

Regel-IDRegelname(n)BeschreibungseverityTags
MD001Überschrift-InkrementÜberschriftenebenen sollten jeweils nur um eine Ebene erhöht werdenerrorÜberschriften
MD004ul-styleUnsortierter ListenstilerrorAufzählungszeichen, ul
MD009keine-nachfolgenden-LeerzeichenNachgestellte Leerzeichenerrorwhitespace
MD011keine-umgekehrte-VerknüpfungSyntax für umgekehrte VerknüpfungenerrorVerknüpfungen
MD012ohne-mehrere-LeerzeichenMehrere aufeinander folgende leere ZeilenerrorLeerzeichen, Leerzeilen
MD014Befehle-anzeigen-AusgabeDollarzeichen vor Befehlen ohne Ausgabe verwendeterrorcode
MD018kein-fehlendes-Leerzeichen-atxKein Leerzeichen nach dem Hash auf der Atx-FormatvorlagenüberschrifterrorÜberschriften, Atx, Leerzeichen
MD019ohne-mehrere-Leerzeichen-atxMehrere Leerzeichen nach dem Hash auf der Atx-FormatvorlagenüberschrifterrorÜberschriften, Atx, Leerzeichen
MD022Leerzeichen um ÜberschriftenÜberschriften sollten von einer einzelnen Leerzeile umgeben seinerrorÜberschriften, Leerzeilen
MD023Überschrift-Anfang-linksÜberschriften müssen am Zeilenanfang beginnenerrorÜberschriften, Leerzeichen
MD027ohne-mehrere-Leerzeichen-BlockzitatMehrere Leerzeichen nach einem BlockzitatsymbolerrorBlockzitat, Leerzeichen, Einzug
MD029ol-PräfixPräfix „Sortiertes Listenelement“errorol
MD030Liste-Marker-LeerzeichenLeerzeichen nach Listenmarkierungenerrorol, ul, Leerzeichen
MD031Leerzeichen-um-FenceFenced-Code-Blöcke sollten von Leerzeilen umgeben seinerrorCode, Leerzeilen
MD037kein-Leerzeichen-in-HervorhebungLeerzeichen innerhalb von HervorhebungsmarkierungenerrorLeerzeichen, Hervorhebung
MD039kein-Leerzeichen-in-LinksLeerzeichen in Link-TexterrorLeerzeichen, Links
MD040Fenced-Code-SpracheFenced Codeblöcke sollten eine angegebene Sprache aufweisen.errorCode, Sprache
MD042keine-leeren-LinksKeine leeren LinkserrorVerknüpfungen
MD047einzeln-nachstehender-ZeichenvorschubDateien sollten mit einem einzigen Zeilenvorschubzeichen endenerrorLeerzeilen
MD049Hervorhebung-FormatHervorhebung-Formaterroremphasis
MD050starke-FormatvorlageStarke Formatvorlageerroremphasis
suchen-ersetzentodocs-PlatzhalterErfassen von Vorkommen von TODOCS-Platzhaltern.error
suchen-ersetzenDokumente-DomäneErfassen von Vorkommen der docs.github.com-Domäne.error
suchen-ersetzenHilfe-DomäneErfassen von Vorkommen von help.github.com-Domänen.error
suchen-ersetzenVorschau-DomäneErfassen von Vorkommen von preview.ghdocs.com-Domänen.error
suchen-ersetzenDeveloper-DomäneErfassen von Vorkommen von developer.github.com-Domänen.error
suchen-ersetzenveraltete Liquid-Syntax: site.dataErfassen von Vorkommen veralteter Liquid-Datensyntax.error
suchen-ersetzenveraltete Liquid Syntax: Octicon-Die verwendete Okticon-Liquid-Syntax ist veraltet. Verwenden Sie stattdessen das Format octicon "<octicon-name>" aria-label="<Octicon aria label>"error
GH001kein-Standard-alt-TextAlle Bilder müssen mit Alternativtext (alt text) versehen sein.errorBarrierefreiheit, Bilder
GH002kein-generischer-Link-TextVermeiden sie die Verwendung von generischem Link-Text wie Learn more oder Click hereerrorBarrierefreiheit, Links
GHD030Code-Fence-Line-LängeCodefencelinien dürfen keine maximale Länge überschreitenWarnung ladenCode, Barrierefreiheit
GHD032Bild-alt-Text-Ende-InterpunktionAlternativtexte müssen mit einem Satzzeichen endenerrorBarrierefreiheit, Bilder
GHD004Bild-Datei-Kebab-VorgangBilddateinamen müssen kebab-Vorgang verwendenerrorimages
GHD033falsch-alt-Text-LängeAlternativtext für Bilder sollte zwischen 40 und 150 Zeichen lang seinWarnung ladenBarrierefreiheit, Bilder
GHD002internal-Links-nicht-langInterne Links dürfen keinen hartcodierten Sprachcode enthaltenerrorLinks, URL
GHD003internae-Links-SlashInterne Links müssen mit einem / beginnen.errorLinks, URL
GHD031Bild-alt-Text-ausschließen-WörterAlternativer Text für Bilder sollte nicht mit Wörtern wie „Bild“ oder „Grafik“ beginnen.errorBarrierefreiheit, Bilder
GHD034Liste-erstes-Wort-GroßschreibungErstes Wort des Listenelements sollte groß geschrieben werdenWarnung ladenul, ol
GHD001Link-InterpunktionInterne Verlinkungstitel dürfen keine Interpunktion enthaltenerrorLinks, URL
GHD008Vorabzugriff-ReferenzenDateien ohne Vorabzugriff sollten nicht auf Dateien mit Vorabzugriff oder Vorabzugriff verweisen.errorFeature, Vorabzugriff
GHD021Yaml-geplante-AufträgeYAML-Ausschnitte, die geplante Workflows enthalten, dürfen nicht zur vollen Stunde ausgeführt werden und müssen eindeutig sein.errorFeature, Aktionen
GHD006internae-Links-alt-VersionInterne Links dürfen nicht über eine hartcodierte Version mit der alten Versionsverwaltungssyntax verfügen.errorLinks, URL, Versionsverwaltung
GHD005hartcodierte-Daten-VariableZeichenfolgen, die „persönliches Zugriffstoken“ enthalten, sollten stattdessen die Produktvariable verwenden.errorEinzelne-Quelle
GHD013github-eigene-Aktion-VerweiseGitHub-eigene Aktionsverweise sollten nicht hartcodiert seinerrorFeature, Aktionen
GHD016liquid-eingeschlossene-bedingte-ArgBedingte Liquid-Tags sollten das bedingte Argument nicht einschließenerrorliquid, Format
GHD014liquid-Daten-Referenzen-definiertLiquid-Daten oder eingezogene Datenverweise wurden in Inhalten gefunden, die keinen Wert aufweisen oder nicht im Datenverzeichnis vorhanden sind.errorliquid
GHD015liquid-Daten-Tag-FormatLiquid-Daten oder Tags eingezogener Datenverweise müssen korrekt formatiert sein und die richtige Anzahl von Argumenten und Abständen aufweisenerrorliquid, Format
GHD010Frontmatter-verstecke-DokumenteArtikel mit Frontmatter-Eigenschaft hidden können nur in bestimmten Produkten gefunden werdenerrorFrontmatter, Feature, Vorabzugriff
GHD009Frontmatter-Vorabzugriff-ReferenzenDateien ohne Vorabzugriff sollten keinen Frontmatter haben, der auf Vorabzugriff verweist.errorFrontmatter, Feature, Vorabzugriff
GHD011Frontmatter-Video-TranskriptionenVideotranskript muss ordnungsgemäß konfiguriert werden.errorFrontmatter, Feature, Videotranskriptionen
GHD012frontmatter-SchemaFrontmatter muss dem Schema entsprechenerrorFrontmatter, Schema
GHD007Code-AnmerkungenCodeanmerkungen, die in Markdown definiert sind, müssen eine bestimmte Layout-Frontmattereigenschaft enthalten.errorCode, Feature, Anmerkung, Frontmatter
GHD017Frontmatter-Liquid-SyntaxFrontmatter-Eigenschaften müssen gültige Liquid verwendenerrorliquid, Frontmatter
GHD018Liquid-SyntaxMarkdown-Inhalt muss gültige Liquid verwendenerrorliquid
GHD019liquid-wenn-TagsLiquid-ifversion-Tags sollten anstelle von if-Tags verwendet werden, wenn das Argument eine gültige Version ist.errorliquid, Versionsverwaltung
GHD020liquid-ifversion-TagsLiquid–ifversionTags sollten gültige Versionsnamen als Argumente enthalten.errorliquid, Versionsverwaltung
GHD022liquid-ifversion-versionsLiquid ifversion (und elsif) sollte nicht immer wahr seinWarnung ladenliquid, Versionsverwaltung
GHD035RAI-WiederverwendbarkeitRAI-Artikel und wiederverwendbare Elemente können nur auf wiederverwendbare Inhalte im Verzeichnis "data/reusables/rai" verweisen.errorFeature, RAI
GHD036Bild-kein-GIFDas Bild darf kein GIF sein, Referenz im Styleguide: contributing/style-guide-and-content-model/style-guide.md#imageserrorimages
GHD038expired-contentAbgelaufene Inhalte müssen bereinigt werden.errorabgelaufen
GHD039expiring-soonInhalte, die bald ablaufen, sollten proaktiv behandelt werden.Warnung ladenabgelaufen
GHD040Tabelle-liquid-VersionsverwaltungTabellen müssen das richtige Format für die Liquid-Versionsverwaltung verwendenerrortables
GHD041third-party-action-pinningCodebeispiele, die Aktionen von Drittanbietern nutzen, müssen immer an einen Commit-SHA mit voller Länge angeheftet werden.errorFeature, Aktionen

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 is 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.

KommentarEffekt
<!-- markdownlint-disable -->Alle Regeln deaktivieren
<!-- markdownlint-enable -->Alle Regeln aktivieren
<!-- markdownlint-disable-line -->Alle Regeln für die aktuelle Zeile deaktivieren
<!-- markdownlint-disable-next-line -->Alle Regeln für die nächste Zeile deaktivieren
<!-- markdownlint-disable RULE-ONE RULE-TWO -->
<!-- markdownlint-enable RULE-ONE RULE-TWO -->Eine oder mehrere Regeln anhand des Namens aktivieren
<!-- markdownlint-disable-line RULE-NAME -->Eine oder mehrere Regeln anhand des Namens für die aktuelle Zeile deaktivieren
<!-- markdownlint-disable-next-line RULE-NAME -->Eine oder mehrere Regeln anhand des Namens für die nächste Zeile deaktivieren