Verwenden einer YAML-Titelei

Sie können die YAML-Titelei verwenden, um die Versionsverwaltung zu definieren, Metadaten hinzuzufügen und das Layout für Artikel zu steuern.

In diesem Artikel

Informationen zur YAML-Titelei

Die YAML-Titelei ist eine durch Jekyll bekannt gewordene Konvention zur Dokumenterstellung, mit der Sie einer Seite Metadaten hinzufügen können. Dabei handelt es sich um einen Block mit Schlüssel-Wert-Paaren, der sich am Anfang jeder Markdowndatei innerhalb von GitHub Docs befindet. Weitere Informationen finden Sie in der Dokumentation zur YAML-Titelei.

Werte der YAML-Titelei

Die folgenden Titeleiwerte haben besondere Bedeutungen und Anforderungen für GitHub Docs. Es gibt auch ein Schema, mit der die Testsammlung die Titeleiwerte aller Seiten überprüft. Weitere Informationen finden Sie unter lib/frontmatter.js.

versions

  • Zweck: Angeben der Versionen, für die eine Seite gilt. Weitere Informationen zu den verschiedenen Versionstypen finden Sie in der "Dokumentation zur Versionsverwaltung".
  • Typ: Object Zulässige Schlüssel werden Produktnamen zugeordnet und befinden sich im Objekt versions in lib/frontmatter.js.
  • Dieser Frontmatter-Wert ist derzeit für alle Seiten erforderlich.
  • Mit * kennzeichnen Sie alle Releases für die Version.
  • Muss für alle index.md-Dateien vorhanden sein, aber der tatsächliche Wert wird zur Laufzeit basierend auf den untergeordneten Elementen berechnet.

Dieser Titeleiwert wird von der Docs-Website verwendet, um für jede Version eines Artikels "Permalinks" zu generieren. Weitere Informationen finden Sie unter Permalinks.

Beispiel, das für GitHub.com und aktuelle Versionen von GitHub Enterprise Server gilt:

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

Beispiel, das für alle unterstützten Versionen von GitHub Enterprise Server, aber nicht für GitHub.com gilt:

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

Sie können für eine Seite auch einen versionsspezifischen Releasebereich festlegen. Das folgende Beispiel verwaltet die Versionen der Seite nur für GitHub.com und die GitHub Enterprise Server-Versionen 3.1 und 3.2:

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

redirect_from

  • Zweck: Auflisten von URLs, von denen auf diese Seite umgeleitet wird.
  • Typ: Array
  • Optional

Beispiel:

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

Weitere Informationen findest du unter Konfigurieren von Umleitungen.

title

  • Zweck: Festlegen eines ansprechenden Titels für die Verwendung im <title>-Tag der gerenderten Seite sowie eines h1-Elements oben auf der Seite.
  • Typ: String
  • Optional. Wenn nicht angegeben, wird die Seite <title> trotzdem festgelegt, jedoch mit einem allgemeinen Wert wie GitHub.com oder GitHub Enterprise.

shortTitle

  • Zweck: Festlegen einer kürzeren Variante des Seitentitels für die Verwendung in Breadcrumbs und Navigationselementen.
  • Typ: String
  • Optional. Wenn nicht angegeben, wird title verwendet.
ArtikeltypMaximale Zeichenlänge
Artikel31
categories27
Kartenthemen30

Beispiel:

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

intro

  • Zweck: Festlegen der Einführung für die Seite. Diese Zeichenfolge wird nach title gerendert.
  • Typ: String
  • Optional.

permissions

  • Zweck: Festlegen der Berechtigungsanweisung für den Artikel. Diese Zeichenfolge wird nach intro gerendert.
  • Typ: String
  • Optional.

product

  • Zweck: Festlegen der Produktbezeichnung für den Artikel. Diese Zeichenfolge wird nach den Anweisungen intro und permissions gerendert.
  • Typ: String
  • Optional.

layout

  • Zweck: Rendern des korrekten Seitenlayouts.
  • Typ: String, in Übereinstimmung mit dem Namen des Layouts. Für ein Layout mit dem Namen components/landing lautet der Wert product-landing.
  • Optional. Wenn nicht angegeben, wird DefaultLayout verwendet.

