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-Frontmatter ist eine durch Jekyll populär gemachte Konvention zum Verfassen von Inhalten, 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 YAML Frontmatter-Dokumentation.

Werte der YAML-Titelei

Die folgenden Frontmatter-Werte haben spezielle Bedeutungen und Anforderungen für GitHub Docs. Es gibt auch ein Schema, mit dem die Test-Suite das Frontmatter aller Seiten validiert. Weitere Informationen finden Sie unter .

versions

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

Dieser Frontmatter-Wert wird von der Dokumentationsseite verwendet, um für jede Version eines Artikels permanente Links zu generieren. Weitere Informationen finden Sie unter Permalinks.

Beispiel, das für Free-, Pro-, Team- und GitHub Enterprise Server Version 3.11 und höher gilt:

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

Beispiel, das nur für GitHub Enterprise Server gilt.

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

Sie können eine Seite auch für verschiedene Releases versionieren. Dies würde die Seite nur für die Versionen Free, Pro, & Team und GitHub Enterprise Server 3.1 und 3.2 aktualisieren:

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

redirect_from

  • Zweck: Auflisten von URLs, die auf diese Seite umleiten sollen.
  • Typ:
  • Wahlweise

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 finden Sie unter AUTOTITLE.

title

  • Zweck: Festlegen eines ansprechenden Titels für die Verwendung im -Tag der gerenderten Seite sowie eines -Elements oben auf der Seite.
  • Typ:
  • Erforderlich.

shortTitle

  • Zweck: Verwendung einer kürzeren Variante des Seitentitels für die Verwendung in Breadcrumbs und Navigationselementen.
  • Typ:
  • Optional. Wenn nicht angegeben, wird verwendet.
ArtikeltypMaximale Zeichenlänge
Artikel31
Kategorien27
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 gerendert.
  • Typ:
  • Optional.

permissions

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

product

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

layout

  • Zweck: Rendern des korrekten Seitenlayouts.
  • Typ: , der mit dem Namen des Layouts übereinstimmt. Für ein Layout mit dem Namen lautet der Wert .
  • Optional. Wenn nicht angegeben, wird verwendet.

children

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

childGroups

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

Die Liste der beliebten Links wird auf der Angebotsseite unter dem Titel „Beliebt“ angezeigt. Alternativ können Sie den Titel „Beliebt“ anpassen, indem Sie die Eigenschaft auf eine neue Zeichenfolge setzen.

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 unter „Automatisch generierte Kurzverzeichnisse“.
  • Typ: . Der Standardwert lautet für Artikel und für Kartenthemen und Seiten vom Typ .
  • Optional.

allowTitleToDifferFromFilename

  • Zweck: Angeben, ob sich der Titel einer Seite vom Dateinamen unterscheiden darf. Beispiel: Der Titel von lautet anstelle von . Seiten, für die dieser Frontmatter-Wert auf festgelegt ist, werden in Tests nicht gekennzeichnet oder mit aktualisiert.
  • Typ: . Der Standardwert ist .
  • Optional.

changelog

  • Zweck: Rendern einer Liste von Elementen, die aus GitHub Changelog auf Produktzielseiten abgerufen wurden (components/landing). Die einzige Ausnahme bildet „Education“, das aus abruft.
  • Typ: , verfügt über folgende Eigenschaften: * label -- muss vorhanden sein und entspricht den Bezeichnungen im GitHub Changelog
    • : Optionale Zeichenfolge, steht am Anfang aller Änderungsprotokolltitel, die im Dokumentationsfeed nicht angegeben werden sollen. Wenn beispielsweise das Präfix GitHub Actions: angegeben ist, werden Änderungsprotokolltitel wie GitHub Actions: Some Title Here als Some Title Here im Docs-Feed gerendert.
  • Optional.

defaultPlatform

  • Zweck: Überschreiben der anfänglichen Plattformauswahl für eine Seite. Wenn dieses Frontmatter weggelassen wird, wird standardmäßig der plattformspezifische Inhalt angezeigt, der dem Betriebssystem des Lesers entspricht. 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: , einer von: , , .
  • Optional.

Beispiel:

defaultPlatform: linux

defaultTool

  • Zweck: Überschreiben Sie die anfängliche Toolauswahl für eine Seite, bei der das Tool auf die Anwendung verweist, die der Leser verwendet, um mit GitHub (z. B. der Web-UI GitHub.com, der GitHub CLI oder GitHub Desktop) oder den GitHub-APIs zu arbeiten. Weitere Informationen zur Toolauswahl findest du unter AUTOTITLE. Wenn dieser Frontmatter nicht angegeben wird, wird standardmäßig der toolspezifische Inhalt angezeigt, der der GitHub Webbenutzeroberfläche entspricht. Gibt ein Benutzer/eine Benutzerin (durch Klicken auf eine Toolregisterkarte) ein Tool an, wird diese Einstellung anstelle des Standardwerts angewendet.
  • Typ: , einer von: , , , , , , , , , , .
  • Optional.
