Utilisation de l'analyseur de contenu

Présentation de l'analyseur de contenu de GitHub Docs

Notre linter de contenu applique des règles du guide stylistique dans nos contenus 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 le linter avant la validation

Lorsque vous rédigez du contenu localement et validez des fichiers via la ligne de commande, ces fichiers mis en scène seront automatiquement analysé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 de GitHub, vous ne pourrez pas corriger automatiquement les erreurs ou exécuter le linter sur un commit, mais vous recevrez un échec de CI si le contenu enfreint des règles d'un niveau de gravité de error.

Exécuter manuellement le linter

Exécutez le linter sur les fichiers mis en scène et modifiés.

Utilisez la commande suivante pour exécuter le linter localement sur vos fichiers mis en scène et modifiés. Il affichera à la fois les warning et error défauts de gravité.

npm run lint-content

Exécutez le linter sur les fichiers mis en scène et modifiés et ne signalez que les erreurs

Utilisez la commande suivante pour exécuter le linter localement sur vos fichiers mis en scène et modifiés, et ne signaler que les error défauts de gravité.

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 chemins 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écutez un ensemble spécifique de règles du 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. Remplacezheading-increment code-fence-line-lengthpar un ou plusieurs alias du linter que vous souhaitez exécuter. Pour voir la liste des règles du linter que vous pouvez passer à cette option, exécuteznpm 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 du linter spécifiées sur tous les fichiers mis en scène 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

Contournez le hook de commit.

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-verifyoption 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 niveaux de gravité des règles sont définis.

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, une fois que le contenu ne comportera plus de violations signalées comme avertissements.

          [MD001](https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md001.md) | heading-increment | Les niveaux de titre ne doivent augmenter que d'un niveau à la fois | erreur | titres |

