Cette version de GitHub Enterprise Server ne sera plus disponible le 2026-03-17. Aucune publication de correctifs n’est effectuée, même pour les problèmes de sécurité critiques. Pour de meilleures performances, une sécurité améliorée et de nouvelles fonctionnalités, effectuez une mise à niveau vers la dernière version de GitHub Enterprise. Pour obtenir de l’aide sur la mise à niveau, contactez le support GitHub Enterprise.

Utilisation du frontmatter 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 de l'en-tête 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 YAML frontmatter

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.ts.

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.ts.
  • Cette valeur de la page d'en-tête est actuellement requise pour toutes les pages.
  • Le symbole * est utilisé pour indiquer toutes les releases de la version.
  • Elle doit être présente dans tous les fichiers index.md, mais la valeur réelle est calculée lors de l’exécution en fonction des enfants.

Cette valeur de métadonnées est utilisée par le site de documentation pour générer des « permaliens » 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 versionner une page pour une série de versions. Ceci versionnerait la page pour les versions Free, Pro et Team, 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
  •         **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
catégories27
sujets de la carte30

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 la déclaration de permission de l’article. Cette chaîne sera affichée après le intro.
  • Entrez : String
  • facultatif.

product

  • Objectif : définit la mention du produit associée à l’article. Cette chaîne sera affichée après les instructions intro et permissions.
  • Entrez : String
  • facultatif.

layout

  • Objectif : rendre la mise en page appropriée.
  • 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.
  • 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 de caractères.

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 sur 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.ts.
  • Type : Boolean. La valeur par défaut est false.
  • facultatif.

changelog

  • Objectif : afficher la liste des éléments extraits de GitHub Journal des modifications sur les pages d’accueil du produit (components/landing). L’une des exceptions est Éducation, qui tire ses données 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 GitHub Journal des modifications * prefix -- chaîne facultative placée au début de chaque titre du journal des modifications et devant être omise dans le flux de documentation. Par exemple, avec le préfixe GitHub Actions: spécifié, les titres de journal de modification tels que GitHub Actions: Some Title Here s’affichent 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 : remplacez la sélection initiale de l'outil pour une page, où l'outil fait référence à l'application que le lecteur utilise pour utiliser GitHub (par exemple, l'interface utilisateur web de GitHub.com, l'interface 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 ce frontmatter est omis, le contenu spécifique à l’outil correspondant à l’interface utilisateur web 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

Remarque

La piste mise en avant est définie par une propriété spécifique dans le fichier YAML des parcours d'apprentissage. Consultez le fichier README pour plus de détails.

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

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) : affiche le titre du parcours (prend en charge les variables Liquid) * description (facultatif) : Description du parcours (prend en charge les variables Liquid) * guides (obligatoire) : tableau d’objets de repère qui composent ce parcours. Chaque objet de repère a : * href (obligatoire) : chemin d’accès à l’article * alternativeNextStep (facultatif) : texte personnalisé pour guider les utilisateurs vers d’autres chemins d’accès dans le parcours. Prend en charge les variables Liquid et [AUTOTITLE].
  • S’applique uniquement lors de l’utilisation avec layout: journey-landing.
  • facultatif.

Exemple :

journeyTracks:
  - id: 'getting_started'
    title: 'Getting started with GitHub Actions'
    description: 'Learn the basics of GitHub Actions.'
    guides:
      - href: '/actions/quickstart'
      - href: '/actions/learn-github-actions'
        alternativeNextStep: 'Want to skip ahead? See [AUTOTITLE](/actions/using-workflows).'
      - href: '/actions/using-workflows'
  - id: 'advanced'
    title: 'Advanced GitHub Actions'
    description: 'Dive deeper into advanced features.'
    guides:
      - href: '/actions/using-workflows/workflow-syntax-for-github-actions'
      - href: '/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.

communityRedirect

  • Objectif : définissez un lien personnalisé et un nom de lien pour Ask the GitHub community lien 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.

Remarque

La valeur effectiveDate du frontmatter est réservée à l’usage exclusif du personnel GitHub.

Échappement des guillemets simples

Si vous voyez deux guillemets simples à la suite ('') dans l'en-tête YAML où vous pourriez vous attendre à en voir un seul ('), c'est la méthode préférée par YAML pour échapper un guillemet simple.

Vous pouvez également remplacer les guillemets simples entourant le champ frontmatter par des guillemets doubles et laisser les guillemets simples internes sans échappement.

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-tableaux des matières. 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

Lorsque vous ajoutez un nouvel article, assurez-vous que le nom du fichier est une version kebab-cased du titre utilisé dans le frontmatter title de l’article. Cela peut se révéler difficile lorsqu'un titre a une ponctuation (par exemple, « plans de facturation de 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é frontmatter 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 n'a connaissance que des chemins inclus dans l'en-tête children. Si un répertoire ou un article existe mais n’est pas inclus dans children, son chemin d’accès renvoie un 404.

Page d'accueil

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é `children` frontmatter.

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 type dans son frontmatter.