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 Dokumentation zum YAML-Frontmatter.

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 findest du unter lib/frontmatter.ts.

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: Object. Zulässige Schlüssel werden Produktnamen zugeordnet und befinden sich im Objekt versions in lib/frontmatter.ts.
  • 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 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: Array
  • 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 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
  •         **Erforderlich**.

shortTitle

  • Zweck: Verwendung 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
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 title gerendert.
  • Typ: String
  • Optional.

permissions

  • Zweck: Festlegen der Berechtigungsanweisung für den Artikel. Diese Zeichenkette wird nach dem 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.
  • Geben Sie String ein, das mit dem Namen des Layouts übereinstimmt. 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 auf der Startseite index.md.
  • 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. Alternativ können Sie den Titel „Beliebt“ anpassen, indem Sie die Eigenschaft featuredLinks.popularHeading auf eine neue Zeichenfolge festlegen.

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.ts aktualisiert.
  • Typ: Boolean. Der Standardwert ist false.
  • 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 https://github.blog/category/community/education abruft.
  • Typ: Object, verfügt über folgende Eigenschaften: * label -- muss vorhanden sein und entspricht den Bezeichnungen im GitHub Changelog * prefix: 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: String, eines von: mac, windows, linux.
  • 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 Verwenden von Markdown und Liquid in GitHub Docs. 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: String, einer von: webui, cli, desktop, curl, codespaces, vscode, importer_cli, graphql, powershell, bash, javascript.
  • Optional.
defaultTool: cli

learningTracks

  • Zweck: Darstellung einer Liste von Lernpfaden auf einer Produkt-Unterseite.
  • Typ: String. Sollte auf die Namen von Lernpfaden verweisen, die in data/learning-tracks/*.yml 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 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

journeyTracks

  • Zweck: Definieren von Journeys für Journey-Zielseiten.
  • Typ: Array von Objekten mit den folgenden Eigenschaften: * id (erforderlich): Eindeutiger Bezeichner für die Reise. Die ID muss nur für Reisen innerhalb einer einzelnen Reise-Startseite eindeutig sein. * title (erforderlich): Anzeigetitel für die Reise (unterstützt Liquid-Variablen) * description (optional): Beschreibung der Reise (unterstützt Liquid-Variablen) * guides (erforderlich): Array von Leitfadenobjekten, die diese Reise ausmachen. Jedes Führungsobjekt verfügt über: * href (erforderlich): Pfad zum Artikel * alternativeNextStep (optional): Benutzerdefinierter Text, der Benutzer zu alternativen Pfaden in der Reise führt. Unterstützt Liquid-Variablen und [AUTOTITLE].
  • Kann nur mit layout: journey-landing 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: String, einer der Typen overview, quick_start, tutorial, how_to, reference, rai.
  • Optional.

communityRedirect

  • Zweck: Legen Sie einen benutzerdefinierten Link- und Linknamen für Ask the GitHub community Link in der Fußzeile fest.
  • 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 Frontmatterwert effectiveDate dient nur für GitHub-Mitarbeitende.

Escapesequenz für einzelne Anführungszeichen

Zwei einzelne Anführungszeichen hintereinander ('') in der YAML-Titelei, wo Sie möglicherweise nur eines erwarten würden ('), sind die bevorzugte Methode in YAML, um ein einfaches Anführungszeichen zu maskieren.

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

Beim Hinzufügen eines neuen Artikels stellen Sie sicher, dass der Dateiname eine kebab-cased Version des Titels ist, den Sie im title Frontmatter verwenden. 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. 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-, Kategorien- und Kartenthema-Unterverzeichnis verfügt über eine index.md-Datei, die einen Überblick über den Inhalt und Links zu jedem untergeordneten Artikel bietet. Jedes index.md muss eine children-Frontmatter-Eigenschaft mit einer Liste relativer Links zu den Kindseiten 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 Frontmatterwert children enthalten sind. Ist ein Verzeichnis oder ein Artikel vorhanden, aber nicht in children enthalten, gibt der Pfad einen 404-Fehler zurück.

Startseite

Die Startseite stellt die Inhaltsverzeichnis-Hauptdatei für die Dokumentationswebsite dar. Die Startseite muss eine vollständige Liste von children enthalten, wie jede Indexseite, und muss 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 Markdown-Datei mit den folgenden Frontmatter-Werten:

  • Verwenden Sie die Seitenvorlage für die Anleitungsseiten, indem Sie auf layout: product-guides verweisen.
  • Schließen Sie die Lernpfade in learningTracks ein. 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 Vordaten aller Artikel in dieser Liste die Eigenschaften topics und type enthalten.