Сведения о frontmatter YAML
Frontmatter YAML — это соглашение о разработке, популярное Jekyll, которое предоставляет способ добавления метаданных на страницы. Это блок содержимого с ключом-значением, который находится в верхней части каждого файла Markdown в GitHub Docs. Дополнительные сведения см. в документации по интерфейсу YAML.
Значения frontmatter YAML
Следующие значения frontmatter имеют специальные значения и требования для GitHub Docs.
Существует также схема, используемая набором тестов для проверки интерфейсного устройства каждой страницы.
Дополнительные сведения см. в разделе 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
- Назначение: указывает версии , к которым применяется страница. Дополнительные сведения о различных типах управления версиями см. в разделе "Документация по использованию версий".
- Введите
Object
. Допустимые ключи сопоставляют имена продуктов и находятся в объектеversions``lib/frontmatter.js
. - Это значение frontmatter в настоящее время требуется для всех страниц.
- Используется
*
для обозначения всех выпусков для версии. - Должен присутствовать для всех
index.md
файлов, но фактическое значение вычисляется во время выполнения на основе дочерних элементов.
Это значение frontmatter используется сайтом документации для создания "permalinks" для каждой версии статьи. Дополнительные сведения см. в разделе Permalinks.
Пример, применимый к free, Pro и GitHub Enterprise Server версии 3.11 и более поздних версий:
title: About your personal dashboard
versions:
fpt: '*'
ghes: '>=3.11'
Пример, который применяется только к GitHub Enterprise Server:
title: Downloading your license
versions:
ghes: '*'
Вы также можете использовать страницу для диапазона выпусков. Это позволит использовать страницу для бесплатной версии, Pro и Team и GitHub Enterprise Server версий 3.1 и 3.2:
versions:
fpt: '*'
ghes: '>=3.1 <3.3'
redirect_from
- Назначение: список URL-адресов, которые должны перенаправляться на эту страницу.
- Тип:
Array
- Необязательно
Пример:
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
Дополнительные сведения см. в разделе Настройка перенаправлений.
title
- Назначение: задайте понятное для человека название для использования в теге отрисованной страницы
<title>
иh1
элементе в верхней части страницы. - Тип:
String
- Необязательно. Если опущено, страница
<title>
по-прежнему будет задана, хотя и с универсальным значением, напримерGitHub.com
илиGitHub Enterprise
.
shortTitle
- Назначение: сокращенный вариант заголовка страницы для использования в панежах и элементах навигации.
- Тип:
String
- Необязательно. Если опущено,
title
будет использоваться.
Тип статьи | Максимальная длина символов |
---|---|
articles | 31 |
categories | 27 |
Разделы карты | 30 |
Пример:
title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects
intro
- Назначение. Задает интро для страницы. Эта строка будет отображаться после
title
. - Тип:
String
- Необязательно.
permissions
- Назначение. Задает инструкцию разрешения для статьи. Эта строка будет отображаться после
intro
. - Тип:
String
- Необязательно.
product
- Назначение. Задает выноску продукта для статьи. Эта строка будет отображаться после инструкции и
permissions
инструкцииintro
. - Тип:
String
- Необязательно.
layout
- Назначение: отрисовка правильного макета страницы.
- Тип:
String
соответствует имени макета. Для макета с именемcomponents/landing
будет значениеproduct-landing
. - Необязательно. Если опущено,
DefaultLayout
используется.
children
- Назначение. Перечисляет относительные ссылки, относящиеся к разделу продукта или категории или карты. Дополнительные сведения см. на страницах индекса.
- Введите
Array
. По умолчанию —false
. - Обязательный на
index.md
страницах.
childGroups
- Назначение: отрисовывает дочерних элементов в группы на домашней странице. Дополнительные сведения см . на домашней странице.
- Введите
Array
. По умолчанию —false
. - Требовать на домашней странице
index.md
.
featuredLinks
- Назначение. Отрисовывает названия связанных статей и встроек на целевые страницы продукта и домашнюю страницу.
- Введите
Object
. - Необязательно.
Список популярных ссылок — это ссылки, отображаемые на целевой странице под названием "Популярные". Кроме того, можно настроить заголовок "Популярный", задав featuredLinks.popularHeading
свойство новой строке.
Пример:
featuredLinks:
gettingStarted:
- /path/to/page
startHere:
- /guides/example
popular:
- /path/to/popular/article1
- /path/to/popular/article2
popularHeading: An alternate heading to Popular
showMiniToc
- Назначение: указывает, должна ли статья отображать мини-оглавление (TOC) над остальной частью содержимого. Дополнительные сведения см. в разделе "Автогенерированные мини-toCs".
- Введите
Boolean
. По умолчанию используетсяtrue
статья, аfalse
также темы иindex.md
страницы карты. - Необязательно.
allowTitleToDifferFromFilename
- Назначение. Указывает, разрешена ли страница иметь название, которое отличается от имени файла. Например,
content/rest/reference/orgs.md
имеет заголовокOrganizations
вместоOrgs
. Страницы с этим параметром frontmattertrue
не будут помечены в тестах или обновленыsrc/content-render/scripts/reconcile-filenames-with-ids.js
. - Введите
Boolean
. По умолчанию —false
. - Необязательно.
changelog
- Назначение. Отрисовка списка элементов, извлекаемых из GitHub Changelog на целевых страницах продукта (
components/landing
). Одним из исключений является образование, из https://github.blog/category/community/educationкоторого извлекается. - Тип: , свойства:
Object
label
- должен присутствовать и соответствовать меткам, используемым в журнале изменений GitHubprefix
— необязательная строка, которая запускает каждый заголовок журнала изменений, который должен быть опущен в веб-канале документации. Например, с указанным префиксомGitHub Actions:
заголовки журнала изменений, какGitHub Actions: Some Title Here
Some Title Here
и в веб-канале документов.
- Необязательно.
defaultPlatform
- Назначение. Переопределите начальный выбор платформы для страницы. Если этот интерфейсный элемент опущен, содержимое для конкретной платформы, соответствующее операционной системе читателя, по умолчанию отображается. Это поведение можно изменить для отдельных страниц, для которых более разумно выбрать вручную. Например, большинство средств выполнения GitHub Actions используют Linux, и их операционная система не зависит от операционной системы читателя.
- Тип:
String
один из:mac
,windows
,linux
. - Необязательно.
Пример:
defaultPlatform: linux
defaultTool
- Назначение. Переопределите начальный выбор инструмента для страницы, где средство ссылается на приложение, которое читатель использует для работы с GitHub (например, веб-интерфейсом GitHub.com, интерфейсом командной строки GitHub или GitHub Desktop) или API GitHub. Дополнительные сведения о селекторе инструментов см. в разделе "Использование Markdown и Liquid в документах GitHub". Если этот интерфейс опущен, содержимое, соответствующее веб-интерфейсу GitHub, отображается по умолчанию. Если пользователь указал предпочтения средства (щелкнув вкладку инструмента), то вместо значения по умолчанию будет применено предпочтение пользователя.
- Тип:
String
один из:webui
,curl``cli``graphql``importer_cli``powershell``codespaces``vscode``desktop
, .bash``javascript
- Необязательно.
defaultTool: cli
learningTracks
- Назначение: отрисовка списка треков обучения на подцеливной странице продукта.
- Введите
String
. Это должно ссылаться на имена треков обучения, определенных вdata/learning-tracks/*.yml
. - Необязательно
Примечание. Рекомендуемая дорожка устанавливается определенным свойством в обучении отслеживает YAML. Дополнительные сведения см. в readME.
includeGuides
- Назначение: отрисовка списка статей, фильтруемых по
type
иtopics
. Применимо только при использовании сlayout: product-guides
. - Тип:
Array
- Необязательно.
Пример:
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
- Назначение: укажите тип статьи.
- Тип:
String
один изoverview
, ,tutorial``quick_start
,how_to
, ,reference``rai
. - Необязательно.
topics
- Назначение: укажите темы, описанные в статье. Дополнительные сведения о добавлении тем см. в con режим палатки ls. Полный список существующих разделов находится в файле разрешенных разделов. Если разделы в статье frontmatter и список разрешенных разделов становятся не синхронизированными, тест CI завершится ошибкой.
- Тип: массив
String
s - Необязательно. Темы предпочтительнее для каждой статьи, но могут возникнуть случаи, когда существующие статьи еще не содержат темы, или добавление раздела в новую статью может не добавлять значение.
communityRedirect
- Назначение. Задайте настраиваемую ссылку и имя ссылки для
Ask the GitHub community
ссылки в нижнем колонтитуле. - Введите
Object
. Свойства иname
href
. - Необязательно.
effectiveDate
- Назначение. Установка даты действующей даты для статей об условиях обслуживания, чтобы команды инженеров могли автоматически повторно запрашивать пользователей, чтобы подтвердить условия
- Тип:
string
YEAR-MONTH-DAY, например 2021-10-04— 4 октября 2021 г. - Необязательно.
Примечание. Значение effectiveDate
frontmatter предназначено только для использования только сотрудниками GitHub.
Экранирование одиночных кавычки
Если в строке () отображаются две одинарные кавычки (''
) в frontmatter YAML, где может потребоваться увидеть один ('
), это предпочтительный способ экранирования одной кавычки.
В качестве альтернативы можно изменить одинарные кавычки, окружающие поле frontmatter, на двойные кавычки и оставить внутренние одинарные кавычки незакрытыми.
Автогенерированные мини-toCs
Каждая статья отображает мини-оглавление (TOC), которое является автоматически созданным разделом "В этой статье", который содержит ссылки на все H2
элементы статьи. В мини-toCs включены только H2
заголовки. Если статья использует H3
или H4
заголовки для разделения информации таким образом, что только определенные разделы относятся к определенной задаче, вы можете помочь людям перейти к содержимому, наиболее релевантным для них, с помощью разделального TOC.
Для предотвращения отображения мини-toC для статьи можно использовать showMiniToc
значение frontmatter.false
Мини-toCs не отображаются на целевых страницах продукта, целевых страницах категорий или страницах тем карты.
Не добавляйте жестко закодированные разделы "В этой статье" в источнике Markdown или в противном случае страница будет отображать повторяющиеся мини-toCs.
Имена файлов
При добавлении новой статьи убедитесь, что имя файла является [версией заголовка, используемого в интерфейсном шаблоне статьиtitle
.](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) Это может получить сложное, если заголовок имеет знак препинания (например, "Планы выставления счетов GitHub"). Тест помечает несоответствия между заголовком и именем файла. Чтобы переопределить это требование для данной статьи, можно добавить allowTitleToDifferFromFilename
frontmatter.
Страницы индекса
Страницы индекса — это файлы содержимого для сайта документации. У каждого продукта, категории и подкаталога раздела карты есть index.md
файл, предоставляющий обзор содержимого и ссылок на каждую дочернюю статью. Каждый index.md
из них должен содержать свойство frontmatter со списком children
относительных ссылок на дочерние страницы продукта, категории или раздела карты. Для страниц индексов требуется versions
свойство frontmatter, а фактическое значение вычисляется во время выполнения на основе версий дочерних статей.
Примечание. Сайт знает только о путях, включенных в children
frontmatter. Если каталог или статья существует, но не включена children
, путь возвращает значение 404.
Главная страница
Домашняя страница — это основной файл оглавлиния для сайта документации. Домашняя страница должна иметь полный список children
, как и каждая страница индекса, но также должна указывать childGroups
свойство frontmatter, которое будет выделено в основной области контента.
childGroups
— это массив сопоставлений, содержащий name
группу, необязательный icon
для группы и массив children
. Массив children
должен присутствовать в свойстве children
frontmatter.
Создание страниц руководства по продуктам
Чтобы создать страницу руководства по продуктам (например , GitHub Actions Руководство), создайте или измените существующий файл markdown с этими конкретными значениями frontmatter:
- Используйте шаблон страницы руководства по продуктам, ссылаясь
layout: product-guides
на нее. - Включите треки обучения в
learningTracks
. Необязательно. - Определите, с какими статьями следует включить
includeGuides
. Необязательно.
При использовании треков обучения они должны быть определены в data/learning-tracks/*.yml
.
При использовании includeGuides
убедитесь, что каждая статья в этом списке имеетtopics
и type
в его передней части.