Utilisation des informations préliminaires YAML

À 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 la documentation 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, consultez lib/frontmatter.js.

• versions
• redirect_from
• title
• shortTitle
• intro
• permissions
• product
• layout
• children
• childGroups
• featuredLinks
• showMiniToc
• allowTitleToDifferFromFilename
• changelog
• defaultPlatform
• defaultTool
• learningTracks
• includeGuides
• type
• topics
• communityRedirect
• effectiveDate

versions

• Objectif : indiquer les versions auxquelles une page s’applique. Pour plus d’informations sur les différents types de contrôle de version, consultez la « Documentation sur le contrôle de version ».
• Type : Object. Les clés autorisées sont mappées aux noms de produits et sont disponibles dans l’objet versions dans lib/frontmatter.js.
• Cette valeur d’informations préliminaires est actuellement requise pour toutes les pages.
• Le symbole * est utilisé pour indiquer toutes les releases de la version.
• Doit être présent pour tous les fichiers index.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, consultez Permalinks.

Exemple qui s’applique à GitHub.com et aux versions récentes de GitHub.com :

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

Exemple qui s’applique à toutes les versions prises en charge de GitHub Enterprise Server, mais pas à GitHub.com :

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 GitHub.com 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ément h1 en haut de la page.
• Entrez : String
• facultatif. Si elle est omise, la page <title> est toujours définie, mais avec une valeur générique comme GitHub.com ou GitHub Enterprise.

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'article	Nombre maximal de caractères
articles	31
categories	27
thématiques	30

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 le title.
• Entrez : String
• facultatif.

permissions

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

product

• Objectif : définir l’encadré de produits pour l’article. Cette chaîne sera affichée après les instructions intro et permissions.
• 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 serait product-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, consultez Pages d’Index.
• Type : Array. La valeur par défaut est false.
• Obligatoire sur les pages index.md.

childGroups

• Objectif : afficher les enfants dans des groupes sur la page d’accueil. Pour plus d’informations, consultez Page d’accueil.
• Type : Array. La valeur par défaut est false.
• Obligatoire sur la page d’accueil index.md.

featuredLinks

• Objectif : afficher les titres et les introductions des articles liés sur les pages de destination du produit et la page d’accueil.
• Type : 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 des mini tables des matières (TOC) générées automatiquement.
• Type : Boolean. La valeur par défaut est true sur les articles, false sur les thématiques et index.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 de Organizations lieu de Orgs. Les pages avec cette information préliminaire définie sur true ne seront pas marquées dans les tests ou mises à jour par src/content-render/scripts/reconcile-filenames-with-ids.js.
• Type : Boolean. La valeur par défaut est false.
• facultatif.

changelog

• Objectif : afficher une liste d’éléments extraits du journal des modifications GitHub sur les pages de destination du produit (components/landing). L’une des exceptions est Education, qui extrait de https://github.blog/category/community/education.
• Type : Object, propriétés :
  • label -- doit être présent et correspond aux étiquettes utilisées dans le journal 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éfixe GitHub Actions: spécifié, les titres du journal des modifications tels que GitHub Actions: Some Title Here seront affichés comme Some 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, consultez « Utilisation 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.
• Type : String. Cela doit faire référence aux noms des pistes d’apprentissage définies dans data/learning-tracks/*.yml.
• Facultatif

includeGuides

• Objectif : afficher une liste d’articles, filtrable par type et topics. S’applique uniquement lors de l’utilisation avec layout: 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

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. Les rubriques sont utilisées pour filtrer les guides sur certaines pages de destination. Par exemple, les guides situés en bas de « Guides pour GitHub Actions » peuvent être filtrés par rubriques, et les rubriques sont répertoriées sous l’introduction du guide. 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 le fichier 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, le test CI des rubriques échoue.
• Type : tableau de String
• 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 lien Ask the GitHub community dans le pied de page.
• Type : Object. Les propriétés sont name et href.
• 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.

É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 les H2 de l’article. Seuls les en-têtes H2 sont inclus dans les mini TOC. Si un article utilise des en-têtes H3 ou H4 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’une TOC sectionnelle.

Vous pouvez utiliser la valeur d’information préliminaire showMiniToc, définie sur false, 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 version kebab-case du titre que vous utilisez dans l’information préliminaire title 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éliminaire allowTitleToDifferFromFilename.

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 fichier index.md qui fournit une vue d’ensemble du contenu et des liens vers chaque article enfant. Chaque index.md doit contenir une propriété d’information préliminaire children 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é frontmatter versions, et la valeur réelle sera calculée au moment du runtime en fonction des versions des articles enfants.

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 de children, comme chaque page d’index, mais doit également spécifier la propriété d’information préliminaire childGroups qui sera mise en surbrillance dans la zone de contenu principale.

childGroups est un tableau de mappages contenant un name pour le groupe, un icon facultatif pour le groupe et un tableau de children. Le children dans le tableau doit être présent dans la propriété d’information préliminaire children.

Création de pages de guides de produit

Pour créer une page de guides de produit (par exemple, page de guide GitHub 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çant layout: product-guides.
• Incluez les pistes d’apprentissage dans learningTracks. facultatif.
• Définissez les articles à inclure avec includeGuides. facultatif.

Si vous utilisez des pistes d’apprentissage, elles doivent être définies dans data/learning-tracks/*.yml. Si vous utilisez includeGuides, vérifiez que chacun des articles de cette liste a topics et type dans son information préliminaire.