| MD011 | no-reversed-links | Syntaxe de lien inversée | erreur | liens | | MD014 | commands-show-output | Signes dollar utilisés avant des commandes sans afficher la sortie | erreur | code | | MD018 | no-missing-space-atx | Aucun espace après le dièse dans un titre de style atx | erreur | titres, atx, espaces | | MD019 | no-multiple-space-atx | Espaces multiples après le dièse dans un titre de style atx | erreur | titres, atx, espaces | | MD023 | heading-start-left | Les titres doivent commencer au début de la ligne | erreur | titres, espaces | | MD027 | no-multiple-space-blockquote | Espaces multiples après le symbole de bloc de citation | erreur | bloc de citation, espace blanc, indentation | | MD029 | ol-prefix | Préfixe d'élément de liste ordonnée | erreur | ol | | MD030 | list-marker-space | Espaces après les marqueurs de liste | erreur | ol, ul, espaces blancs | | MD031 | blanks-around-fences | Les blocs de code délimités doivent être entourés de lignes vides | erreur | code, lignes_vides | | MD037 | no-space-in-emphasis | Espaces à l'intérieur des marqueurs d'emphase | erreur | espaces blancs, emphase | | MD039 | no-space-in-links | Espaces à l'intérieur du texte du lien | erreur | espaces blancs, liens | | MD040 | fenced-code-language | Les blocs de code délimités doivent spécifier un langage | erreur | code, langage | | MD042 | no-empty-links | Aucun lien vide | erreur | liens | | MD050 | strong-style | Style de mise en évidence forte | erreur | emphase | | GH001 | no-default-alt-text | Les images doivent avoir un texte de remplacement pertinent (texte alt) | erreur | accessibilité, images | | GH002 | no-generic-link-text | Évitez d'utiliser un texte de lien générique comme Learn more ou Click here | erreur | accessibilité, liens | | GHD001 | link-punctuation | Les titres de lien internes ne doivent pas contenir de ponctuation | erreur | liens, url | | GHD002 | internal-links-no-lang | Les liens internes ne doivent pas avoir de code de langue codé en dur | erreur | liens, url | | GHD003 | internal-links-slash | Les liens internes doivent commencer par un / | erreur | liens, url | | GHD004 | image-file-kebab-case | Les noms de fichiers d'image doivent utiliser le kebab-case | erreur | images | | GHD005 | hardcoded-data-variable | Les chaînes qui contiennent « personal access token » doivent utiliser la variable de produit à la place | erreur | single-source | | GHD006 | internal-links-old-version | Les liens internes ne doivent pas avoir de version codée en dur avec une ancienne syntaxe de gestion des versions | erreur | liens, url, gestion des versions | | GHD007 | code-annotations | Les annotations de code définies en Markdown doivent contenir une propriété frontmatter de disposition spécifique | erreur | code, fonctionnalité, annotation, frontmatter | | GHD008 | early-access-references | Les fichiers qui ne sont pas en accès anticipé ne doivent pas référencer early-access ou des fichiers early-access | erreur | fonctionnalité, 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érence early-access | erreur | frontmatter, fonctionnalité, accès anticipé | | GHD010 | frontmatter-hidden-docs | Les articles avec la propriété frontmatter hidden ne peuvent se trouver que dans des produits spécifiques | erreur | frontmatter, fonctionnalité, accès anticipé | | GHD012 | frontmatter-schema | Le frontmatter doit être conforme au schéma | erreur | frontmatter, schéma | | GHD013 | github-owned-action-references | Les références d’action appartenant à GitHub ne doivent pas être codées en dur | erreur | fonctionnalité, actions | | GHD014 | liquid-data-references-defined | Des références Liquid data ou indented data ont été trouvées dans du contenu qui n'a pas de valeur ou n'existe pas dans le répertoire data | erreur | liquid | | GHD015 | liquid-data-tag-format | Les balises de références Liquid data ou indented data doivent être correctement formatées et avoir le nombre correct d'arguments et d'espacements | erreur | liquide, format | | GHD016 | liquid-quoted-conditional-arg | Les balises conditionnelles Liquid ne doivent pas mettre l'argument conditionnel entre guillemets | erreur | liquide, format | | GHD017 | frontmatter-liquid-syntax | Les propriétés frontmatter doivent utiliser un Liquid valide | erreur | liquid, frontmatter | | GHD018 | liquid-syntax | Le contenu Markdown doit utiliser un Liquid valide | erreur | liquid | | GHD019 | liquid-if-tags | Les balises Liquid ifversion doivent être utilisées au lieu des balises if lorsque l'argument est une version valide | erreur | liquid, gestion des versions | | GHD020 | liquid-ifversion-tags | Les balises Liquid ifversion doivent contenir des noms de version valides en tant qu'arguments | erreur | liquid, gestion des versions | | GHD021 | yaml-scheduled-jobs | Les extraits YAML qui incluent des workflows planifiés ne doivent pas s'exécuter à l'heure pile et doivent être uniques | erreur | fonctionnalité, actions | | GHD022 | liquid-ifversion-versions | Les balises Liquid ifversion, elsif et else doivent être valides et ne pas contenir de versions non prises en charge. | erreur | liquid, gestion des versions | | GHD031 | image-alt-text-exclude-words | Le texte de remplacement des images ne doit pas commencer par des mots comme « image » ou « graphic » | erreur | accessibilité, images | | GHD032 | image-alt-text-end-punctuation | Le texte de remplacement des images doit se terminer par une ponctuation | erreur | accessibilité, images | | GHD033 | incorrect-alt-text-length | Le texte de remplacement des images doit comporter entre 40 et 150 caractères | erreur | accessibilité, images | | GHD034 | frontmatter-curly-quotes | Le titre et l’introduction du frontmatter ne doivent pas contenir de guillemets typographiques | erreur | frontmatter, format | | GHD035 | rai-reusable-usage | Les articles et ressources réutilisables RAI ne peuvent référencer que du contenu réutilisable dans le répertoire data/reusables/rai | erreur | fonctionnalité, 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 | erreur | images | | GHD038 | expired-content | Le contenu expiré doit être corrigé. | avertissement | expiré | | GHD039 | expiring-soon | Le contenu qui expire bientôt doit être traité de manière proactive. | avertissement | expiré | | GHD040 | table-liquid-versioning | Les tableaux doivent utiliser le bon format de versioning Liquid | erreur | tables | | GHD041 | third-party-action-pinning | Les exemples de code qui utilisent des actions tierces doivent toujours épingler un SHA de commit complet | erreur | fonctionnalité, actions | | GHD042 | liquid-tag-whitespace | Les balises Liquid doivent commencer et se terminer par un seul espace blanc. Les arguments des balises Liquid doivent être séparés par un seul espace blanc. | erreur | liquide, format | | GHD043 | link-quotation | Les titres de lien internes ne doivent pas être entourés de guillemets | erreur | liens, url | | GHD045 | code-annotation-comment-spacing | Les commentaires de code dans les blocs d'annotation doivent avoir exactement un espace après le ou les caractères de commentaire | erreur | code, commentaires, annotation, espacement | | GHD046 | outdated-release-phase-terminology | La terminologie de la phase de publication obsolète doit être remplacée par la terminologie actuelle GitHub | erreur | terminologie, cohérence, release-phases | | GHD047 | table-column-integrity | Les tableaux doivent avoir un nombre de colonnes cohérent sur toutes les lignes | erreur | tableaux, accessibilité, mise en forme | | GHD051 | frontmatter-versions-whitespace | Le frontmatter Versions ne doit pas contenir d'espaces blancs inutiles | erreur | frontmatter, versions | | GHD054 | third-party-actions-reusable | Les exemples de code avec des actions tierces doivent inclure un avertissement réutilisable | erreur | actions, réutilisable, tiers | | GHD056 | frontmatter-landing-carrousels | Seules les pages d’accueil peuvent avoir des carrousels, il ne doit y avoir aucun article en double, et tous les articles doivent exister | erreur | frontmatter, page de destination, carrousels | | GHD057 | ctas-schema | Les URL CTA doivent être conformes au schéma | erreur | ctas, schéma, URL | | GHD058 | journey-tracks-liquid | Les propriétés de suivi de parcours doivent utiliser la syntaxe Liquid valide | erreur | frontmatter, journey-tracks, liquid | | GHD059 | journey-tracks-guide-path-exists | Les chemins d’accès au suivi du parcours doivent référencer des fichiers de contenu existants | erreur | frontmatter, journey-tracks | | GHD060 | journey-tracks-unique-ids | Les ID de suivi de parcours doivent être uniques dans une page | erreur | frontmatter, journey-tracks, unique-ids | | GHD061 | frontmatter-hero-image | Les chemins d'image hero doivent être absolus, sans extension, et pointer vers des images valides dans /assets/images/banner-images/ | erreur | préface, images | | GHD062 | frontmatter-intro-links | les clés introLinks doivent être des clés valides définies dans les données/ui.yml sous product_landing | erreur | Préface, source unique | | GHD063 | frontmatter-children | Des frontmatter enfants doivent exister. Prend en charge les chemins relatifs et les chemins /content/ absolus pour l’inclusion entre produits. | erreur | frontmatter, enfants | | GHD064 | rai-app-card-structure | Les articles sur les cartes d’application/plateforme RAI doivent suivre la structure de modèle requise | avertissement | fonctionnalité, rai | | GHD065 | frontmatter-content-type | Les fichiers de contenu dans les répertoires de type contenu doivent avoir une propriété frontmatter contentType qui correspond au répertoire parent. | erreur | frontmatter, content-type | | GHD066 | frontmatter-docs-team-metrics | Les articles dont le chemin contient une valeur docsTeamMetrics doivent inclure cette valeur dans leur propriété frontmatter docsTeamMetrics. | erreur | frontmatter, docs-team-metrics | | search-replace | Syntaxe liquid obsolète : octicon- | La syntaxe Liquid octicon utilisée est obsolète. Utilisez ce format à la place octicon "<octicon-name>" aria-label="<Octicon aria label>" | erreur | | | search-replace | Syntaxe liquid obsolète : syntax: site.data | Détecter les occurrences de la syntaxe Liquid data obsolète. | erreur | | | search-replace | developer-domain | Détecter les occurrences du domaine developer.github.com. | erreur | | | search-replace | docs-domain | Détecter les occurrences du domaine docs.github.com. | erreur | | | search-replace | help-domain | Détecter les occurrences du domaine help.github.com. | erreur | | | search-replace | todocs-placeholder | Détecter les occurrences de l'espace réservé TODOCS. | erreur | |

Syntaxe des règles de linting

Certaines règles de linting renvoient des avertissements ou des erreurs en fonction des commentaires HTML que vous pouvez ajouter aux articles.

Syntaxe pour le contenu expirant et expiré

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 renverra un avertissement indiquant que le contenu arrive bientôt à expiration. À compter de la date spécifiée, le linter de contenu renverra un avertissement et signalera le contenu à corriger.

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 en cours de clôture 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 pourriez avoir besoin de documenter quelque chose qui enfreint une ou plusieurs règles du 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.