À 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 ».
- Entrez :
Object
. Les clés autorisées sont mappées aux noms de produits et sont disponibles dans l’objetversions
danslib/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 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
- facultatif. Si elle est omise, la page
<title>
est toujours définie, mais avec une valeur générique commeGitHub.com
ouGitHub 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
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, consultez Pages d’Index.
- Entrez :
Array
. La valeur par défaut estfalse
. - 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.
- Entrez :
Array
. La valeur par défaut estfalse
. - 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.
- 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 des mini 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.js
. - Entrez :
Boolean
. La valeur par défaut estfalse
. - 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 GitHubprefix
-- 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, 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.
- 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 fichier LISEZMOI pour plus de détails.
includeGuides
- Objectif : afficher une liste d’articles, filtrable par
type
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
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 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. - 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 : La valeur de l’information préliminaire effectiveDate
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 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.
Remarque : le site connaît uniquement les chemins d’accès inclus dans l’information préliminaire children
. Si un répertoire ou un article existe mais n’est pas inclus dans children
, 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 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.