Utilisation des informations préliminaires YAML

Vous pouvez utiliser les informations préliminaires YAML pour définir le contrôle de version, ajouter des métadonnées et contrôler la disposition des articles.

Dans cet article

À propos des informations préliminaires YAML

Les informations préliminaires YAML sont une convention de création popularisée par Jekyll qui permet d’ajouter des métadonnées aux pages. Il s’agit d’un bloc de contenu clé-valeur qui se trouve en haut de chaque fichier Markdown dans GitHub Docs. Pour plus d’informations, consultez ladocumentation sur les informations préliminaires YAML.

Valeurs d’informations préliminaires YAML

Les valeurs d’informations préliminaires suivantes ont des significations et des exigences spéciales pour GitHub Docs. Il existe également un schéma qui est utilisé par la suite de tests pour valider les informations préliminaires de chaque page. Pour plus d’informations, consultezlib/frontmatter.ts.

versions

  • Objectif : indiquer lesversions auxquelles une page s’applique. Pour plus d’informations sur les différents types de contrôle de version, consultez laDocumentation sur le contrôle de version.
  • Entrez :Object. Les clés autorisées sont mappées aux noms de produits et sont disponibles dans l’objetversions danslib/frontmatter.ts.
  • Cette valeur d’informations préliminaires est actuellementrequise pour toutes les pages.
  • Le symbole* est utilisé pour indiquer toutes les releases de la version.
  • Doit être présent pour tous les fichiersindex.md, mais la valeur réelle est calculée au moment du runtime en fonction des enfants.

Cette valeur d’informations préliminaires est utilisée par le site docs pour générer des « permalinks » pour chaque version d’un article. Pour plus d’informations, consultezPermalinks.

Exemple qui s’applique aux Free, Pro et Team et GitHub Enterprise Server version 3.11 et ultérieures :

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=3.11'

Exemple qui s’applique uniquement aux GitHub Enterprise Server :

title: Downloading your license
versions:
  ghes: '*'

Vous pouvez également contrôler la version d'une page dans une plage de versions. Ceci contrôlerait la version de la page pour Free, Pro et Team, et et uniquement les versions 3.1 et 3.2 de GitHub Enterprise Server :

versions:
  fpt: '*'
  ghes: '>=3.1 <3.3'

redirect_from

  • Objectif : répertorier les URL qui doivent être redirigées vers cette page.
  • Entrez :Array
  • Facultatif

Exemple :

title: Getting started with GitHub Desktop
redirect_from:
  - /articles/first-launch
  - /articles/error-github-enterprise-version-is-too-old
  - /articles/getting-started-with-github-for-windows

Pour plus d’informations, consultez « Configurer des redirections ».

title

  • Objectif : définir un titre convivial pour une utilisation dans la balise<title> de la page affichée et un élémenth1 en haut de la page.
  • Entrez :String
  • Obligatoire.

shortTitle

  • Objectif : variante abrégée du titre de page à utiliser dans les barres de navigation et les éléments de navigation.
  • Entrez :String
  • facultatif. En cas d’omission,title sera utilisé.
Type de l'articleNombre maximal de caractères
articles31
categories27
thématiques30

Exemple :

title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects

intro

  • Objectif : définir l’introduction de la page. Cette chaîne sera affichée après letitle.
  • Entrez :String
  • facultatif.

permissions

  • Objectif : définir l’instruction d’autorisation de l’article. Cette chaîne sera affichée après leintro.
  • Entrez :String
  • facultatif.

product

  • Objectif : définir l’encadré de produits pour l’article. Cette chaîne sera affichée après les instructionsintro etpermissions.
  • Entrez :String
  • facultatif.

layout

  • Objectif : afficher le style de disposition approprié.
  • Type :String qui correspond au nom du layout. Pour un layout nommécomponents/landing, la valeur seraitproduct-landing.
  • facultatif. Si elle est omise,DefaultLayout est utilisé.

