Использование Markdown и Liquid в документах GitHub

Вы можете использовать Markdown и Liquid для форматирования содержимого, создания повторно используемого содержимого и записи содержимого для разных версий GitHub Docs.

В этой статье

Сведения об использовании Markdown и Liquid в GitHub Docs

GitHub Docs написаны с помощью Markdown, который является понятным синтаксисом для форматирования обычного текста. Мы используем вариант Markdown с именем GitHub Flavored Markdown и убедитесь, что он соответствует CommonMark. Дополнительные сведения см. в разделе О написании и форматировании на GitHub.

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

Содержимое на этом сайте использует отрисовку Markdown, основанную /src/content-renderна процессоре remark Markdown.

Списки

В элементе списка общие правила дополнительного содержимого после первого абзаца:

  • Изображения и последующие абзацы должны находиться в собственной строке и разделены пустой строкой.
  • Все последующие строки в элементе списка должны соответствовать первому тексту после маркера списка.

Пример использования списка

В этом примере показан правильный способ выравнивания элементов списка с несколькими абзацами или объектами.

1. Under your repository name, click **Actions**.

   ![Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab-global-nav-update.png)

   This is another paragraph in the list.

1. This is the next item.

Это содержимое отображается на GitHub Docs сайте с содержимым под первым элементом списка правильно выровнены.

Пример списка, отрисованного в GitHub Docs

  1. Под именем своего репозитория щелкните Действия.

    Снимок экрана: вкладки для репозитория github/docs. Вкладка "Действия" выделена оранжевым контуром.

    Это еще один абзац в списке.

  2. Это следующий элемент.

видны узлы

Оповещения выделяют важную информацию, которую должны знать пользователи. Дополнительные сведения о поддерживаемых типах оповещений, форматировании их в Markdown и сведения об использовании оповещений см. в разделе Руководство по стилю.

Примеры оповещений

> [!TIP]
> Try this out!

> [!NOTE]
> Generally alerts should be short.
>
> But occasionally may require more than one paragraph

Примеры оповещений, отображаемых в GitHub Docs

Совет

Попробуйте это!

Примечание.

Как правило, оповещения должны быть короткими.

Но иногда может потребоваться несколько абзацов

Выделение синтаксиса примера кода

Для отображения синтаксиса, выделенного в инструкциях командной строки и примерах кода, мы используем тройные обратные знаки, а затем язык примера. Список всех поддерживаемых языков см. в разделе code-languages.yml.

Пример использования выделения синтаксиса кода

```bash
git init YOUR-REPOSITORY
```

В синтаксисе примера кода используйте весь текст верхнего регистра, чтобы указать замещающий текст или содержимое, которое зависит от каждого пользователя, например имени пользователя или репозитория. По умолчанию блоки кода будут экранировать содержимое в трех резервных фрагментах. Если вам нужно написать пример кода, который анализирует содержимое (например, для курсивирования текста в <em> тегах вместо передачи тегов через буквально), заключите блок кода в <pre> теги.

Блоки кода с кнопкой копирования

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

Например, следующий код добавляет выделение синтаксиса для JavaScript и кнопку копирования для примера кода.

Пример использования кнопки копирования

```javascript copy
const copyMe = true
```

Пример кода, отрисованного в GitHub Docs

JavaScript
const copyMe = true

Примеры заметок кода

Примеры заметок кода помогают объяснить более длинные примеры кода путем отрисовки комментариев в виде заметок рядом с примером кода. Это позволяет создавать более длинные объяснения кода без загромождения самого кода. Примеры кода с заметками отображаются в макете двух областей с примером кода слева и заметками справа. Заметки визуально подчеркиваются при наведении курсора на пример кода.

Заметки кода работают только в статьях со свойством layout: inline frontmatter. Дополнительные сведения о написании и стили заметок кода см. в разделе Примеры кода аннотирования.

Пример аннотированного кода

