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.
Regel-ID | Regelname(n) | Beschreibung | severity | Tags |
---|---|---|---|---|
MD001 | Überschrift-Inkrement | Überschriftenebenen sollten jeweils nur um eine Ebene erhöht werden | error | Überschriften |
MD004 | ul-style | Unsortierter Listenstil | error | Aufzählungszeichen, ul |
MD009 | keine-nachfolgenden-Leerzeichen | Nachgestellte Leerzeichen | error | whitespace |
MD011 | keine-umgekehrte-Verknüpfung | Syntax für umgekehrte Verknüpfungen | error | Verknüpfungen |
MD012 | ohne-mehrere-Leerzeichen | Mehrere aufeinander folgende leere Zeilen | error | Leerzeichen, Leerzeilen |
MD014 | Befehle-anzeigen-Ausgabe | Dollarzeichen vor Befehlen ohne Ausgabe verwendet | error | code |
MD018 | kein-fehlendes-Leerzeichen-atx | Kein Leerzeichen nach dem Hash auf der Atx-Formatvorlagenüberschrift | error | Überschriften, Atx, Leerzeichen |
MD019 | ohne-mehrere-Leerzeichen-atx | Mehrere Leerzeichen nach dem Hash auf der Atx-Formatvorlagenüberschrift | error | Überschriften, Atx, Leerzeichen |
MD022 | Leerzeichen um Überschriften | Überschriften sollten von einer einzelnen Leerzeile umgeben sein | error | Überschriften, Leerzeilen |
MD023 | Überschrift-Anfang-links | Überschriften müssen am Zeilenanfang beginnen | error | Überschriften, Leerzeichen |
MD027 | ohne-mehrere-Leerzeichen-Blockzitat | Mehrere Leerzeichen nach einem Blockzitatsymbol | error | Blockzitat, Leerzeichen, Einzug |
MD029 | ol-Präfix | Präfix „Sortiertes Listenelement“ | error | ol |
MD030 | Liste-Marker-Leerzeichen | Leerzeichen nach Listenmarkierungen | error | ol, ul, Leerzeichen |
MD031 | Leerzeichen-um-Fence | Fenced-Code-Blöcke sollten von Leerzeilen umgeben sein | error | Code, Leerzeilen |
MD037 | kein-Leerzeichen-in-Hervorhebung | Leerzeichen innerhalb von Hervorhebungsmarkierungen | error | Leerzeichen, Hervorhebung |
MD039 | kein-Leerzeichen-in-Links | Leerzeichen in Link-Text | error | Leerzeichen, Links |
MD040 | Fenced-Code-Sprache | Fenced Codeblöcke sollten eine angegebene Sprache aufweisen. | error | Code, Sprache |
MD042 | keine-leeren-Links | Keine leeren Links | error | Verknüpfungen |
MD047 | einzeln-nachstehender-Zeichenvorschub | Dateien sollten mit einem einzigen Zeilenvorschubzeichen enden | error | Leerzeilen |
MD049 | Hervorhebung-Format | Hervorhebung-Format | error | emphasis |
MD050 | starke-Formatvorlage | Starke Formatvorlage | error | emphasis |
suchen-ersetzen | todocs-Platzhalter | Erfassen von Vorkommen von TODOCS-Platzhaltern. | error | |
suchen-ersetzen | Dokumente-Domäne | Erfassen von Vorkommen der docs.github.com-Domäne. | error | |
suchen-ersetzen | Hilfe-Domäne | Erfassen von Vorkommen von help.github.com-Domänen. | error | |
suchen-ersetzen | Vorschau-Domäne | Erfassen von Vorkommen von preview.ghdocs.com-Domänen. | error | |
suchen-ersetzen | Developer-Domäne | Erfassen von Vorkommen von developer.github.com-Domänen. | error | |
suchen-ersetzen | veraltete Liquid-Syntax: site.data | Erfassen von Vorkommen veralteter Liquid-Datensyntax. | error | |
suchen-ersetzen | veraltete Liquid Syntax: Octicon- | Die verwendete Okticon-Liquid-Syntax ist veraltet. Verwenden Sie stattdessen das Format octicon "<octicon-name>" aria-label="<Octicon aria label>" | error | |
GH001 | kein-Standard-alt-Text | Alle Bilder müssen mit Alternativtext (alt text) versehen sein. | error | Barrierefreiheit, Bilder |
GH002 | kein-generischer-Link-Text | Vermeiden sie die Verwendung von generischem Link-Text wie Learn more oder Click here | error | Barrierefreiheit, Links |
GHD030 | Code-Fence-Line-Länge | Codefencelinien dürfen keine maximale Länge überschreiten | Warnung laden | Code, Barrierefreiheit |
GHD032 | Bild-alt-Text-Ende-Interpunktion | Alternativtexte müssen mit einem Satzzeichen enden | error | Barrierefreiheit, Bilder |
GHD004 | Bild-Datei-Kebab-Vorgang | Bilddateinamen müssen kebab-Vorgang verwenden | error | images |
GHD033 | falsch-alt-Text-Länge | Alternativtext für Bilder sollte zwischen 40 und 150 Zeichen lang sein | Warnung laden | Barrierefreiheit, Bilder |
GHD002 | internal-Links-nicht-lang | Interne Links dürfen keinen hartcodierten Sprachcode enthalten | error | Links, URL |
GHD003 | internae-Links-Slash | Interne Links müssen mit einem / beginnen. | error | Links, URL |
GHD031 | Bild-alt-Text-ausschließen-Wörter | Alternativer Text für Bilder sollte nicht mit Wörtern wie „Bild“ oder „Grafik“ beginnen. | error | Barrierefreiheit, Bilder |
GHD034 | Liste-erstes-Wort-Großschreibung | Erstes Wort des Listenelements sollte groß geschrieben werden | Warnung laden | ul, ol |
GHD001 | Link-Interpunktion | Interne Verlinkungstitel dürfen keine Interpunktion enthalten | error | Links, URL |
GHD008 | Vorabzugriff-Referenzen | Dateien ohne Vorabzugriff sollten nicht auf Dateien mit Vorabzugriff oder Vorabzugriff verweisen. | error | Feature, Vorabzugriff |
GHD021 | Yaml-geplante-Aufträge | YAML-Ausschnitte, die geplante Workflows enthalten, dürfen nicht zur vollen Stunde ausgeführt werden und müssen eindeutig sein. | error | Feature, Aktionen |
GHD006 | internae-Links-alt-Version | Interne Links dürfen nicht über eine hartcodierte Version mit der alten Versionsverwaltungssyntax verfügen. | error | Links, URL, Versionsverwaltung |
GHD005 | hartcodierte-Daten-Variable | Zeichenfolgen, die „persönliches Zugriffstoken“ enthalten, sollten stattdessen die Produktvariable verwenden. | error | Einzelne-Quelle |
GHD013 | github-eigene-Aktion-Verweise | GitHub-eigene Aktionsverweise sollten nicht hartcodiert sein | error | Feature, Aktionen |
GHD016 | liquid-eingeschlossene-bedingte-Arg | Bedingte Liquid-Tags sollten das bedingte Argument nicht einschließen | error | liquid, Format |
GHD014 | liquid-Daten-Referenzen-definiert | Liquid-Daten oder eingezogene Datenverweise wurden in Inhalten gefunden, die keinen Wert aufweisen oder nicht im Datenverzeichnis vorhanden sind. | error | liquid |
GHD015 | liquid-Daten-Tag-Format | Liquid-Daten oder Tags eingezogener Datenverweise müssen korrekt formatiert sein und die richtige Anzahl von Argumenten und Abständen aufweisen | error | liquid, Format |
GHD010 | Frontmatter-verstecke-Dokumente | Artikel mit Frontmatter-Eigenschaft hidden können nur in bestimmten Produkten gefunden werden | error | Frontmatter, Feature, Vorabzugriff |
GHD009 | Frontmatter-Vorabzugriff-Referenzen | Dateien ohne Vorabzugriff sollten keinen Frontmatter haben, der auf Vorabzugriff verweist. | error | Frontmatter, Feature, Vorabzugriff |
GHD011 | Frontmatter-Video-Transkriptionen | Videotranskript muss ordnungsgemäß konfiguriert werden. | error | Frontmatter, Feature, Videotranskriptionen |
GHD012 | frontmatter-Schema | Frontmatter muss dem Schema entsprechen | error | Frontmatter, Schema |
GHD007 | Code-Anmerkungen | Codeanmerkungen, die in Markdown definiert sind, müssen eine bestimmte Layout-Frontmattereigenschaft enthalten. | error | Code, Feature, Anmerkung, Frontmatter |
GHD017 | Frontmatter-Liquid-Syntax | Frontmatter-Eigenschaften müssen gültige Liquid verwenden | error | liquid, Frontmatter |
GHD018 | Liquid-Syntax | Markdown-Inhalt muss gültige Liquid verwenden | error | liquid |
GHD019 | liquid-wenn-Tags | Liquid-ifversion -Tags sollten anstelle von if -Tags verwendet werden, wenn das Argument eine gültige Version ist. | error | liquid, Versionsverwaltung |
GHD020 | liquid-ifversion-Tags | Liquid–ifversion Tags sollten gültige Versionsnamen als Argumente enthalten. | error | liquid, Versionsverwaltung |
GHD022 | liquid-ifversion-versions | Liquid ifversion (und elsif ) sollte nicht immer wahr sein | Warnung laden | liquid, Versionsverwaltung |
GHD035 | RAI-Wiederverwendbarkeit | RAI-Artikel und wiederverwendbare Elemente können nur auf wiederverwendbare Inhalte im Verzeichnis "data/reusables/rai" verweisen. | error | Feature, RAI |
GHD036 | Bild-kein-GIF | Das Bild darf kein GIF sein, Referenz im Styleguide: contributing/style-guide-and-content-model/style-guide.md#images | error | images |
GHD038 | expired-content | Abgelaufene Inhalte müssen bereinigt werden. | error | abgelaufen |
GHD039 | expiring-soon | Inhalte, die bald ablaufen, sollten proaktiv behandelt werden. | Warnung laden | abgelaufen |
GHD040 | Tabelle-liquid-Versionsverwaltung | Tabellen müssen das richtige Format für die Liquid-Versionsverwaltung verwenden | error | tables |
GHD041 | third-party-action-pinning | Codebeispiele, die Aktionen von Drittanbietern nutzen, müssen immer an einen Commit-SHA mit voller Länge angeheftet werden. | error | Feature, 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–table
Element 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.
Kommentar | Effekt |
---|---|
<!-- 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 |