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

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

В этой статье

Сведения о frontmatter YAML

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

Значения frontmatter YAML

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

versions

  • Назначение: указывает версии , к которым применяется страница. Дополнительные сведения о различных типах управления версиями см . в документации по использованию версий.
  • Введите . Допустимые ключи сопоставляют имена продуктов и находятся в объекте.
  • Это значение frontmatter в настоящее время требуется для всех страниц.
  • Используется для обозначения всех выпусков для версии.
  • Должен присутствовать для всех файлов, но фактическое значение вычисляется во время выполнения на основе дочерних элементов.

Это значение 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-адресов, которые должны перенаправляться на эту страницу.
  • Тип:
  • Необязательно

Пример:

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

Дополнительные сведения см. в разделе AUTOTITLE.

title

  • Назначение: задайте понятное для человека название для использования в теге отрисованной страницы и элементе в верхней части страницы.
  • Тип:
  • Необходимые.

shortTitle

  • Назначение: сокращенный вариант заголовка страницы для использования в панежах и элементах навигации.
  • Тип:
  • Необязательно. Если опущено, будет использоваться.
Тип статьиМаксимальная длина символов
articles31
categories27
Разделы карты30

Пример:

title: Contributing to projects with GitHub Desktop
shortTitle: Contributing to projects

intro

  • Назначение. Задает интро для страницы. Эта строка будет отображаться после .
  • Тип:
  • Необязательно.

permissions

  • Назначение. Задает инструкцию разрешения для статьи. Эта строка будет отображаться после .
  • Тип:
  • Необязательно.

product

  • Назначение. Задает выноску продукта для статьи. Эта строка будет отображаться после инструкции и инструкции.
  • Тип:
  • Необязательно.

layout

  • Назначение: отрисовка правильного макета страницы.
  • Тип: соответствует имени макета. Для макета с именем будет значение .
  • Необязательно. Если опущено, используется.

children

  • Назначение. Перечисляет относительные ссылки, относящиеся к разделу продукта или категории или карты. Дополнительные сведения см. на страницах индекса.
  • Введите . По умолчанию — .
  • Обязательный на страницах.

childGroups

  • Назначение: отрисовывает дочерних элементов в группы на домашней странице. Дополнительные сведения см . на домашней странице.
  • Введите . По умолчанию — .
  • Требовать на домашней странице .
  • Назначение. Отрисовывает названия связанных статей и встроек на целевые страницы продукта и домашнюю страницу.
  • Введите .
  • Необязательно.

Список популярных ссылок — это ссылки, отображаемые на целевой странице под названием "Популярные". Кроме того, можно настроить заголовок "Популярный", задав свойство новой строке.

Пример:

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".
  • Введите . По умолчанию используется статья, а также темы и страницы карты.
  • Необязательно.

allowTitleToDifferFromFilename

  • Назначение. Указывает, разрешена ли страница иметь название, которое отличается от имени файла. Например, имеет заголовок вместо . Страницы с этим параметром frontmatter не будут помечены в тестах или обновлены .
  • Введите . По умолчанию — .
  • Необязательно.

changelog

  • Цель: Отрендерить список элементов, взятых из #REF! Changelog на лендинг страницах продукта (components/landing). Одним из исключений является образование, из которого извлекается.
  • Тип: , свойства: * label -- должен присутствовать и соответствовать меткам, используемым в #REF! Changelog
    • — необязательная строка, которая запускает каждый заголовок журнала изменений, который должен быть опущен в веб-канале документации. Например, при указанном префиксе GitHub Actions: заголовки из журнала изменений, такие как GitHub Actions: Some Title Here, будут отображаться как Some Title Here в ленте документации.
  • Необязательно.

defaultPlatform

  • Назначение. Переопределите начальный выбор платформы для страницы. Если этот интерфейсный элемент опущен, содержимое для конкретной платформы, соответствующее операционной системе читателя, по умолчанию отображается. Это поведение можно изменить для отдельных страниц, для которых более разумно выбрать вручную. Например, большинство средств выполнения GitHub Actions используют Linux, и их операционная система не зависит от операционной системы читателя.
  • Тип: один из: , , .
  • Необязательно.

Пример:

defaultPlatform: linux

defaultTool

  • Цель: Переопределить начальный выбор инструмента для страницы, где инструмент ссылается на приложение, которое читатель использует для работы с #REF! (например, веб-интерфейс #REF!.com, #REF! CLI или #REF! Desktop) или API #REF!. Дополнительные сведения о селекторе инструментов см. в разделе AUTOTITLE. Если этот фронтматтер отсутствует, то по умолчанию отображается контент, специфичный для инструмента, соответствующий веб-интерфейсу #REF!. Если пользователь указал предпочтения средства (щелкнув вкладку инструмента), то вместо значения по умолчанию будет применено предпочтение пользователя.
  • Тип: один из: , , .
  • Необязательно.