```yaml annotate
# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: Post welcome comment
# The `on` keyword lets you define the events that trigger when the workflow is run.
on:
  # Add the `pull_request` event, so that the workflow runs automatically
  # every time a pull request is created.
  pull_request:
    types: [opened]
# Modifies the default permissions granted to `GITHUB_TOKEN`.
permissions:
  pull-requests: write
# Defines a job with the ID `build` that is stored within the `jobs` key.
jobs:
  build:
    name: Post welcome comment
    # Configures the operating system the job runs on.
    runs-on: ubuntu-latest
    # The `run` keyword tells the job to execute the [`gh pr comment`](https://cli.github.com/manual/gh_pr_comment) command on the runner.
    steps:
      - run: gh pr comment $PR_URL --body "Welcome to the repository!"
        env:
          GH_TOKEN: $
          PR_URL: $
```

Пример статьи, в которую используются заметки GitHub Docsкода, см. в разделе Публикация и установка пакета с помощью GitHub Actions.

Copilot Запросы

Запросы Copilot могут отображаться в блоках или включаться в текст.

Блоки запроса

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

Блоки запросов всегда должны иметь кнопку копирования, добавленную с помощью copy параметра, а также Copilot кнопку, добавленную prompt с помощью параметра. Кнопка Copilot позволяет средству чтения быстро запустить запрос.Копилот ЧатGitHub.com Параметры copy и prompt параметры можно использовать в любом порядке.

Пример блока запроса с Copilot кнопками копирования и копирования

```copilot prompt copy
What is git?
```

Это отрисовывается следующим образом:

Copilot prompt
What is git?

Если вы должны добавить только кнопку Copilot в блок запроса:

  • Запрос можно запустить без дополнительного контекста (как показано в приведенном выше примере).
  • В той же статье есть блок кода, который предоставляет необходимый контекст для запроса.

Включение контекста с запросом

Если вы используете кнопку Copilot , вы можете добавить контекст в запрос, на который отправляется Копилот Чат ссылка на блок кода в той же статье. Для этого добавьте id=STRING-OF-YOUR-CHOICE блок кода и ref=STRING-OF-YOUR-CHOICE в блок запроса.

Пример блока кода, используемого в качестве контекста в блоке запроса

Add an id to the code block whose code you want to add to the prompt as context:

```javascript id=js-age
function logPersonsAge(a, b, c) {
  if (c) {
    console.log(a + " is " + b + " years old.");
  } else {
    console.log(a + " does not want to reveal their age.");
  }
}
```

Then, elsewhere in the same article, reference the id in the prompt block:

```copilot copy prompt ref=js-age
Improve the variable names in this function
```

Существует множество примеров блоков запроса с контекстом в книге Copilot Кука. Например, см . раздел AUTOTITLE.

Встроенные запросы

Для большинства встроенных запросов помечайте их с помощью обратных символов, как и встроенный код.

Если запрос не требует контекста, после запроса можно добавить значок, доступный Copilot для щелчка. Это позволяет средству чтения запускать запрос включено Копилот ЧатGitHub.com. Чтобы добавить значок щелчка, введите запрос с тегами синтаксиса Liquid:

... you can click {% prompt %}what is git{% endprompt %} to run this ...

Это отрисовывается следующим образом:

... вы можете щелкнуть , что такое git , чтобы запустить эту ...

Октиконы

Octicons — это значки, используемые в GitHubинтерфейсе. Мы ссылаемся на Octicons при документе пользовательского интерфейса и указываем двоичные значения в таблицах. Найдите имя определенных Октикосов на сайте Octicons.