defaultTool: cli

learningTracks

  • Zweck: Darstellung einer Liste von Lernpfaden auf einer Produkt-Unterseite.
  • Typ: . Sollte auf die Namen von Lernpfaden verweisen, die in definiert sind.
  • Wahlweise

Hinweis

Der hervorgehobene Lernpfad wird durch eine bestimmte Eigenschaft in der YAML-Datei der Lernpfade festgelegt. Weitere Informationen finden Sie in dieser README.

includeGuides

  • Zweck: Rendern einer Liste von Artikeln, die nach und gefiltert werden kann. Kann nur mit verwendet werden.
  • Typ:
  • 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

journeyTracks

  • Zweck: Definieren von Journeys für Journey-Zielseiten.
  • Typ: von Objekten mit den folgenden Eigenschaften:
    • (erforderlich): Eindeutiger Bezeichner für die Reise. Die ID muss nur für Reisen innerhalb einer einzelnen Reise-Startseite eindeutig sein.
    • (erforderlich): Anzeigetitel für die Reise (unterstützt Liquid-Variablen)
    • (optional): Beschreibung der Reise (unterstützt Liquid-Variablen)
    • (erforderlich): Array von Leitfadenobjekten, die diese Reise ausmachen. Jedes Führungsobjekt verfügt über:
    • (erforderlich): Pfad zum Artikel
    • (optional): Benutzerdefinierter Text, der Benutzer zu alternativen Pfaden in der Reise führt. Unterstützt Liquid-Variablen und .
  • Kann nur mit verwendet werden.
  • Optional.

Beispiel:

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

  • Zweck: Angeben des Artikeltyps.
  • Typ: . Die Eigenschaften sind , , , , oder .
  • Optional.

communityRedirect

  • Zweck: Legen Sie einen benutzerdefinierten Link- und Linknamen für Ask the GitHub community Link in der Fußzeile fest.
  • Typ: . Die Eigenschaften sind und .
  • 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: im Format JAHR-MONAT-TAG, „2021-10-04“ entspricht z. B. dem Datum „4. Oktober 2021“.
  • Optional.

Hinweis

Der Frontmatterwert dient nur für GitHub-Mitarbeitende.

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 Abschnitten im Artikel enthält. Nur Kopfzeilen sind in den Miniinhaltsverzeichnissen enthalten. Wenn ein Artikel oder Kopfzeilen zum Aufteilen von Informationen auf eine Weise verwendet, dass bestimmte Abschnitte nur für eine bestimmte Aufgabe relevant sind, können Sie Personen dabei helfen, zu den für sie relevantesten Inhalten zu navigieren, indem Sie ein Inhaltsverzeichnis für Abschnitte verwenden.

Sie können den Frontmatter-Wert verwenden, um zu verhindern, dass das Mini-Inhaltsverzeichnis für einen Artikel angezeigt wird, indem Sie diesen auf einen bestimmten Wert festlegen.

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 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 Interpunktion hat (z. B. "Abrechnungspläne von GitHub"). Bei einem Test werden alle Abweichungen zwischen Titel und Dateinamen gekennzeichnet. Um diese Anforderung für einen bestimmten Artikel zu umgehen, können Sie Frontmatter hinzufügen.

Indexseiten

Indexseiten sind die Inhaltsverzeichnisdateien für die Dokumentationswebsite. Jedes Produkt, jedes Kategorie- und Kartenthemaunterverzeichnis verfügt über eine -Datei, die einen Überblick über den Inhalt und Links zu jedem untergeordneten Artikel bietet. Jeder -Wert muss eine Frontmatter-Eigenschaft vom Typ mit einer Liste relativer Links zu den untergeordneten Seiten des Produkts, der Kategorie oder des Kartenthemas enthalten. Indexseiten erfordern eine -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 Frontmatter enthalten sind. Ist ein Verzeichnis oder ein Artikel vorhanden, aber nicht in enthalten, gibt der Pfad einen 404-Fehler zurück.

Startseite

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

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

Erstellen neuer Seiten für Produktanleitungen

Wenn Sie eine Produktanleitungsseite erstellen möchten (z. B. eine GitHub Actions-Anleitungsseite), erstellen oder ändern Sie eine vorhandene Markdowndatei mit den folgenden Frontmatter-Werten:

  • Verwenden Sie die Produktanleitungsseitenvorlage, indem Sie darauf verweisen.
  • Integrieren Sie die Lernpfade in das Programm. Optional.
  • Definieren Sie mit , welche Artikel eingeschlossen werden sollen. Optional.

Wenn Sie Lernpfade verwenden möchten, definieren Sie diese in . Stelle bei Verwendung von sicher, dass das Frontmatter aller Artikel in dieser Liste und enthält.