children

  • Objectif : répertorier les liens relatifs qui appartiennent à la rubrique produit/catégorie/map. Pour plus d’informations, consultezPages d’Index.
  • Entrez :Array. La valeur par défaut estfalse.
  • Obligatoire sur les pagesindex.md.

childGroups

  • Objectif : afficher les enfants dans des groupes sur la page d’accueil. Pour plus d’informations, consultezPage d’accueil.
  • Entrez :Array. La valeur par défaut estfalse.
  • Obligatoire sur la page d’accueilindex.md.
  • Objectif : afficher les titres et les introductions des articles liés sur les pages de destination du produit et la page d’accueil.
  • Entrez :Object.
  • facultatif.

La liste des liens populaires est les liens affichés sur la page d’accueil sous le titre « Populaire ». Vous pouvez également personnaliser le titre « Populaire » en définissant la propriétéfeaturedLinks.popularHeading sur une nouvelle chaîne.

Exemple :

featuredLinks:
  gettingStarted:
    - /path/to/page
  startHere:
    - /guides/example
  popular:
    - /path/to/popular/article1
    - /path/to/popular/article2
  popularHeading: An alternate heading to Popular

showMiniToc

  • Objectif : indiquer si un article doit afficher une mini table des matières (TOC) au-dessus du reste du contenu. Pour plus d’informations, consultez desmini tables des matières (TOC) générées automatiquement.
  • Entrez :Boolean. La valeur par défaut esttrue sur les articles,false sur les thématiques etindex.md les pages.
  • facultatif.

allowTitleToDifferFromFilename

  • Objectif : indiquer si une page est autorisée à avoir un titre différent de son nom de fichier. Par exemple,content/rest/reference/orgs.md a un titre deOrganizations lieu deOrgs. Les pages avec cette information préliminaire définie surtrue ne seront pas marquées dans les tests ou mises à jour parsrc/content-render/scripts/reconcile-filenames-with-ids.ts.
  • Entrez :Boolean. La valeur par défaut estfalse.
  • facultatif.

changelog

  • Objectif : afficher une liste d’éléments extraits dujournal des modifications GitHub sur les pages de destination du produit (components/landing). L’une des exceptions est Education, qui extrait dehttps://github.blog/category/community/education.
  • Type :Object, propriétés :
    • label -- doit être présent et correspond aux étiquettes utilisées dans lejournal des modifications GitHub
    • prefix -- chaîne facultative qui commence chaque titre du journal des modifications devant être omis dans le flux docs. Par exemple, avec le préfixeGitHub Actions: spécifié, les titres du journal des modifications tels queGitHub Actions: Some Title Here seront affichés commeSome Title Here dans le flux docs.
  • facultatif.

defaultPlatform

  • Objectif : remplacer la sélection initiale de la plateforme pour une page. Si cette information préliminaire est omise, le contenu spécifique à la plateforme correspondant au système d’exploitation du lecteur est affiché par défaut. Ce comportement peut être modifié pour les pages individuelles, pour lesquelles une sélection manuelle est plus raisonnable. Par exemple, la plupart des exécuteurs GitHub Actions utilisent Linux, et leur système d’exploitation est indépendant du système d’exploitation du lecteur.
  • Type :String, l’une des valeurs suivantes :mac,windows,linux.
  • facultatif.

Exemple :

defaultPlatform: linux

defaultTool

  • Objectif : remplacer la sélection initiale de l’outil pour une page, où l’outil fait référence à l’application que le lecteur utilise pour travailler avec GitHub (par exemple, l’interface utilisateur web de GitHub.com, la CLI GitHub ou GitHub Desktop) ou les API GitHub. Pour plus d’informations sur le sélecteur d’outil, consultezUtilisation de Markdown et Liquid dans GitHub Docs. Si cette information préliminaire est omise, le contenu spécifique à l’outil correspondant à l’interface utilisateur web de GitHub est affiché par défaut. Si un utilisateur a indiqué une préférence d’outil (en cliquant sur un onglet d’outil), la préférence de l’utilisateur est appliquée au lieu de la valeur par défaut.
  • Type :String, l’une des valeurs suivantes :webui,cli,desktop,curl,codespaces,vscode,importer_cli,graphql,powershell,bash,javascript.
  • facultatif.