Если вы ссылаетесь на октикон, который отображается в пользовательском интерфейсе, определите, является ли октикон целым меткой элемента пользовательского интерфейса (например, кнопкой, помеченной только "+") или только декоративным, в дополнение к другой метке (например, кнопка "+ Добавить сообщение").

  • Если Октикон является всей меткой, используйте средства разработчика браузера, чтобы проверить октикон и определить, какие пользователи средства чтения с экрана будут слышать. Затем используйте этот текст для aria-label (например, {% octicon "plus" aria-label="Add file" %}). Иногда в пользовательском интерфейсе сам Octicon не будет иметь aria-labelэлемент, а окружающий элемент, например <summary>``<div> , тег.
    • Некоторые октиконы, используемые в качестве меток, имеют динамические aria-label элементы, которые изменяются на основе состояния элемента пользовательского интерфейса или ввода пользователя. Например, если у кого-то есть две политики безопасности,Policy A и Policy Bпользовательский интерфейс будет отображать два корзины Octicons помечены {% octicon "trash" aria-label="Delete Policy A" %} и {% octicon "trash" aria-label="Delete Policy B" %}. Для динамических aria-label элементов, так как мы не можем документировать точное aria-label , что люди будут столкнуться, описать октикон и пример заполнителя метки (например, "{% octicon "trash" aria-label="The trash icon, labeled 'Delete YOUR-POLICY-NAME'." %}"). Это поможет людям определить как октикон, так и как он помечен, и дать контекст для совместной работы с людьми, которые визуально описывают Октикон.
  • Если октикон является декоративным, скорее всего, он скрыт для средств чтения с экрана с атрибутом aria-hidden=true . Если да, для согласованности с продуктом используйте aria-hidden="true" синтаксис Liquid для октикона в документах (например, "{% octicon "plus" aria-hidden="true" %} Add message").

Если вы используете Octicon другим способом, например использование значков check и x для отражения двоичных значений в таблицах, используйте aria-label его для описания смысла октикона, а не его визуальных характеристик. Например, если вы используете значок "x" в столбце "Поддерживаемый" таблицы, используйте "Не поддерживается" в качестве aria-labelзначения. Дополнительные сведения см. в разделе Руководство по стилю.

Пример использования Octicons

{% octicon "<name of Octicon>" %}
{% octicon "plus" %}
{% octicon "plus" aria-label="Add file" %}
"{% octicon "plus" aria-hidden="true" %} Add file"

Теги операционной системы

Иногда нам нужно написать документацию для разных операционных систем. Для каждой операционной системы может потребоваться другой набор инструкций. Теги операционной системы используются для демаркации сведений для каждой операционной системы.

Пример использования тегов операционной системы

{% mac %}

These instructions are pertinent to Mac users.

{% endmac %}

{% linux %}

 These instructions are pertinent to Linux users.

{% endlinux %}

{% windows %}

These instructions are pertinent to Windows users.

{% endwindows %}

Вы можете определить платформу по умолчанию в интерфейсном элементе YAML статьи. Дополнительные сведения см. в разделе Использование frontmatter YAML.

Теги инструментов

Иногда нам нужно написать документацию, которая содержит разные инструкции для различных инструментов. Например, GitHub пользовательский интерфейс, GitHub CLI, GitHub Desktopи GitHub Codespacesможет иметь возможность выполнить одну и Visual Studio Code ту же задачу с помощью различных шагов. Теги инструментов используются для управления отображаемыми сведениями для каждого средства.

GitHub Docs поддерживает теги инструментов для GitHub продуктов и выбранных сторонних расширений. См. all-tools.ts объект в github/docs репозитории для списка всех поддерживаемых средств.

В редких случаях мы добавим новые инструменты. Перед добавлением нового средства прочитайте Создание переключателей инструментов в статьях. Чтобы добавить новое средство, добавьте запись в allTools объект в lib/all-tools.ts качестве пары "ключ-значение". Ключом является тег, который вы будете использовать для ссылки на инструмент в статье, и значением является то, как средство будет идентифицировано в средстве выбора инструментов в верхней части статьи.

Вы можете определить средство по умолчанию для статьи в интерфейсном элементе YAML. Дополнительные сведения см. в разделе Использование frontmatter YAML.

Пример использования тегов инструментов

{% api %}