children

  • Zweck: Auflisten der relativen Links zu Produkt/Kategorie/Kartemthema. Weitere Informationen finden Sie unter Indexseiten.
  • Typ: Array Der Standardwert ist false.
  • Erforderlich auf Seiten vom Typ index.md.

childGroups

  • Zweck: Rendern von untergeordneten Elementen in Gruppen auf der Startseite. Weitere Informationen finden Sie unter Homepage.
  • Typ: Array Der Standardwert ist false.
  • Erforderlich für den index.md-Wert der Startseite.
  • Zweck: Rendern der Titel und Einführungen von verknüpften Artikeln auf den Angebotsseiten und der Startseite des Produkts.
  • Typ: Object
  • Optional.

Die Liste der beliebten Links wird auf der Angebotsseite unter dem Titel „Beliebt“ angezeigt. Wenn Sie den Titel „Beliebt“ anpassen möchten, legen Sie die Eigenschaft featuredLinks.popularHeading auf eine neue Zeichenfolge fest.

Beispiel:

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

showMiniToc

  • Zweck: Angeben, ob im Artikel über dem weiteren Inhalt ein Mini-Inhaltsverzeichnis angezeigt werden soll. Weitere Informationen finden Sie unter Automatisch generierte Kurzverzeichnisse.
  • Typ: Boolean Der Standardwert lautet true für Artikel und false für Kartenthemen und Seiten vom Typ index.md.
  • Optional.

allowTitleToDifferFromFilename

  • Zweck: Angeben, ob sich der Titel einer Seite vom Dateinamen unterscheiden darf. Beispiel: Der Titel von content/rest/reference/orgs.md lautet Organizations anstelle von Orgs. Seiten, für die dieser Frontmatter-Wert auf true festgelegt ist, werden in Tests nicht gekennzeichnet oder mit src/content-render/scripts/reconcile-filenames-with-ids.js aktualisiert.
  • Typ: Boolean Der Standardwert ist false.
  • Optional.

changelog

  • Zweck: Rendern einer Liste von Elementen, die per Pull vom GitHub-Änderungsprotokoll auf Produktangebotsseiten (components/landing) übertragen wurden. Die einzige Ausnahme bildet „Education“, das aus https://github.blog/category/community/education abruft.
  • Typ: Object, verfügt über folgende Eigenschaften:
    • label: Muss angegeben werden, entspricht den im GitHub-Änderungsprotokoll verwendeten Bezeichnungen.
    • prefix: Optionale Zeichenfolge, steht am Anfang aller Änderungsprotokolltitel, die im Dokumentationsfeed nicht angegeben werden sollen. Mit dem Präfix GitHub Actions: wird z. B. der Änderungsprotokolltitel GitHub Actions: Some Title Here im Dokumentationsfeed als Some Title Here gerendert.
  • Optional.

defaultPlatform

  • Zweck: Überschreiben der anfänglichen Plattformauswahl für eine Seite. Wenn nicht angegeben, wird standardmäßig der plattformspezifische Inhalt entsprechend dem Betriebssystem des Lesers angezeigt. Dieses Verhalten kann für einzelne Seiten geändert werden, für die eine manuelle Auswahl geeigneter ist. Beispielsweise verwenden die meisten Runner für GitHub Actions Linux, und ihr Betriebssystem ist unabhängig vom Betriebssystem des Lesers.
  • Typ: String. Die Eigenschaften sind mac, windows oder linux.
  • Optional.

Beispiel:

defaultPlatform: linux

defaultTool

  • Zweck: Überschreiben der anfänglichen Toolauswahl für eine Seite. Dabei handelt es sich um die Anwendung, die der Leser für GitHub verwendet (z. B. die Webbenutzeroberfläche von GitHub.com, die GitHub-CLI oder GitHub Desktop) oder für die GitHub-APIs. Weitere Informationen zur Toolauswahl finden Sie unter Verwenden von Markdown und Liquid in GitHub Docs. Wenn nicht angegeben, wird standardmäßig der toolspezifische Inhalt entsprechend de GitHub-Web-UI angezeigt. Gibt ein Benutzer/eine Benutzerin (durch Klicken auf eine Toolregisterkarte) ein Tool an, wird diese Einstellung anstelle des Standardwerts angewendet.
  • Typ: String. Die Eigenschaften sind webui, cli, desktop, curl, codespaces, vscode, importer_cli, graphql, powershell, bash, javascript.
  • Optional.
