Шаблон метаданных и Markdown для документов .NET

Этот шаблон dotnet/docs содержит примеры синтаксиса Markdown и рекомендации по настройке метаданных.

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

Метаданные

Обязательный блок метаданных находится в следующем примере блока метаданных:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents

Необходимо иметь пробел между двоеточием (:) и значением элемента метаданных.
Двоеточия в значении (например, заголовке) ломают синтаксический анализатор метаданных. В этом случае заголовок окружает двойными кавычками (например, title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: отображается в результатах поисковой системы. Заголовок не должен совпадать с заголовком H1, и он должен содержать 60 символов или меньше.
описание. Суммирует содержимое статьи. Обычно он отображается на странице результатов поиска, но он не используется для ранжирования поиска. Его длина должна составлять 115–145 символов, включая пробелы.
автор: поле автора должно содержать имя пользователя GitHub автора.
ms.date: дата последнего значительного обновления. Обновите эту информацию о существующих статьях, если вы рассмотрели и обновили всю статью. Небольшие исправления, такие как опечатки или аналогичные, не гарантируют обновление.

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

Базовый Markdown, GFM и специальные символы

Вы можете изучить основы Markdown, GitHub Flavored Markdown (GFM) и конкретные расширения OPS в справочной статье по Markdown.

Markdown использует специальные символы, такие как *, ', и # для форматирования. Если вы хотите включить один из этих символов в содержимое, необходимо выполнить одно из двух действий:

Поместите обратную косую черту перед специальным символом, чтобы «экранировать» его (например, экранирование символа * будет выглядеть как \*).
Используйте код сущности HTML для символа (например, * для *).

Имена файлов

Имена файлов используют следующие правила:

Содержит только строчные буквы, цифры и дефисы.
Пробелы или знаки препинания отсутствуют. Используйте дефисы для разделения слов и чисел в имени файла.
Используйте конкретные команды действий, такие как разработка, покупка, сборка, устранение неполадок. Недопустимо использование слов с окончанием -ing.
Исключите маленькие слова, такие как на, и, в, или.
Должно быть в формате Markdown и использовать расширение файла .md.
Оставить имена файлов достаточно короткими. Они являются частью URL-адреса для ваших статей.

Заголовки

Используйте заглавные буквы в стиле предложений. Всегда прописывайте первое слово заголовка.

Стилизация текста

Italics
Используется для файлов, папок, путей (для длинных элементов, разделённых на отдельные строки), новых терминов.

Жирный
Используется для элементов пользовательского интерфейса.

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

Links

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

Команда документации .NET использует следующие соглашения:

В большинстве случаев мы используем относительные ссылки и не рекомендуем использовать ссылки типа ~/, так как относительные ссылки обрабатываются в источнике на GitHub. Однако всякий раз, когда мы ссылаемся на файл в зависимом репозитории, мы используем ~/ символ для предоставления пути. Так как файлы в зависимом репозитории находятся в другом месте на GitHub, относительные ссылки не работают правильно, независимо от того, как они были записаны.
Спецификация языка C# и спецификация языка Visual Basic включены в документы .NET, включая источник из репозиториев языка. Источники markdown управляются в репозиториях csharplang и vblang .

Ссылки на спецификацию должны указывать на исходные каталоги, в которых включены эти спецификации. Для C# это ~/_csharplang/spec , а для VB — ~/_vblang/spec, как показано в следующем примере:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Ссылки на API

Система сборки имеет некоторые расширения, которые позволяют нам связываться с API .NET без использования внешних ссылок. Используется один из следующих синтаксисов:

Автоматическая ссылка: <xref:UID> или <xref:UID?displayProperty=nameWithType>

Параметр displayProperty запроса создает полностью квалифицированный текст ссылки. По умолчанию текст ссылки отображает только имя члена или типа.
Ссылка Markdown: [link text](xref:UID)

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

Примеры.

<xref:System.String> отрисовывается как строка
<xref:System.String?displayProperty=nameWithType> отображается как System.String
[String class](xref:System.String) Отрисовывается как класс String

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

Некоторые уникальные идентификаторы содержат специальные символы `, # или *. Значение UID должно быть закодировано в формате HTML как %60, %23 и %2A соответственно. Иногда вы увидите скобки, закодированные, но это не обязательно.

Примеры.

System.Threading.Tasks.Task`1 становится System.Threading.Tasks.Task%601
System.Exception.#ctor становится System.Exception.%23ctor
System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) становится System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Если вы добавляете * (или %2A) после UID, ссылка затем представит страницу перегрузки и не будет вести на конкретный API. Например, можно использовать это, если вы хотите ссылаться на страницу метода List<T>.BinarySearch в общем виде вместо конкретной перегрузки, такой как List<T>.BinarySearch(T, IComparer<T>). Вы также можете использовать * для ссылки на страницу участника, если участник не перегружен; это избавляет вас от необходимости включать список параметров в UID.

Чтобы указать на конкретную перегрузку метода, необходимо указать полное имя типа каждого из параметров метода. Например, <xref:System.DateTime.ToString> ссылается на метод DateTime.ToString без параметров, а <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> ссылается на метод DateTime.ToString(String,IFormatProvider).

Чтобы связаться с универсальным типом, например System.Collections.Generic.List<T>, используйте символ '(%60), за которым следует число параметров универсального типа. Например, <xref:System.Nullable%601> ссылается на тип System.Nullable<T>, а <xref:System.Func%602> ссылается на делегат System.Func<T,TResult>.

Code

Лучший способ включения кода — включить фрагменты из рабочего примера. Создайте пример, следуя инструкциям, указанным в статье по вкладу в .NET. Включение фрагментов из полных программ гарантирует, что весь код выполняется через нашу систему непрерывной интеграции (CI). Однако если вам нужно показать что-то, что приводит к ошибкам времени компиляции или среды выполнения, можно использовать встроенные блоки кода.

Сведения о синтаксисе Markdown для отображения кода в документах см. в разделе "Как включить код в документы".

Изображения

Статическое изображение или анимированный GIF

![this is the alt text](../images/Logo_DotNet.png)

Связанный образ

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Videos

Вы можете внедрить видео YouTube в файл Markdown. Чтобы получить правильный URL-адрес видео, щелкните по видео правой кнопкой мыши, выберите "Копировать код для вставки" и скопируйте URL-адрес из элемента <iframe>.

> [!VIDEO <youtube_video_link>]

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

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

расширения Microsoft Learn

learn.microsoft предоставляет несколько дополнительных расширений для GitHub Flavored Markdown.

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

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

> [!div class="checklist"]
>
> - How to create a .NET Core app
> - How to add a reference to the Microsoft.XmlSerializer.Generator package
> - How to edit your MyApp.csproj to add dependencies
> - How to add a class and an XmlSerializer
> - How to build and run the application

Это отображается:

Создание приложения .NET Core
Добавление ссылки на пакет Microsoft.XmlSerializer.Generator
Как изменить MyApp.csproj для добавления зависимостей
Как добавить класс и XmlSerializer
Как создать и запустить приложение

Вы можете увидеть пример проверочных списков в действии в документации .NET Core.

Кнопки

Ссылки на кнопки:

> [!div class="button"]
> [button links](dotnet-contribute.md)