These instructions are pertinent to API users.

{% endapi %}

{% bash %}

These instructions are pertinent to Bash shell commands.

{% endbash %}

{% cli %}

These instructions are pertinent to GitHub CLI users.

{% endcli %}

{% codespaces %}

These instructions are pertinent to Codespaces users. They are mostly used outside the Codespaces docset, when we want to refer to how to do something inside Codespaces. Otherwise `webui` or `vscode` may be used.

{% endcodespaces %}

{% curl %}

These instructions are pertinent to curl commands.

{% endcurl %}

{% desktop %}

 These instructions are pertinent to GitHub Desktop.

{% enddesktop %}

{% importer_cli %}

These instructions are pertinent to GitHub Enterprise Importer CLI users.

{% endimporter_cli %}

{% javascript %}

These instructions are pertinent to javascript users.

{% endjavascript %}

{% jetbrains %}

These instructions are pertinent to users of JetBrains IDEs.

{% endjetbrains %}

{% powershell %}

These instructions are pertinent to `pwsh` and `powershell` commands.

{% endpowershell %}

{% vscode %}

These instructions are pertinent to VS Code users.

{% endvscode %}

{% webui %}

These instructions are pertinent to GitHub UI users.

{% endwebui %}

Многократно используемые и переменные строки текста

Многократно используемые строки (часто называемые ссылками на содержимое или conrefs) содержат содержимое, которое используется в нескольких местах в нашей документации. Создание этих данных позволяет обновлять содержимое в одном расположении, а не каждое место, где отображается строка.

Для более длинных строк мы используем повторно используемые строки и для более коротких строк, мы используем переменные. Дополнительные сведения о повторно используемых и переменных см. в разделе Создание повторно используемых содержимого.

Каналы таблиц

Каждая строка таблицы в GitHub Docs ней должна начинаться и заканчиваться каналом, даже строки, |содержащие только управление версиями Liquid.

| Where is the table located? | Does every row end with a pipe? |
| --- | --- |
| {% ifversion some-cool-feature %} |
| GitHub Docs | Yes |
| {% endif %} |

Заголовки строк таблицы

Если вы создаете таблицу, в которой первый столбец содержит заголовки для строк таблицы, заключите таблицу в тег {% rowheaders %} {% endrowheaders %}Liquid. Дополнительные сведения об использовании разметки для таблиц см. в разделе Руководство по стилю.

Пример таблицы с заголовками строк

{% rowheaders %}

|             | Mona | Tom    | Hobbes |
|-------------|------|--------|--------|
|Type of cat  | Octo | Tuxedo | Tiger  |
|Likes to swim| Yes  | No     | No     |

{% endrowheaders %}

Пример таблицы без заголовков строк

| Name   | Vocation         |
| ------ | ---------------- |
| Mona   | GitHub mascot    |
| Tom    | Mouse antagonist |
| Hobbes | Best friend      |

Таблицы с блоками кода

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

Так как таблицы в GitHub Flavored Markdown не могут содержать разрывы строк или структуры уровня блоков, необходимо использовать теги HTML для записи структуры таблицы.

Если html-таблицы содержат блоки кода, ширина таблицы может превышать обычную ширину содержимого страницы, а затем переполнение в область, содержащую мини-оглавление.

Если это произойдет, добавьте следующий стиль CSS в <table> html-тег:

<table style="table-layout: fixed;">

Текущий пример использования см. в разделе Управление работой с помощью GitHub Actions.

Ссылки на документы в docs репозитории должны начинаться с идентификатора продукта (например /actions , или /admin) и содержать весь файловый путь, но не расширение файла. Например, /actions/creating-actions/about-custom-actions.

Пути к изображениям должны начинаться и /assets содержать весь файловый путь, включая расширение файла. Например, /assets/images/help/settings/settings-account-delete.png.

