Использование 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, см. в разделе "Руководство по стилю".

Примеры выносок

> [!NOTE] Keep this in mind.

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

Примеры выносок, отображаемых на GitHub Docs

Note

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

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

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

Для отображения синтаксиса, выделенного в инструкциях командной строки и примерах кода, мы используем тройные обратные знаки, а затем язык примера. Список всех поддерживаемых языков см. в разделе 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, см. в разделе "Использование скриптов для тестирования кода в средстве выполнения тестов".

Октиконы

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, labelled 'Delete YOUR-POLICY-NAME'." %}"). Это поможет людям определить как октикон, так и как он помечен, и дать контекст для совместной работы с людьми, которые визуально описывают Октикон.
  • Если октикон является декоративным, скорее всего, он скрыт для средств чтения с экрана с атрибутом aria-hidden=true . Если да, для согласованности с продуктом используйте aria-hidden="true" синтаксис Liquid для октикона в документах (например, "{% octicon "plus" aria-hidden="true" %} Add message").

Если вы используете Octicon другим способом, например использование значков "проверка" и "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.js объект в github/docs репозитории для списка всех поддерживаемых средств.

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

Вы можете определить средство по умолчанию для статьи в интерфейсном элементе 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 %} |

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

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

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

{% 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;">

Текущий пример использования см. в разделе "Примеры".

Ссылки на документы в 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.com ссылка отображается с помощью языкового кода:

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

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

/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply

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

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

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

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

  • /en/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-cloud@latest/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.10/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.9/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.8/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.7/get-started/getting-started-with-git/set-up-git
  • /en/enterprise-server@3.6/get-started/getting-started-with-git/set-up-git

Статья, которая недоступна в GitHub Enterprise Server будет иметь только один постоянная ссылка:

  • /en/get-started/getting-started-with-git/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. Наши документы также содержат ссылки, ссылающиеся на статьи по прошлым именам. Оба этих типа ссылок работают правильно из-за перенаправлений, но они являются ошибками.

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