À propos de linter de contenu pour GitHub Docs
Notre linter de contenu applique des règles de guide de style dans notre contenu Markdown.
Le linter utilise markdownlint
comme infrastructure pour effectuer des vérifications, signaler des défauts et corriger automatiquement le contenu, dans la mesure du possible. Cette infrastructure exécute de manière flexible des règles spécifiques, fournit des messages d’erreur descriptifs et corrige les erreurs. Le linter de contenu GitHub Docs utilise plusieurs règles existantes markdownlint
et des règles personnalisées supplémentaires pour vérifier le contenu Markdown dans nos répertoires content
etdata
. Nos règles personnalisées implémentent des vérifications qui ne sont pas encore disponibles dans l’infrastructure markdownlint
ou qui sont spécifiques au contenu GitHub Docs. Les règles vérifient la syntaxe pour Markdown et Liquid.
Exécution du linter de contenu GitHub Docs
Le linter de contenu GitHub Docs s’exécute automatiquement lors de la pré-validation, mais vous pouvez également l’exécuter manuellement.
Exécuter automatiquement linter lors de la pré-validation
Quand vous écrivez du contenu localement et que vous validez des fichiers à l’aide de la ligne de commande, ces fichiers mis en scène sont automatiquement lintés par le linter de contenu. Les avertissements et les erreurs sont signalés, mais seules les erreurs empêchent la fin de votre validation.
Si des erreurs sont signalées, votre validation ne se terminera pas. Vous devrez corriger les erreurs signalées, rajouter les fichiers modifiés et valider de nouveau vos modifications. Toutes les erreurs signalées doivent être corrigées pour empêcher l’introduction d’erreurs qui ne respectent pas le guide de style GitHub Docs dans le contenu. Si des avertissements sont signalés, vous pouvez éventuellement choisir de les corriger ou non.
Quand vous écrivez du contenu localement, il existe plusieurs règles que vous pouvez corriger automatiquement à l’aide de la ligne de commande. Si vous souhaitez corriger automatiquement les erreurs qui peuvent être corrigées, consultez « Corriger automatiquement les erreurs qui peuvent être corrigées ».
Si vous modifiez un fichier dans l’interface utilisateur GitHub, vous ne pourrez pas corriger automatiquement les erreurs ou exécuter le linter sur un engagement, mais vous obtiendrez un échec de CI si le contenu enfreint des règles avec une gravité de error
.
Exécuter manuellement le linter
Exécuter le linter sur des fichiers intermédiaires et modifiés
Utilisez la commande suivante pour exécuter le linter localement sur vos fichiers intermédiaires et modifiés. Il génère les deux défauts graves, warning
et error
.
npm run lint-content
Exécuter le linter sur les fichiers intermédiaires et modifiés et signaler uniquement les erreurs
Utilisez la commande suivante pour exécuter le linter localement sur vos fichiers intermédiaires et modifiés et signalez uniquement les défauts graves error
.
npm run lint-content -- --errors
Exécuter le linter sur des fichiers ou des répertoires spécifiques
Utilisez la commande suivante pour exécuter le linter localement sur des fichiers ou des répertoires spécifiques. Séparez plusieurs filtres par un espace. Vous pouvez inclure des fichiers et des répertoires dans la même commande.
npm run lint-content -- \ --paths content/FILENAME.md content/DIRECTORY
npm run lint-content -- \
--paths content/FILENAME.md content/DIRECTORY
Corriger automatiquement les erreurs qui peuvent être corrigées
Si une erreur a fixable: true
dans sa description, vous pouvez utiliser les commandes suivantes pour les corriger automatiquement.
Exécutez cette commande pour corriger uniquement les fichiers intermédiaires et modifiés :
npm run lint-content -- --fix
Exécutez cette commande pour corriger des fichiers ou des répertoires spécifiques :
npm run lint-content -- \
--fix --paths content/FILENAME.md content/DIRECTORY
Exécuter un ensemble spécifique de règles linter
Utilisez la commande suivante pour exécuter une ou plusieurs règles linter spécifiques. Ces exemples exécutent les règles heading-increment
et code-fence-line-length
. Remplacez heading-increment code-fence-line-length
par un ou plusieurs alias linter que vous souhaitez exécuter. Pour afficher la liste des règles linter que vous pouvez passer à cette option, exécutez npm run lint-content -- --help
. Vous pouvez utiliser le nom court (par exemple, MD001
) ou le nom long (par exemple, heading-increment
) d’une règle linter.
Exécutez les règles linter spécifiées sur tous les fichiers intermédiaires et modifiés :
npm run lint-content -- \
--rules heading-increment code-fence-line-length
Exécutez les règles linter spécifiées sur des fichiers ou des répertoires spécifiques :
npm run lint-content -- \
--rules heading-increment code-fence-line-length \
--path content/FILENAME.md content/DIRECTORY
Contourner le hook de validation
Si le linter détecte des erreurs que vous n'avez pas introduites, vous pouvez contourner le hook de validation de git en utilisant l'--no-verify
option lors de la validation de vos modifications.
git commit -m 'MESSAGE' --no-verify
Afficher le menu d’aide pour le script linter de contenu
npm run lint-content -- --help
Règles de linting
Chaque règle est configurée dans un fichier dans src/content-linter/style
, où les gravités des règles sont définies.
Les erreurs doivent être traitées avant de fusionner vos modifications dans la branche main
. Les avertissements doivent être traités, mais n’empêchent pas la fusion d’une modification dans la branche main
. La plupart des règles seront finalement promues en erreurs, quand le contenu n’a plus de violations d’avertissement.
Identificateur de la règle | Nom(s) de la règle | Description | Gravité | Balises |
---|---|---|---|---|
MD001 | heading-increment | Les niveaux de titre ne doivent incrémenter qu’un seul niveau à la fois | error | titres |
MD004 | ul-style | Style de liste non ordonné | error | puce, ul |
MD009 | no-trailing-spaces | Espaces de fin | error | whitespace |
MD011 | no-reversed-links | Syntaxe de lien inversé | error | liens |
MD012 | no-multiple-blanks | Plusieurs lignes vides consécutives | error | espace blanc, blank_lines |
MD014 | commands-show-output | Les signes dollar utilisés avant les commandes sans afficher la sortie | error | code |
MD018 | no-missing-space-atx | Aucun espace après hachage sur le titre de style atx | error | titres, atx, espaces |
MD019 | no-multiple-space-atx | Plusieurs espaces après hachage sur le titre de style atx | error | titres, atx, espaces |
MD022 | blanks-around-headings | Les titres doivent être entourés de lignes vides | error | titres, blank_lines |
MD023 | heading-start-left | Les titres doivent commencer au début de la ligne | error | titres, espaces |
MD027 | no-multiple-space-blockquote | Plusieurs espaces après le symbole blockquote | error | blockquote, espace blanc, retrait |
MD029 | ol-prefix | Préfixe d’élément de liste ordonné | error | ol |
MD030 | list-marker-space | Espaces après les marqueurs de liste | error | ol, ul, espace blanc |
MD031 | blanks-around-fences | Les blocs de code clôturés doivent être entourés de lignes vides | error | code, blank_lines |
MD037 | no-space-in-emphasis | Espaces à l’intérieur des marqueurs d’accentuation | error | espace blanc, accentuation |
MD039 | no-space-in-links | Espaces à l’intérieur du texte du lien | error | espaces blancs, liens |
MD040 | fenced-code-language | Les blocs de code délimités doivent avoir une langue spécifiée | error | code, langages |
MD042 | no-empty-links | Aucun lien vide | error | liens |
MD047 | single-trailing-newline | Les fichiers doivent se terminer par un caractère nouvelle ligne unique | error | blank_lines |
MD049 | emphasis-style | Style d’accentuation | error | emphasis |
MD050 | strong-style | Style fort | error | emphasis |
search-replace | todocs-placeholder | Interceptez les occurrences de l’espace réservé TODOCS. | error | |
search-replace | docs-domain | Interceptez les occurrences de domaine docs.gitub.com. | error | |
search-replace | help-domain | Interceptez les occurrences de domaine help.github.com. | error | |
search-replace | preview-domain | Interceptez les occurrences de domaine preview.ghdocs.com. | error | |
search-replace | developer-domain | Interceptez les occurrences de domaine developer.github.com. | error | |
search-replace | syntaxe liquid déconseillée : site.data | Interceptez les occurrences de syntaxe de données liquid dépréciées. | error | |
search-replace | syntaxe liquid déconseillée : octicon- | La syntaxe liquid octicon utilisée est déconseillée. Utilisez ce format à la place octicon "<octicon-name>" aria-label="<Octicon aria label>" | error | |
GH001 | no-default-alt-text | Les images doivent avoir un texte de remplacement significatif (texte de remplacement) | error | accessibilité, images |
GH002 | no-generic-link-text | Évitez d’utiliser du texte de lien générique comme Learn more ou Click here | error | Accessibilité, liens |
GHD030 | code-fence-line-length | Les lignes délimitées de code ne doivent pas dépasser une longueur maximale | avertissement | code, accessibilité |
GHD032 | image-alt-text-end-punctuation | Le texte de remplacement des images doit se terminer par une ponctuation | error | accessibilité, images |
GHD004 | image-file-kebab-case | Les noms de fichiers image doivent utiliser kebab-case | error | images |
GHD033 | incorrect-alt-text-length | Le texte de remplacement des images doit contenir entre 40 et 150 caractères | avertissement | accessibilité, images |
GHD002 | internal-links-no-lang | Les liens internes ne doivent pas contenir de code de langage codé en dur | error | liens, url |
GHD003 | internal-links-slash | Les liens internes doivent commencer par un / | error | liens, url |
GHD031 | image-alt-text-exclude-words | Le texte de remplacement des images ne doit pas commencer par des mots tels que « image » ou « graphique » | error | accessibilité, images |
GHD034 | list-first-word-capitalization | Le premier mot de l’élément de liste doit être capitalisé | avertissement | ul, ol |
GHD001 | link-punctuation | Les titres de liens internes ne doivent pas contenir de ponctuation | error | liens, url |
GHD008 | early-access-references | Les fichiers qui ne sont pas en accès anticipé ne doivent pas référencer l’accès anticipé ou les fichiers d’accès anticipé | error | caractéristiques, accès anticipé |
GHD021 | yaml-scheduled-jobs | Les extraits de code YAML qui incluent des flux de travail planifiés ne doivent pas s’exécuter à l’heure et doivent être uniques | error | Caractéristiques, actions |
GHD006 | internal-links-old-version | Les liens internes ne doivent pas contenir de version codée en dur à l’aide de l’ancienne syntaxe de contrôle de version | error | liens, URL, contrôle de version |
GHD005 | hardcoded-data-variable | Les chaînes qui contiennent un « jeton d’accès personnel » doivent utiliser la variable de produit à la place | error | single-source |
GHD013 | github-owned-action-references | Les références d’action appartenant à GitHub ne doivent pas être codées en dur | error | Caractéristiques, actions |
GHD016 | liquid-quoted-conditional-arg | Les balises conditionnelles liquid ne doivent pas citer l’argument conditionnel | error | liquid, format |
GHD014 | liquid-data-references-defined | Les données liquid ou les références de données mises en retrait ont été trouvées dans le contenu qui pourvu d’aucune valeur ou n’existent pas dans l’annuaire de données | error | liquid |
GHD015 | liquid-data-tag-format | Les balises de référence de données liquid ou de données mises en retrait doivent être correctement formatées et contenir le nombre correct d’arguments et d’espacement | error | liquid, format |
GHD010 | frontmatter-hidden-docs | Les articles ayant la propriété frontmatter hidden ne peuvent être situés que dans des produits spécifiques | error | frontmatter, caractéristiques, accès anticipé |
GHD009 | frontmatter-early-access-references | Les fichiers qui ne sont pas en accès anticipé ne doivent pas avoir de frontmatter qui référencent un accès anticipé | error | frontmatter, caractéristiques, accès anticipé |
GHD011 | frontmatter-video-transcripts | La transcription vidéo doit être configurée correctement | error | frontmatter, caractéristiques, transcriptions vidéo |
GHD012 | frontmatter-schema | Frontmatter doit être conforme au schéma | error | frontmatter, schéma |
GHD007 | code-annotations | Les annotations de code définies dans Markdown doivent contenir une propriété frontmatter de disposition spécifique | error | code, caractéristiques, annoter, frontmatter |
GHD017 | frontmatter-liquid-syntax | Les propriétés frontmatter doivent utiliser liquid valide | error | liquid, frontmatter |
GHD018 | liquid-syntax | Le contenu Markdown doit utiliser liquid valide | error | liquid |
GHD019 | liquid-if-tags | Les balises liquid ifversion doivent être utilisées au lieu de balises if quand l’argument est une version valide | error | liquid, contrôle de version |
GHD020 | liquid-ifversion-tags | Les balises liquid ifversion doivent contenir des noms de version valides en tant qu’arguments | error | liquid, contrôle de version |
GHD022 | liquid-ifversion-versions | Liquid ifversion (et elsif ) ne doit pas toujours être vrai | avertissement | liquid, contrôle de version |
GHD035 | rai-reusable-usage | Les articles et les éléments réutilisables RAI ne peuvent référencer que du contenu réutilisable dans le répertoire data/réutilisables/rai | error | feature, rai |
GHD036 | image-no-gif | L’image ne doit pas être un gif, référence du guide de style : contributing/style-guide-and-content-model/style-guide.md#images | error | images |
GHD038 | expired-content | Le contenu expiré doit être corrigé. | error | expiré |
GHD039 | expire bientôt | Le contenu qui expire bientôt devrait être résolu de manière proactive. | avertissement | expiré |
GHD040 | table, liquide, contrôle de version | Les tables doivent utiliser le bon format de contrôle de version liquide | error | dans des tables |
GHD041 | épinglage-tiers-action | Exemples de code qui utilisent des actions tierces doivent toujours être épinglés à un SHA de commit complet | error | Caractéristiques, actions |
Syntaxe des règles de linting
Certaines règles de linting retournent des avertissements ou des erreurs basés sur des commentaires HTML que vous pouvez ajouter à des articles.
Syntaxe pour l’expiration et l’expiration du contenu
Les règles GHD038
et GHD039
vérifient le contenu auquel une date d'expiration a été attribuée manuellement. Quatorze jours avant la date spécifiée, le linter de contenu renvoie un avertissement indiquant que le contenu expire bientôt. À compter de la date spécifiée, le linter de contenu retourne une erreur et signale le contenu pour la correction.
Vous pouvez ajouter une date d'expiration au contenu en l’encapsulant dans des balises HTML qui contiennent une date d'expiration au format : <!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->
Utiliser :
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.
Remarque : si vous placez les balises périmées dans un élément HTML table
, assurez-vous que la balise entoure toute la ligne et pas seulement la cellule. Par exemple :
<!-- 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 -->
Suppression des règles de linter
Rarement, vous devrez peut-être documenter quelque chose qui enfreint une ou plusieurs règles de linter. Dans ces cas, vous pouvez supprimer des règles en ajoutant un commentaire au fichier Markdown. Vous pouvez désactiver toutes les règles ou règles spécifiques. Essayez toujours de limiter autant de règles que possible. Vous pouvez désactiver une règle pour un fichier entier, pour une section d’un fichier Markdown, une ligne spécifique ou la ligne suivante.
Par exemple, si vous écrivez un article qui inclut l’expression régulière (^|/)[Cc]+odespace/
qui examine la syntaxe des liens inversés, il déclenche la règle MD011
qui examine les liens inversés. Vous pouvez désactiver la règle MD011
sur cette ligne spécifique en ajoutant le commentaire suivant.
(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->
Si la ligne que vous essayez d’ignorer se trouve dans un bloc de code, vous pouvez ignorer ce bloc de code en l’entourant des commentaires suivants.
<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->
Vous pouvez utiliser ces commentaires pour activer ou désactiver des règles.
Commentaire | Effet |
---|---|
<!-- markdownlint-disable --> | Désactiver toutes les règles |
<!-- markdownlint-enable --> | Activer toutes les règles |
<!-- markdownlint-disable-line --> | Désactiver toutes les règles de la ligne actuelle |
<!-- markdownlint-disable-next-line --> | Désactiver toutes les règles de la ligne suivante |
<!-- markdownlint-disable RULE-ONE RULE-TWO --> | |
<!-- markdownlint-enable RULE-ONE RULE-TWO --> | Activer une ou plusieurs règles par nom |
<!-- markdownlint-disable-line RULE-NAME --> | Désactiver une ou plusieurs règles par nom pour la ligne active |
<!-- markdownlint-disable-next-line RULE-NAME --> | Désactiver une ou plusieurs règles par nom pour la ligne suivante |