Ссылки на страницы Markdown проходят некоторые преобразования на стороне сервера, чтобы соответствовать языку и версии текущей страницы. Обработка этих преобразований живет в lib/render-content/plugins/rewrite-local-links.

Например, если в файл содержимого включена следующая ссылка:

/github/writing-on-github/creating-a-saved-reply

При просмотре GitHub Docsссылка отображается с помощью языкового кода:

/en/github/writing-on-github/creating-a-saved-reply

и при просмотре в GitHub Enterprise Server документации версия также включается:

/en/[email protected]/github/writing-on-github/creating-a-saved-reply

Дополнительные сведения о ссылках см. в разделе Руководство по стилю.

Так как сайт является динамическим, он не создает HTML-файлы для каждой версии статьи. Вместо этого он создает "permalink" для каждой версии статьи. Это делается на основе фронтматтераversions

Примечание.

В начале 2021 free-pro-team@latest года версия не включена в URL-адреса. Вспомогательная функция, вызванная lib/remove-fpt-from-path.ts удалением версии из URL-адресов.

Например, в статье, доступной в текущих поддерживаемых версиях, будут иметься URL-адреса постоянной связи, как показано ниже:

В статье, недоступной в GitHub Enterprise Server этой статье, будет только одна ссылка на несколько ссылок:

  • /en/get-started/git-basics/set-up-git

Примечание.

Если вы являетесь участником содержимого, вам не нужно беспокоиться о поддерживаемых версиях при добавлении ссылки на документ. Следуя приведенным выше примерам, если вы хотите ссылаться на статью, можно просто использовать его относительное расположение: /github/getting-started-with-github/set-up-git

При связывании с другой GitHub Docs страницей используйте стандартный синтаксис Markdown, например [](), но введите AUTOTITLE вместо заголовка страницы. Приложение GitHub Docs заменит AUTOTITLE название связанной страницы во время отрисовки. Это специальное ключевое слово учитывает регистр, поэтому следите за вводом или заменой не будет работать.

  • For more information, see [AUTOTITLE](/path/to/page).
  • For more information, see [AUTOTITLE](/path/to/page#section-link).
  • For more information, see the TOOLNAME documentation in [AUTOTITLE](/path/to/page?tool=TOOLNAME).

Примечание.

Ссылки на один и тот же раздел не работают с этим ключевым словом. Вместо этого введите полный текст заголовка.

Связывание с текущей статьей в другой версии документации

Иногда может потребоваться связать статью с той же статьей в другой версии продукта. Например:

  • Вы упоминаете некоторые функции, которые недоступны для бесплатных, профессиональных или командных планов, и вы хотите связать с GitHub Enterprise Cloud версией той же страницы.
  • Версия GitHub Enterprise Server статьи описывает функцию, которая поставляется с этой версией, но администраторы сайта могут обновиться до последней версии используемой функции GitHub Enterprise Cloud.

Вы можете связаться непосредственно с другой версией страницы с помощью currentArticle свойства. Это означает, что ссылка будет продолжать работать непосредственно, даже если URL-адрес статьи изменяется.

{% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest{{ currentArticle }}).{% endif %}

Предотвращение преобразований

Иногда вы хотите связаться со статьей только Dotcom в корпоративном контенте, и вы не хотите, чтобы ссылка была уведомлена Enterprise. Чтобы предотвратить преобразование, следует включить предпочтительную версию в путь.

[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service)

Иногда каноническое домашнее содержимое перемещается за пределы сайта документации. Ни одна из ссылок, включенных в src/redirects/lib/external-sites.json получение перезаписи. Дополнительные сведения об этом типе перенаправления см. в этой contributing/redirects.md статье.

В наших документах содержатся ссылки, использующие устаревшие файловые пути, такие как /article/article-name или /github/article-name. Наши документы также содержат ссылки, ссылающиеся на статьи по прошлым именам. Оба этих типа ссылок работают правильно из-за перенаправлений, но они являются ошибками.

При добавлении ссылки на статью используйте текущее имя файла и статьи.