Использование frontmatter YAML

Интерфейс YAML можно использовать для определения управления версиями, добавления метаданных и управления макетом статей.

В этой статье

Сведения о frontmatter YAML

Frontmatter YAML — это соглашение о разработке, популярное Jekyll, которое предоставляет способ добавления метаданных на страницы. Это блок содержимого с ключом-значением, который находится в верхней части каждого файла Markdown в GitHub Docs. Дополнительные сведения см. в документации по интерфейсу YAML.

Значения frontmatter YAML

Следующие значения frontmatter имеют специальные значения и требования для GitHub Docs. Существует также схема, используемая набором тестов для проверки интерфейсного устройства каждой страницы. Дополнительные сведения см. в разделе lib/frontmatter.js.

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 будет использоваться.
Тип статьиМаксимальная длина символов
articles31
categories27
Разделы карты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.
  • Назначение. Отрисовывает названия связанных статей и встроек на целевые страницы продукта и домашнюю страницу.
  • Введите 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. Страницы с этим параметром frontmatter true не будут помечены в тестах или обновлены src/content-render/scripts/reconcile-filenames-with-ids.js.
  • Введите Boolean. По умолчанию — false.
  • Необязательно.

changelog

  • Назначение. Отрисовка списка элементов, извлекаемых из GitHub Changelog на целевых страницах продукта (components/landing). Одним из исключений является образование, из https://github.blog/category/community/educationкоторого извлекается.
  • Тип: , свойства: Object
    • label - должен присутствовать и соответствовать меткам, используемым в журнале изменений GitHub
    • prefix — необязательная строка, которая запускает каждый заголовок журнала изменений, который должен быть опущен в веб-канале документации. Например, с указанным префиксом 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.
  • Необязательно

Note

Функция отслеживания устанавливается определенным свойством в обучаемом треке 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 завершится ошибкой.
  • Тип: массив Strings
  • Необязательно. Темы предпочтительнее для каждой статьи, но могут возникнуть случаи, когда существующие статьи еще не содержат темы, или добавление раздела в новую статью может не добавлять значение.

communityRedirect

  • Назначение. Задайте настраиваемую ссылку и имя ссылки для Ask the GitHub community ссылки в нижнем колонтитуле.
  • Введите Object. Свойства и name href.
  • Необязательно.

effectiveDate

  • Назначение. Установка даты действующей даты для статей об условиях обслуживания, чтобы команды инженеров могли автоматически повторно запрашивать пользователей, чтобы подтвердить условия
  • Тип: string YEAR-MONTH-DAY, например 2021-10-04— 4 октября 2021 г.
  • Необязательно.

Note

Значение 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, а фактическое значение вычисляется во время выполнения на основе версий дочерних статей.

Note

Сайт знает только о путях, включенных в 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 в его передней части.