defaultTool: cli

learningTracks

  • Назначение: отрисовка списка треков обучения на подцеливной странице продукта.
  • Введите . Это должно ссылаться на имена треков обучения, определенных в .
  • Необязательно

Примечание.

Функция отслеживания устанавливается определенным свойством в обучаемом треке YAML. Дополнительные сведения см. в readME.

includeGuides

  • Назначение: отрисовка списка статей, фильтруемых по и . Применимо только при использовании с .
  • Тип:
  • Необязательно.

Пример:

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

  • Цель: Определение путей для целевых страниц путешествий.
  • Тип: объектов со следующими свойствами:
    • (обязательно): уникальный идентификатор поездки. Идентификатор должен быть уникальным только для поездок в пределах одной целевой страницы.
    • (обязательно): Отображение заголовка для поездки (поддерживает переменные Liquid)
    • (опционально): Описание пути (поддерживает переменные Liquid)
    • (требуется): Набор путеводных объектов, составляющих это путешествие. Каждый направляющий объект имеет:
    • (обязательно): Путь к статье
    • (опционально): Пользовательский текст, направляющий пользователей к альтернативным путям путешествия. Поддерживает жидкие переменные и .
  • Применимо только при использовании с .
  • Необязательно.

Пример:

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

  • Назначение: укажите тип статьи.
  • Тип: один из , , , , , .
  • Необязательно.

communityRedirect

  • Цель: Установить пользовательскую ссылку и имя ссылки для ссылки Ask the #REF! community в нижнем месте.
  • Введите . Свойства и .
  • Необязательно.

effectiveDate

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

Примечание.

Значение frontmatter используется только сотрудниками GitHub.

Экранирование одиночных кавычки

Если в строке () отображаются две одинарные кавычки () в frontmatter YAML, где может потребоваться увидеть один (), это предпочтительный способ экранирования одной кавычки.

В качестве альтернативы можно изменить одинарные кавычки, окружающие поле frontmatter, на двойные кавычки и оставить внутренние одинарные кавычки незакрытыми.

Автогенерированные мини-toCs

Каждая статья отображает мини-оглавление (TOC), которое является автоматически созданным разделом "В этой статье", который содержит ссылки на все элементы статьи. В мини-toCs включены только заголовки. Если статья использует или заголовки для разделения информации таким образом, что только определенные разделы относятся к определенной задаче, вы можете помочь людям перейти к содержимому, наиболее релевантным для них, с помощью разделального TOC.

Для предотвращения отображения мини-toC для статьи можно использовать значение frontmatter.

Мини-toCs не отображаются на целевых страницах продукта, целевых страницах категорий или страницах тем карты.

Не добавляйте жестко закодированные разделы "В этой статье" в источнике Markdown или в противном случае страница будет отображать повторяющиеся мини-toCs.

Имена файлов

При добавлении новой статьи убедитесь, что имя файла является версией заголовка, используемого в интерфейсном шаблоне статьи. Это может быть сложно, если в заголовке есть пунктуация (например, «#REF!'s Billing Plans»). Тест помечает несоответствия между заголовком и именем файла. Чтобы переопределить это требование для данной статьи, можно добавить frontmatter.

Страницы индекса

Страницы индекса — это файлы содержимого для сайта документации. У каждого продукта, категории и подкаталога раздела карты есть файл, предоставляющий обзор содержимого и ссылок на каждую дочернюю статью. Каждый из них должен содержать свойство frontmatter со списком относительных ссылок на дочерние страницы продукта, категории или раздела карты. Для страниц индексов требуется свойство frontmatter, а фактическое значение вычисляется во время выполнения на основе версий дочерних статей.

Примечание.

Сайт знает только о путях, включенных в frontmatter. Если каталог или статья существует, но не включена , путь возвращает значение 404.

Главная страница

Домашняя страница — это основной файл оглавлиния для сайта документации. Домашняя страница должна иметь полный список , как и каждая страница индекса, но также должна указывать свойство frontmatter, которое будет выделено в основной области контента.

— это массив сопоставлений, содержащий группу, необязательный для группы и массив . Массив должен присутствовать в свойстве frontmatter.

Создание страниц руководства по продуктам

Чтобы создать страницу руководства по продуктам (например , GitHub Actions Руководство), создайте или измените существующий файл markdown с этими конкретными значениями frontmatter:

  • Используйте шаблон страницы руководства по продуктам, ссылаясь на нее.
  • Включите треки обучения в . Необязательно.
  • Определите, с какими статьями следует включить . Необязательно.

При использовании треков обучения они должны быть определены в . При использовании убедитесь, что каждая статья в этом списке имеети в его передней части.