defaultTool: cli

learningTracks

  • Objectif : afficher une liste de pistes d’apprentissage sur la sous-page de destination d’un produit.
  • Entrez :String. Cela doit faire référence aux noms des pistes d’apprentissage définies dansdata/learning-tracks/*.yml.
  • Facultatif

Remarque

La piste recommandée est définie par une propriété spécifique dans le parcours d’apprentissage YAML. Consultez le fichierLISEZMOI pour plus de détails.

includeGuides

  • Objectif : afficher une liste d’articles, filtrable partype ettopics. S’applique uniquement lors de l’utilisation aveclayout: product-guides.
  • Entrez :Array
  • facultatif.

Exemple :

includeGuides:
  - /actions/guides/about-continuous-integration
  - /actions/guides/setting-up-continuous-integration-using-workflow-templates
  - /actions/guides/building-and-testing-nodejs
  - /actions/guides/building-and-testing-powershell

journeyTracks

  • Objectif : Définir des parcours pour les pages de destination des parcours.
  • Type :Array d’objets avec les propriétés suivantes :
    • id (obligatoire) : identificateur unique pour le parcours. L’ID doit uniquement être unique pour les parcours au sein d’une page d’accueil de parcours unique.
    • title (obligatoire) : Afficher le titre du parcours (prend en charge les variables Liquid)
    • description (facultatif) : Description du parcours (prend en charge les variables Liquid)
    • guides (obligatoire) : tableau des chemins d'accès des articles constituant ce parcours
  • S’applique uniquement lors de l’utilisation aveclayout: journey-landing.
  • facultatif.

Exemple :

journeyTracks:
  - id: 'getting_started'
    title: 'Getting started with GitHub Actions'
    description: 'Learn the basics of GitHub Actions.'
    guides:
      - '/actions/quickstart'
      - '/actions/learn-github-actions'
      - '/actions/using-workflows'
  - id: 'advanced'
    title: 'Advanced GitHub Actions'
    description: 'Dive deeper into advanced features.'
    guides:
      - '/actions/using-workflows/workflow-syntax-for-github-actions'
      - '/actions/deployment/deploying-with-github-actions'

type

  • Objectif : indiquer le type d’article.
  • Type :String, l’une des valeurs suivantes :overview,quick_start,tutorial,how_to,reference,rai.
  • facultatif.

topics

  • Objectif : indiquer les rubriques couvertes par l’article. Pour plus de détails sur l’ajout de rubriques, reportez-vous aux modèles de contenu. Une liste complète des rubriques existantes se trouve dans lefichier des rubriques autorisées. Si les rubriques dans l’information préliminaire de l’article et la liste des rubriques autorisées ne sont plus synchronisées, letest CI des rubriques échoue.
  • Type : tableau deString
  • Facultatif : les rubriques sont conseillées pour chaque article, mais il peut arriver que des articles existants n’aient pas encore de rubriques, ou que l’ajout d’une rubrique à un nouvel article n’ajoute pas de valeur.

communityRedirect

  • Objectif : définir un lien personnalisé et un nom de lien pour le lienAsk the GitHub community dans le pied de page.
  • Entrez :Object. Les propriétés sontname ethref.
  • facultatif.

effectiveDate

  • Objectif : définir une date d'entrée en vigueur pour les articles sur les conditions d’utilisation du service afin que les équipes d’ingénierie puissent inviter automatiquement les utilisateurs à confirmer les conditions
  • Type :string YEAR-MONTH-DAY, par exemple 2021-10-04 est le 4 octobre 2021
  • facultatif.

Remarque

LaeffectiveDate valeur de l’information préliminaire est à utiliser uniquement par le personnel GitHub.

Échappement des guillemets simples

Si vous voyez deux guillemets simples dans une ligne ('') dans l’information préliminaire YAML, où vous pourriez vous attendre à en voir un seul ('), il s’agit de la méthode préférée de YAML pour échapper un guillemet simple.

En guise d’alternative, vous pouvez modifier les guillemets simples entourant le champ d’information préliminaire en guillemets doubles et laisser les guillemets simples intérieurs non échappés.

Mini tables des matières (TOC) générées automatiquement

Chaque article affiche une mini table des matières (TOC), qui est une section « Dans cet article » générée automatiquement qui inclut des liens vers tous lesH2 de l’article. Seuls les en-têtesH2 sont inclus dans les mini TOC. Si un article utilise des en-têtesH3 ouH4 pour diviser les informations d’une manière telle que seules certaines sections sont pertinentes pour une tâche particulière, vous pouvez aider les utilisateurs à accéder au contenu le plus pertinent pour eux à l’aide d’uneTOC sectionnelle.

Vous pouvez utiliser la valeur d’information préliminaireshowMiniToc, définie surfalse, pour empêcher la mini TOC de s’afficher pour un article.

Les mini TOC n’apparaissent pas sur les pages de destination des produits, les pages de destination des catégories ou les pages thématiques.

N’ajoutez pas de sections « Dans cet article » codées en dur dans la source Markdown, sinon la page affichera des mini TOC en double.

Noms de fichiers

Lors de l’ajout d’un nouvel article, vérifiez que le nom de fichier est une versionkebab-case du titre que vous utilisez dans l’information préliminairetitle de l’article. Cela peut se révéler difficile lorsqu’un titre a une ponctuation (par exemple, « Plans de facturation GitHub »). Un test signale toutes les différences entre le titre et le nom de fichier. Pour remplacer cette exigence pour un article donné, vous pouvez ajouter une information préliminaireallowTitleToDifferFromFilename.

Pages d'index

Les pages d’index sont les fichiers de table des matières du site Docs. Chaque sous-répertoire de produit, de catégorie et de thématique possède un fichierindex.md qui fournit une vue d’ensemble du contenu et des liens vers chaque article enfant. Chaqueindex.md doit contenir une propriété d’information préliminairechildren avec une liste de liens relatifs vers les pages enfants du produit, de la catégorie ou de la thématique. Les pages d’index nécessitent une propriété frontmatterversions, et la valeur réelle sera calculée au moment du runtime en fonction des versions des articles enfants.

Remarque

Le site connaît uniquement les chemins d’accès inclus dans l’informationchildren préliminaire . Si un répertoire ou un article existe mais n’estpas inclus danschildren, son chemin d’accès renvoie un 404.

Homepage

La page d’accueil est le fichier de la table des matières principale du site docs. La page d’accueil doit avoir une liste complète dechildren, comme chaquepage d’index, mais doit également spécifier la propriété d’information préliminairechildGroups qui sera mise en surbrillance dans la zone de contenu principale.

childGroups est un tableau de mappages contenant unname pour le groupe, unicon facultatif pour le groupe et un tableau dechildren. Lechildren dans le tableau doit être présent dans la propriété d’information préliminairechildren.

Création de pages de guides de produit

Pour créer une page de guides de produit (par exemple, page de guideGitHub Actions), créez ou modifiez un fichier markdown existant avec ces valeurs d’information préliminaire spécifiques :

  • Utilisez le modèle de page guides de produit en référençantlayout: product-guides.
  • Incluez les pistes d’apprentissage danslearningTracks. facultatif.
  • Définissez les articles à inclure avecincludeGuides. facultatif.

Si vous utilisez des pistes d’apprentissage, elles doivent être définies dansdata/learning-tracks/*.yml. Si vous utilisezincludeGuides, vérifiez que chacun des articles de cette liste atopics ettype dans son information préliminaire.