defaultTool: cli

learningTracks

  • Zweck: Rendern einer Liste von Lernpfaden auf einer Unterseite der Produktangebotsseite.
  • Typ: String Sollte auf die Namen von Lernpfaden verweisen, die in data/learning-tracks/*.yml definiert sind.
  • Optional

Hinweis:: Der empfohlene Lernpfad wird durch eine bestimmte Eigenschaft in seiner YAML-Datei festgelegt. Weitere Informationen finden Sie in dieser README.

includeGuides

  • Zweck: Rendern einer Liste von Artikeln, die nach type und topics gefiltert werden kann. Kann nur mit layout: product-guides verwendet werden.
  • Typ: Array
  • Optional.

Beispiel:

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

  • Zweck: Angeben des Artikeltyps.
  • Typ: String. Die Eigenschaften sind overview, quick_start, tutorial, how_to, reference oder rai.
  • Optional.

topics

  • Zweck: Angeben der Themen, die im Artikel behandelt werden. Anhand der Themen werden die Anleitungen auf einigen Angebotsseiten gefiltert. Beispielsweise können die Anleitungen unten auf "Anleitungen für GitHub Actions" nach Themen gefiltert werden, die unterhalb der Anleitungseinführung aufgelistet werden. Weitere Informationen zum Hinzufügen von Themen finden Sie in den Inhaltsmodellen. Eine vollständige Liste der vorhandenen Themen finden Sie in der Datei mit den zulässigen Themen. Sind die Themen im Frontmatter-Wert des Artikels und in der Liste der zulässigen Themen nicht mehr synchron, tritt beim CI-Test der Themen ein Fehler auf.
  • Typ: String-Array.
  • Optional: Grundsätzlich werden Themen für jeden Artikel empfohlen. Doch es kann vorkommen, dass vorhandene Artikel noch keine Themen besitzen oder das Hinzufügen eines Themas zu einem neuen Artikel keinen Mehrwert bringt.

communityRedirect

  • Zweck: Festlegen eines benutzerdefinierten Links und Linknamens für den Link Ask the GitHub community in der Fußzeile.
  • Typ: Object Die Eigenschaften sind name und href.
  • Optional.

effectiveDate

  • Zweck: Festlegen eines Gültigkeitsdatums für Artikel zum Thema Nutzungsbedingungen, damit Technikteams Benutzer*innen automatisch zur erneuten Bestätigung der Nutzungsbedingungen auffordern können.
  • Typ: string im Format JAHR-MONAT-TAG, „2021-10-04“ entspricht z. B. dem Datum „4. Oktober 2021“.
  • Optional.

Hinweis: Der effectiveDate-Titeleiwert dient nur für GitHub-Mitarbeiter.

Escapesequenz für einzelne Anführungszeichen

Zwei einzelne Anführungszeichen hintereinander ('') in der YAML-Titelei anstelle eines einzelnen (') stellen die Escapesequenz für ein einzelnes Anführungszeichen im YAML-Format dar.

Alternativ können Sie das Titelei-Feld mit doppelten Anführungszeichen umschließen und die inneren einzelnen Anführungszeichen ohne Escapesequenz belassen.

Automatisch generierte Mini-Inhaltsverzeichnisse

Jeder Artikel zeigt ein Mini-Inhaltsverzeichnis an, bei dem es sich um einen automatisch generierten Abschnitt "In diesem Artikel" handelt, der Links zu allen H2 im Artikel enthält. Nur H2-Kopfzeilen sind in den Mini-Inhaltsverzeichnissen enthalten. Wenn ein Artikel- H3 oder H4-Kopfzeilen zum Aufteilen von Informationen auf eine Weise verwenden kann, sodass bestimmte Abschnitte nur für eine bestimmte Aufgabe relevant sind, können Sie Personen bei der Navigation zu den inhalten helfen, die für sie am relevantesten sind, indem Sie ein Abschnitts-Inhaltsverzeichnis verwenden.

Sie können den showMiniToc-Titeleiwert verwenden, der auf false festgelegt wurde, um zu verhindern, dass das Mini-Inhaltsverzeichnis für einen Artikel angezeigt wird.

Auf Produkt- und Kategorieangebotsseiten sowie auf Kartenthemaseiten werden keine Miniinhaltsverzeichnisse angezeigt.

Fügen Sie der Markdownquelle keine hartcodierten Abschnitte vom Typ „Inhalt dieses Artikels“ hinzu, damit auf der Seite keine doppelten Miniinhaltsverzeichnisse angezeigt werden.

Dateinamen

Verwenden Sie beim Hinzufügen eines neuen Artikels für den Dateinamen den Titel, den Sie für den Frontmatter-Wert title verwendet haben. Verwenden Sie hierzu jedoch die Kebab-Schreibweise, bei der alle Wörter kleingeschrieben und durch Bindestriche voneinander getrennt werden. Dies kann schwierig werden, wenn ein Titel Satzzeichen enthält (z. B. „GitHub's Billing Plans“). Bei einem Test werden alle Abweichungen zwischen Titel und Dateinamen gekennzeichnet. Wenn Sie diese Anforderung für einen bestimmten Artikel außer Kraft setzen möchten, fügen Sie den Frontmatter-Wert allowTitleToDifferFromFilename hinzu.

Indexseiten

Indexseiten sind die Inhaltsverzeichnisdateien für die Dokumentationswebsite. Jedes Produkt, jedes Kategorie- und Kartenthemaunterverzeichnis verfügt über eine index.md-Datei, die einen Überblick über den Inhalt und Links zu jedem untergeordneten Artikel bietet. Jeder index.md-Wert muss eine Frontmatter-Eigenschaft vom Typ children mit einer Liste relativer Links zu den untergeordneten Seiten des Produkts, der Kategorie oder des Kartenthemas enthalten. Indexseiten erfordern eine versions-Frontmattereigenschaft, und der tatsächliche Wert wird zur Laufzeit basierend auf den Versionen von untergeordneten Artikeln berechnet.

Hinweis: Die Website kennt nur Pfade, die im Titeleiwert children enthalten sind. Ist ein Verzeichnis oder ein Artikel vorhanden, aber nicht in children enthalten, gibt der Pfad einen 404-Fehler zurück.

Homepage

Die Startseite stellt die Inhaltsverzeichnis-Hauptdatei für die Dokumentationswebsite dar. Die Startseite muss wie jede Indexseite eine vollständige Liste der children-Werte enthalten und zusätzlich die Frontmatter-Eigenschaft childGroups angeben, die im Hauptinhaltsbereich hervorgehoben wird.

childGroups ist ein Array von Zuordnungen, das einen name-Wert und einen optionalen icon-Wert für die Gruppe und ein Array von children-Werten enthält. Der children-Wert im Array muss in der Frontmatter-Eigenschaft children vorhanden sein.

Erstellen neuer Seiten für Produktanleitungen

Wenn Sie eine Seite für Produktanleitungen erstellen möchten (z. B. eine GitHub Actions-Anleitungsseite), erstellen oder ändern Sie eine vorhandene Markdowndatei mit den folgenden Titeleiwerten:

  • Verwenden Sie die Seitenvorlage für die Anleitungsseiten, indem Sie auf layout: product-guides verweisen.
  • Verweisen Sie auf die Lernpfade in learningTracks. Optional.
  • Definieren Sie mit includeGuides, welche Artikel eingeschlossen werden sollen. Optional.

Wenn Sie Lernpfade verwenden möchten, definieren Sie diese in data/learning-tracks/*.yml. Wenn Sie includeGuides verwenden, stellen Sie sicher, dass die Titeleiwerte aller Artikel in dieser Liste die Eigenschaften topics und type enthalten.