Рекомендации по использованию языка Markdown

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

Конвейер сборки, который создает нашу документацию, использует markdig для обработки документов Markdown. Markdig анализирует документы на основе правил последней спецификации CommonMark . OPS следует спецификации CommonMark и добавляет некоторые расширения для функций конкретной платформы, таких как таблицы и оповещения.

Спецификация CommonMark является более строгой при построении некоторых элементов Markdown. Внимательно обратите внимание на сведения, указанные в этом документе.

Мы используем расширение Markdownlint в VS Code для применения правил стиля и форматирования. Это расширение устанавливается в составе пакета разработки Learn.

Пустые строки, пробелы и вкладки

Пустые строки также сигнализируют о конце блока в Markdown.

• Поместите одно пустое между блоками Markdown разных типов; например, между абзацем и списком или заголовком.
• Не используйте несколько пустых строк. Несколько пустых строк отображаются как одна пустая строка в HTML, поэтому лишние пустые строки являются ненужными.
• Не используйте несколько последовательных пустых строк в блоке кода, последовательные пустые строки разбивают блок кода.

Интервалы важны в Markdown.

• Удалите дополнительные пробелы в конце строк. Конечные пробелы могут изменить способ отрисовки документа Markdown.
• Всегда используйте пробелы вместо вкладок (жесткие вкладки).

Названия и заголовки

