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
redirect_from
title
shortTitle
intro
permissions
product
layout
children
childGroups
featuredLinks
showMiniToc
allowTitleToDifferFromFilename
changelog
defaultPlatform
defaultTool
learningTracks
includeGuides
type
topics
communityRedirect
effectiveDate
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 Objektversions
inlib/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 einesh1
-Elements oben auf der Seite. - Typ:
String
- Optional. Wenn nicht angegeben, wird die Seite
<title>
trotzdem festgelegt, jedoch mit einem allgemeinen Wert wieGitHub.com
oderGitHub 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.
Artikeltyp | Maximale Zeichenlänge |
---|---|
Artikel | 31 |
categories | 27 |
Kartenthemen | 30 |
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
undpermissions
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 Namencomponents/landing
lautet der Wertproduct-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 istfalse
. - 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 istfalse
. - Erforderlich für den
index.md
-Wert der Startseite.
featuredLinks
- 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 lautettrue
für Artikel undfalse
für Kartenthemen und Seiten vom Typindex.md
. - Optional.
allowTitleToDifferFromFilename
- Zweck: Angeben, ob sich der Titel einer Seite vom Dateinamen unterscheiden darf. Beispiel: Der Titel von
content/rest/reference/orgs.md
lautetOrganizations
anstelle vonOrgs
. Seiten, für die dieser Frontmatter-Wert auftrue
festgelegt ist, werden in Tests nicht gekennzeichnet oder mitsrc/content-render/scripts/reconcile-filenames-with-ids.js
aktualisiert. - Typ:
Boolean
Der Standardwert istfalse
. - 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äfixGitHub Actions:
wird z. B. der ÄnderungsprotokolltitelGitHub Actions: Some Title Here
im Dokumentationsfeed alsSome 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 sindmac
,windows
oderlinux
. - 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 sindwebui
,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 indata/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
undtopics
gefiltert werden kann. Kann nur mitlayout: 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 sindoverview
,quick_start
,tutorial
,how_to
,reference
oderrai
. - 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 sindname
undhref
. - 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.