Используйте только заголовки ATX (# стиль, а не =- заголовки стилей).

• Используйте стиль предложения - следует писать с заглавной буквы только имена собственные и первую букву заголовка.
• Добавьте один пробел между # и первой буквой заголовка.
• Оберните заголовки одной пустой строкой
• Не используйте больше одной H1 на документ
  • Это должен быть первый заголовок
  • Он должен соответствовать названию статьи
• Увеличивайте уровни заголовков на один — не пропускайте уровни
• Ограничение глубины до H3 или H4
• Избегайте использования полужирного или другой разметки в заголовках

Ограничение длины строки до 100 символов

Для концептуальных статей и ссылок на командлеты ограничьте длину строки до 100 символов. Для about_ статей ограничьте длину строки до 79 символов. Ограничение длины строки повышает читаемость git диффов и истории. Это также упрощает другим авторам внесение вклада.

Используйте расширение Reflow Markdown в VS Code, чтобы переформатировать абзацы для соответствия установленной длине строки.

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

Акцент

Для акцента Markdown поддерживает полужирный и курсив. Markdown позволяет использовать либо *, либо _ для выделения акцента. Тем не менее, чтобы быть согласованным и показать намерение:

• Используйте ** для полужирного шрифта
• Используйте _ для выделения текста курсивом

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

Списки

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

Окружайте списки одной пустой строкой.

Неупорядоченные списки

• Не заканчивайте элементы списка с периодом, если они не содержат несколько предложений.
• Используйте символ дефиса (-) для маркеров элементов списка, чтобы избежать путаницы с разметкой выделения, которая использует звездочку (*).
• Чтобы включить абзац или другие элементы под элементом маркера, вставьте разрыв строки и выровняйте отступ с первым символом после маркера.

Рассмотрим пример.

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Это список, содержащий дочерние элементы под пунктом списка с маркером.

• Первый пункт списка

  Предложение, объясняющее первый пункт.

  • Дочерний элемент маркера

    Предложение, объясняющее дочерний маркер.

• Второй пункт списка

• Третий пункт списка

Упорядоченные списки

• Все элементы в нумерованном списке должны использовать число 1. , а не увеличивать каждый элемент.
  • Обработка Markdown увеличивает значение автоматически.
  • Это упрощает изменение порядка элементов и стандартизирует отступ подчиненного содержимого.
• Чтобы включить абзац или другие элементы под нумерованным элементом, выровняйте отступ с первым символом после номера элемента.

Рассмотрим пример.

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

Результирующий Markdown отображается следующим образом:

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

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

2. Следующий нумерованный элемент начинается здесь.

Изображения

Синтаксис для включения изображения:

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Где alt text краткое описание изображения и <folderPath> относительный путь к изображению.

• Альтернативный текст необходим для поддержки программ экранного чтения для слабовидящих.
• Изображения должны храниться в папке media/<article-name> внутри папки, содержащей статью.
  • Создайте папку, которая соответствует имени файла статьи в папке media . Скопируйте изображения для этой статьи в новую папку.
• Не делитесь изображениями между статьями.
  • Если изображение используется несколькими статьями, каждая папка должна иметь копию этого образа.
  • Это предотвращает изменение изображения в одной статье от воздействия на другую статью.

Поддерживаются следующие типы файлов изображений: *.png, *.gif, *.jpeg, *.jpg*.svg

Расширение Markdown — поля оповещений

Пакет разработки Learn содержит средства, которые поддерживают функции, уникальные для нашей системы публикации. Оповещения — это расширение Markdown для создания цитатных блоков, которые отображаются с цветами и значками, подчеркивающими важность содержания. Поддерживаются следующие типы оповещений:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

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

Блок заметок

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

Важный блок

Блок предостережения

Блок предупреждений

Расширение Markdown — таблицы

Таблица — это расположение данных со строками и столбцами, состоящими из следующих:

• Одна строка заголовка
• Строка разделителя, разделяющая заголовок от данных
• Ноль или больше строк данных

Каждая строка состоит из ячеек, содержащих произвольный текст, разделенный каналами (|). Для ясности также рекомендуется использовать ведущий и конечный канал. Пробелы между каналами и содержимым ячеек обрезаются. Элементы уровня блока нельзя вставить в таблицу. Все содержимое строки должно находиться в одной строке.

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

Для небольших таблиц вместо этого рекомендуется использовать список. Списки:

• Легче обслуживать и читать
• Можно перестроить текст в соответствии с ограничением строки в 100 символов.
• Больше возможностей для пользователей, использующих средства чтения с экрана для визуальной помощи

Дополнительные сведения см. в разделе "Таблицы " справочника Markdown для Microsoft Learn.

Гиперссылки

• Гиперссылки должны использовать синтаксис [friendlyname](url-or-path)Markdown.

• Система публикации поддерживает три типа ссылок:

  • URL-ссылки
  • Ссылки на файлы
  • Перекрестные ссылки

• Все URL-адреса внешних веб-сайтов должны использовать HTTPS, если это не является допустимым для целевого сайта.

• Ссылки должны иметь понятное имя, как правило, название связанной статьи

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

• Когда вы документируете определённый универсальный код ресурса (URI), можно использовать голые URL, но они должны быть заключены в обратные кавычки. Рассмотрим пример.

  By default, if you don't specify this parameter, the DMTF standard resource URI
  `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
  

• Используйте ссылочные указатели, где разрешено. Ссылки на абзацы делают абзацы более читаемыми.

  Ссылочные ссылки разделяют ссылку Markdown на две части:

  • Ссылка на ссылку — [friendlyname][id]
  • Определение ссылки — [id]: url-or-path

URL-ссылки

• ССЫЛКИ НА URL-адреса других статей learn.microsoft.com должны использовать относительные пути сайта. Самый простой способ создать относительную ссылку сайта — скопировать URL-адрес из браузера, а затем удалить https://learn.microsoft.com/en-us из значения, которое вы вставляете в markdown.
• Не включайте языковые параметры в URL-адреса на ресурсах Майкрософт (удалите /en-us из URL-адреса) или в ссылках на Википедию.
• Удалите ненужные параметры запроса из URL-адреса. Примеры, которые следует удалить:
  • ?view=powershell-5.1 — используется для связывания с определенной версией PowerShell
  • ?redirectedfrom=MSDN — добавлен в URL-адрес при перенаправлении из старой статьи в новое расположение.
• Если необходимо связать с определенной версией документа, необходимо добавить &preserve-view=true параметр в строку запроса. Например: ?view=powershell-5.1&preserve-view=true
• На сайтах Майкрософт url-адреса не содержат расширений файлов (например, нет .md)

Ссылки типа файла

• Ссылка на файл используется для ссылки из одной справочной статьи на другую или из одной концептуальной статьи в другую в том же наборе документов.
  • Если вам нужно создать ссылку из концептуальной статьи на справочную статью, необходимо использовать URL-ссылку.
  • Если вам нужно связать статью в другом наборе документов или в разных репозиториях, необходимо использовать URL-ссылку.
• Используйте относительные пути к файлам (например: ../folder/file.md)
• Все пути к файлам используют символы косой черты вперед (/)
• Включите расширение файла (например, .md)

Перекрестные ссылки

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

• Для получения ссылок на справочные материалы по API .NET, см. раздел Использование ссылок в документации в центральном руководстве для участников.

• Ссылки на командлет имеют следующий формат: xref:<module-name>.<cmdlet-name> Например, чтобы связаться с Get-Content командлетом в модуле Microsoft.PowerShell.Management .

  [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Глубокое связывание

Для URL-адресов и ссылок на файлы разрешено глубокое связывание.

• Текст привязки должен быть строчными буквами
• Добавьте привязку в конец целевого пути. Например:
  • [about_Splatting](about_Splatting.md#splatting-with-arrays)
  • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

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

Диапазоны кода

Диапазоны кода используются для фрагментов встроенного кода в абзаце. Используйте одинарные обратные кавычки, чтобы указать диапазон кода. Рассмотрим пример.

PowerShell cmdlet names use the `Verb-Noun` naming convention.

В этом примере отображается следующее:

Имена командлетов PowerShell используют Verb-Noun соглашение об именовании.

Блоки кода

Блоки кода используются для примеров команд, примеров кода с несколькими строками, языков запросов и выходных данных. Существует два способа указать, что раздел текста в файле статьи является блоком кода: окружить его тройными обратными кавычками (```) или добавить отступ.

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

Блоки заборированного кода могут содержать необязательный тег, указывающий синтаксис языка, содержащийся в блоке. Платформа публикации поддерживает список тегов языка. Тег языка используется для выделения синтаксиса при отображении статьи на веб-странице. Тег языка не учитывает регистр, но следует использовать строчные буквы, за исключением нескольких особых случаев.

• Ограждения кода без тегов можно использовать для блоков синтаксиса или других типов содержимого, в которых выделение синтаксиса не требуется.
• При отображении выходных данных из команды используйте помеченный кодовый блок с языковым тегом Output. Отрисованное поле помечено как выходные данные и не имеет выделения синтаксиса.
• Если выходные данные используются на определенном поддерживаемом языке, используйте соответствующий тег языка. Например, многие команды выводят данные в формате JSON, поэтому используйте тег json.
• Если вы используете неподдерживаемый тег языка, блок кода будет отображаться без выделения синтаксиса. Тег языка становится меткой для отрисованного поля кода на веб-странице. Сделайте тег с заглавной буквы, чтобы метка отображалась заглавной на веб-странице.

Дальнейшие действия

Руководство по стилю PowerShell