Включение кода в документацию

Есть несколько способов, отличных от снимков экрана , чтобы включить код в статью, опубликованную на Microsoft Learn:

Отдельные элементы (слова) в строке. Ниже приведен пример стиля code . Используйте формат кода при ссылке на именованные параметры и переменные в ближайшем блоке кода в тексте. Формат кода также можно использовать для свойств, методов, классов и ключевых слов языка. Дополнительные сведения см. в разделе Элементы кода далее в этой статье.
Блоки кода в файле Markdown, содержащем статью.

 ```csharp public static void Log(string message) < _logger.LogInformation(message); >```

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26".

. code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5".

. code source="PowerShell.ps1" interactive="cloudshell-powershell".

Помимо описания синтаксиса Markdown для каждого метода включения кода, в статье приведено общее руководство для всех блоков кода.

Элементы кода

«Элемент кода» является ключевым словом языка программирования, именем класса, именем свойства и т. д. Не всегда очевидно, что рассматривается в качестве кода. Например, имена пакетов NuGet должны считаться кодом. Если возникают сомнения, ознакомьтесь с рекомендациями по форматированию текста.

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

Чтобы включить элемент кода в текст статьи, поместите его между одинарными кавычками в виде обратного апострофа (`), чтобы указать стиль кода. Встроенный стиль кода не должен использовать формат тройных кавычек.

Markdown	Отображение
По умолчанию Entity Framework интерпретирует свойство с именем Id или ClassnameID как первичный ключ.	По умолчанию Entity Framework интерпретирует свойство с именем Id или ClassnameID как первичный ключ.

При локализации статьи (переводе на другие языки) текст, имеющий стиль кода, не переводится. Если вы хотите предотвратить локализацию без использования стиля кода, см. раздел Нелокализованные строки.

Полужирный стиль

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

Создание ссылок

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

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

The first reference to in this text is a link. Subsequent references to `System.CommandLine` can be in code style.

Первая ссылка на System.CommandLine в этом тексте — это гиперссылка. Последующие ссылки на System.CommandLine написаны в виде кода.

Заполнители

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

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

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

Имена заполнителей можно разделять дефисами (kebab-case), подчеркиванием или не разделяться вообще (Pascal case). Kebab-case может вызывать синтаксические ошибки, а знаки подчеркивания могут конфликтовать с подчеркиванием. Использование всех заглавных букв может вызвать конфликты с именованными константами во многих языках, хотя такой текст также может привлекать внимание к имени заполнителя.

Блоки кода

Синтаксис для включения кода в документ зависит от того, где находится код:

в файле Markdown статьи;
в файле кода в том же репозитории;
в файле кода в другом репозитории.

Ниже приведены рекомендации, которые применяются для всех трех типов блоков кода:

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

Снимки экрана

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

Вы можете копировать их.
Они индексируются поисковыми механизмами.
Они доступны для средств чтения с экрана.

Это лишь несколько из причин, по которым снимки экрана IDE не рекомендуются в качестве метода включения кода в статью. Используйте снимки экрана IDE для кода только в том случае, если вы показываете что-то о самой среде IDE, например IntelliSense. Не используйте снимки экрана, только чтобы показать цвета и выделение.

Проверка кода

В некоторых репозиториях реализованы процессы, которые автоматически компилируют все примеры кода для проверки на наличие ошибок. Это делается в репозитории .NET. Дополнительные сведения см. в разделе об участии в репозитории .NET.

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

Выделение

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

Пример отображения выделенного кода

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

Горизонтальные полосы прокрутки

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

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

Явное определение неправильного кода

В некоторых сценариях рекомендуется указывать шаблоны кода, которые следует избегать, например:

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

Для таких сценариев:

Укажите на ошибку как в комментариях к коду, так и в тексте статьи. Читатели часто пропускают текст статьи и ищут только код, поэтому важно объяснить ошибку не только в тексте статьи. Также недостаточно объяснить ошибку в комментариях к коду, так как комментарии к коду не локализованы.
Рассмотрите возможность комментирования кода, если предполагается ошибка компилятора. Закомментированный код не нарушит работу системы непрерывной интеграции (CI), если в репозитории со статьей он есть сейчас или будет реализован в будущем.

Пример того, как представлять нерекомендуемый код, см. в разделе Пример использования Rune: изменение регистра букв. В этом примере совет, как избежать ошибки, встроен в сам код, так как имя метода C# — ConvertToUpperBadExample .

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

Используйте встроенные блоки кода, только когда непрактично отображать код по ссылке на файл кода. Как правило, встроенный код сложнее тестировать и обновлять по сравнению с файлом кода, который является частью полного проекта. И встроенный код может опускать контекст, который может помочь разработчику понять и использовать код. Эти рекомендации относятся главным образом к языкам программирования. Встроенные блоки кода также могут использоваться для выходных и входных данных (например, JSON), языков запросов (таких как SQL) и языков сценариев (например, PowerShell).

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

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

 ```json < "aggregator": < "batchSize": 1000, "flushTimeout": "00:00:30" >> ```

GitHub Flavored Markdown поддерживает разделение блоков кода тильдами (~), а также обратными кавычками (`). Символ, используемый для открытия и закрытия блока кода, должен быть одинаковым в пределах одного блока кода.

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

Если вы используете слово языка или среды после тройных кавычек («`), которые не поддерживаются, такое слово отобразится в заголовке раздела кода на отображенной странице. По возможности используйте индикатор языка или среды во встроенных блоках кода.

При копировании и вставке кода из документа Word убедитесь, что в нем нет изогнутых кавычек, которые являются для кода недопустимыми. Если есть, замените их на обычные кавычки ( ‘ и » ). Кроме того, можно использовать функцию замены смарт-кавычек в пакете разработки Learn.

Ссылки на фрагмент кода в репозитории

Предпочтительный способ включения фрагментов кода для языков программирования в документы — использование ссылки на файл кода. Этот метод позволяет выделить строки кода и предоставить больше контекста для фрагмента кода, доступного в GitHub для разработчиков. Код можно включить с помощью формата с тройным двоеточием (. ) вручную или в Visual Studio Code с помощью пакета разработки Learn.

Находясь в Visual Studio Code, нажмите клавиши ALT+M или OPTION+M и выберите «Фрагмент кода».
Вам будет предложено выполнить поиск по всему содержимому, в какой-то области или по различным репозиториям. Для локального поиска выберите полный поиск.
Введите условие поиска и найдите нужный файл. Найдя файл, выберите его.
Затем выберите, какие строки кода нужно включить в фрагмент, используя следующие параметры: ИД, Диапазон или Никакие.
В зависимости от выбора на шаге 4 предоставьте необходимые значения.

Отображение всего файла кода:

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs".

Отображение части файла кода путем указания номера строк:

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26".

Отображение части файла кода путем указания имени фрагмента кода:

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" >В следующих разделах описаны эти примеры:

Использование относительного пути к файлу кода
Включение только выбранных номеров строк
Использование ссылки на фрагмент кода с именем
Выделение выбранных строк

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

Путь к файлу кода

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26".

Пример взят из репозитория документов ASP.NET, файла статьи aspnetcore/data/ef-mvc/crud.md. Для ссылки на файл кода используется относительный путь к aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs в том же репозитории.

Выбранные номера строк

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26".

В этом примере отображаются только строки 2–24 и 26 из файла кода StudentController.cs.

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

Именованный фрагмент кода

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" >Используйте для имени только буквы и символы подчеркивания.

В примере отображается раздел snippet_Create файла кода. Файл кода для этого примера содержит теги фрагментов в комментариях в коде C#:

// code excluded from the snippet // // code included in the snippet // // code excluded from the snippet

Именованные фрагменты кода могут быть вложенными, как показано в следующем примере:

// public static void SomeMethod() < // // Single line of code. // > //

При отображении фрагмента Method кода теги Line не включаются в отображаемые выходные данные.

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

Выделение выбранных строк

. code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26" highlight="2,5".

В примере выделены строки 2 и 5, если считать от начала отображаемого фрагмента кода. Подсчет выделяемых номеров строк не начинается от начала файла кода. Другими словами, выделяются строки 3 и 6 файла кода.

Ссылки на фрагменты кода в другом репозитории

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

Например, репозиторий документов — Azure/azure-docs, а репозиторий кода — Azure/azure-functions-durable-extension.

В корневой папке azure-docs добавьте следующий раздел в .openpublishing.publish.config.json:

Теперь при добавлении ссылки на sample-durable-functions, как если бы это была папка в azure-docs, вы на самом деле ссылаетесь на корневую папку в репозитории azure-functions-durable-extension.

Код можно включить с помощью формата с тройным двоеточием (. ) вручную или в Visual Studio Code с помощью пакета разработки Learn.

Находясь в Visual Studio Code, нажмите клавиши ALT+M или OPTION+M и выберите «Фрагмент кода».
Вам будет предложено выполнить поиск по всему содержимому, в какой-то области или по различным репозиториям. Выберите поиск по репозиториям.
Вам будет представлен набор репозиториев из .openpublishing.publish.config.json. Выберите репозиторий.
Введите условие поиска и найдите нужный файл. Найдя файл, выберите его.
Затем выберите, какие строки кода нужно включить в фрагмент, используя следующие параметры: ИД, Диапазон или Никакие.
В зависимости от выбора на шаге 5 предоставьте значение.

Ссылка на фрагмент кода будет выглядеть следующим образом:

. code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx" highlight="2,5".

В репозитории azure-functions-durable-extension этот файл кода находится в папке samples/csx/shared. Как отмечалось ранее, номера строк для выделения начинаются от начала фрагмента, а не от начала файла.

Имя, присвоенное зависимому репозиторию, относится к корню репозитория main, а тильда ( ~ ) ссылается на корень набора документов. Корень набора документов определяется в build_source_folder .openpublishing.publish.config.json . Путь к фрагменту кода в предыдущем примере работает в репозитории azure-docs, так как build_source_folder относится к корню репозитория ( . ). Если бы в качестве build_source_folder использовалось articles , путь начинался бы с ~/../samples-durable-functions , а не с ~/samples-durable-functions .

Фрагменты кода в записной книжке Jupyter

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

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

Добавление метаданных в записную книжку

Присвойте ячейке имя, добавив метаданные ячейки в записную книжку Jupyter.
- В Jupyter вы можете редактировать метаданные ячейки, сначала включив панель инструментов ячейки. Для этого выберите Просмотр > Панель инструментов ячейки > Редактировать метаданные.
- После включения панели инструментов ячейки выберите Изменить метаданные в ячейке, которой нужно присвоить имя.
- Кроме того, можно изменить метаданные непосредственно в структуре JSON записной книжки.
В метаданных ячейки добавьте атрибут «name»:

"metadata": ">,

"metadata": ,

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

 "metadata": < "name": "workspace", "msdoc": "how-to-track-experiments.md" >,

Настройка доступа к репозиторию

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

Справочник по синтаксису фрагмента кода записной книжки Jupyter

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

[!notebook-[] (/?name=)]

[!notebook-python[] (~/MachineLearningNotebooks/train-on-local.ipynb?name=workspace)]

Этот синтаксис является блоком расширения Markdown. Он должен использоваться в отдельной строке.

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

Интерактивные фрагменты кода

Встроенные блоки интерактивного кода

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

Azure Cloud Shell
Azure PowerShell Cloud Shell
C# REPL

Если включен интерактивный режим, в отображаемых полях с кодом будут кнопки Попробовать или Запустить. Например:

 ```azurepowershell-interactive New-AzResourceGroup -Name myResourceGroup -Location westeurope ```

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

New-AzResourceGroup -Name myResourceGroup -Location westeurope

 ```csharp-interactive var aFriend = "Maria"; Console.WriteLine($"Hello "); ```

 var aFriend = "Maria"; Console.WriteLine($"Hello ");

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

azurepowershell-interactive — активирует Cloud Shell в Azure PowerShell, как в предыдущем примере.
azurecli-interactive — включает Azure Cloud Shell
csharp-interactive — включает C# REPL

В Azure Cloud Shell и PowerShell Cloud Shell пользователи могут выполнять команды только с собственной учетной записью Azure.

Фрагменты кода, включаемые по ссылке

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

cloudshell-powershell — активирует Cloud Shell в Azure PowerShell, как в предыдущем примере.
cloudshell-bash — включает Azure Cloud Shell
try-dotnet — активирует Try .NET.
try-dotnet-class — активирует Try .NET с формированием шаблонов классов.
try-dotnet-method — активирует Try .NET с формированием шаблонов методов.

Ниже приведены некоторые примеры:

. code source="PowerShell.ps1" interactive="cloudshell-powershell".

. code source="Bash.sh" interactive="cloudshell-bash".

В Azure Cloud Shell и PowerShell Cloud Shell пользователи могут выполнять команды только с собственной учетной записью Azure.

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

Без формирования шаблонов ( try-dotnet ). Блок кода должен представлять полный текст программы. Например, допустимым будет файл Program.cs, созданный dotnet new console . Это удобно для демонстрации программы небольшого размера целиком, включая все необходимые директивы using . Операторы верхнего уровня сейчас не поддерживаются.
Формирование шаблонов методов ( try-dotnet-method ). Блок кода должен представлять содержимое метода Main в консольном приложении. Вы можете учитывать директивы using , добавленные шаблоном dotnet new console . Этот вариант удобен для коротких фрагментов кода, которые демонстрируют использование одной функции.
Формирование шаблонов классов ( try-dotnet-class ). Блок кода должен представлять класс с методом Main , который выполняет для программы роль точки входа. Этот вариант можно использовать для демонстрации взаимодействия между элементами класса.

Синтаксис ссылок на фрагменты

. code language="" source="" ="".

Этот синтаксис является блоком расширения Markdown. Он должен использоваться в отдельной строке.

(необязательно)

Язык фрагмента кода. Дополнительные сведения см. в разделе Поддерживаемые языки далее в этой статье.

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

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

range : 1,3-5 Диапазон строк. Этот пример содержит строки 1, 3, 4 и 5.
id : Create Идентификатор фрагмента, который нужно вставить из файла кода. Это значение не может существовать одновременно с диапазоном.
highlight : 2-4,6 Диапазон и (или) номера строк, которые должны выделяться в создаваемом фрагменте кода. Нумерация задается относительно отображаемых строк (в соответствии с диапазоном или идентификатором), а не файла.
interactive : cloudshell-powershell , cloudshell-bash , try-dotnet , try-dotnet-class , try-dotnet-method Строковое значение, определяющее тип используемой интерактивности.
Сведения о представлении имени тега в исходных файлах фрагмента кода для каждого языка см. в разделе с рекомендациями по DocFX.

Поддерживаемые языки

Пакет разработки Learn включает функцию для завершения инструкций и проверки доступных идентификаторов языка для блоков ограждения кода.

Огороженные блоки кода

Имя	Допустимые псевдонимы
.NET Core CLI	dotnetcli
1C	1c
ABNF	abnf
Журналы доступа	accesslog
Ada	ada
Ассемблер ARM	armasm , arm
Ассемблер AVR	avrasm
ActionScript	actionscript , as
Алан	alan , i
AngelScript	angelscript , asc
ANTLR	antlr
Apache	apache , apacheconf
AppleScript	applescript , osascript
Аркады	arcade
AsciiDoc	asciidoc , adoc
AspectJ	aspectj
ASPX	aspx
ASP.NET (C#)	aspx-csharp
ASP.NET (VB)	aspx-vb
AutoHotkey	autohotkey
AutoIt	autoit
Awk	awk , mawk , nawk , gawk
Axapta	axapta
AzCopy	azcopy
Azure CLI	azurecli
Azure CLI (интерактивный)	azurecli-interactive
Azure PowerShell	azurepowershell
Azure Powershell (интерактивный)	azurepowershell-interactive
Bash	bash , sh , zsh
Basic	basic
форма Бэкуса-Наура (BNF)	bnf
C	c
C#	csharp , cs
C# (интерактивный)	csharp-interactive
C++	cpp , c , cc , h , c++ , h++ , hpp
C++/CX	cppcx
C++/WinRT	cppwinrt
C/AL	cal
Cache Object Script	cos , cls
CMake	cmake , cmake.in
Coq	coq
Поставщик служб шифрования	csp
CSS	css
Cap’n Proto	capnproto , capnp
Clojure	clojure , clj
CoffeeScript	coffeescript , coffee , cson , iced
Crmsh	crmsh , crm , pcmk
Crystal	crystal , cr
Cypher (Neo4j)	cypher
D	d
DAX Power BI	dax
Файл зоны DNS	dns , zone , bind
DOS	dos , bat , cmd
Dart	dart
Delphi	delphi , dpr , dfm , pas , pascal , freepascal , lazarus , lpr , lfm
Поиск различий	diff , patch
Django	django , jinja
Dockerfile	dockerfile , docker
dsconfig	dsconfig
DTS (дерево устройств)	dts
Dust	dust , dst
Dylan	dylan
EBNF	ebnf
Elixir	elixir
Elm	elm
Erlang	erlang , erl
Excel	excel , xls , xlsx
Extempore	extempore , xtlang , xtm
F#	fsharp , fs
FIX	fix
Fortran	fortran , f90 , f95
G-Code	gcode , nc
Gams	gams , gms
GAUSS	gauss , gss
GDScript	godot , gdscript
Gherkin	gherkin
GN for Ninja	gn , gni
Go	go , golang
Golo	golo , gololang
Gradle	gradle
GraphQL	graphql
Groovy	groovy
HTML	html , xhtml
HTTP	http , https
Haml	haml
Рули	handlebars , hbs , html.hbs , html.handlebars
Haskell	haskell , hs
Haxe	haxe , hx
Hy	hy , hylang
Ini	ini
Inform7	inform7 , i7
IRPF90	irpf90
JSON	json
Java	java , jsp
JavaScript	javascript , js , jsx
Kotlin	kotlin , kt
Kusto	kusto
Leaf	leaf
Lasso	lasso , ls , lassoscript
Меньше	less
LDIF	ldif
Lisp	lisp
LiveCode Server	livecodeserver
LiveScript	livescript , ls
Lua	lua
Makefile	makefile , mk , mak
Markdown	markdown , md , mkdown , mkd
Mathematica	mathematica , mma , wl
Matlab	matlab
Maxima	maxima
Maya Embedded Language	mel
Mercury	mercury
Язык сценариев mIRC	mirc , mrc
Mizar	mizar
MOF	mof
Mojolicious	mojolicious
Monkey	monkey
Moonscript	moonscript , moon
MS Graph (интерактивный)	msgraph-interactive
N1QL	n1ql
NSIS	nsis
Nginx	nginx , nginxconf
Nimrod	nimrod , nim
Nix	nix
OCaml	ocaml , ml
Objective C	objectivec , mm , objc , obj-c
OpenGL Shading Language	glsl
OpenSCAD	openscad , scad
Язык правил Oracle	ruleslanguage
Oxygene	oxygene
PF	pf , pf.conf
PHP	php , php3 , php4 , php5 , php6
Parser3	parser3
Perl	perl , pl , pm
Обычный текст без выделения	plaintext
Pony	pony
PostgreSQL и PL/pgSQL	pgsql , postgres , postgresql
PowerShell	powershell , ps
PowerShell (интерактивный)	powershell-interactive
Обработка	processing
Prolog	prolog
Свойства	properties
Protocol Buffers	protobuf
Puppet	puppet , pp
Python	python , py , gyp
Результаты профилировщика Python	profile
Q#	qsharp
Q	k , kdb
QML	qml
R	r
Razor CSHTML	cshtml , razor , razor-cshtml
ReasonML	reasonml , re
RenderMan RIB	rib
RenderMan RSL	rsl
Roboconf	graph , instances
Robot Framework	robot , rf
Файлы спецификаций RPM	rpm-specfile , rpm , spec , rpm-spec , specfile
Ruby	ruby , rb , gemspec , podspec , thor , irb
Rust	rust , rs
SAS	SAS , sas
SCSS	scss
SQL	sql
STEP Part 21	p21 , step , stp
Scala	scala
Схема	scheme
Scilab	scilab , sci
Выражения фигуры	shexc
Оболочка	shell , console
Smali	smali
Smalltalk	smalltalk , st
Solidity	solidity , sol
Stan	stan
Stata	stata
Структурированный текст	iecst , scl , stl , structured-text
Стилус	stylus , styl
SubUnit	subunit
Supercollider	supercollider , sc
Swift	swift
Tcl	tcl , tk
Terraform (HCL)	terraform , tf , hcl
Test Anything Protocol	tap
TeX	tex
Thrift	thrift
TOML	toml
TP	tp
Twig	twig , craftcms
TypeScript	typescript , ts
VB.NET	vbnet , vb
VBScript	vbscript , vbs
VHDL	vhdl
Vala	vala
Verilog	verilog , v
Скрипт Vim	vim
Visual Basic	vb
Visual Basic для приложений	vba
X++	xpp
Сборка x86	x86asm
XL	xl , tao
XQuery	xquery , xpath , xq
XAML	xaml
XML	xml , xhtml , rss , atom , xjb , xsd , xsl , plist
YAML	yml , yaml
Zephir	zephir , zep

Функция завершения Dev Lang пакета разработки Learn использует первый допустимый псевдоним при наличии нескольких псевдонимов.

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

Сведения о форматировании текста для типов содержимого, отличных от кода, см. в разделе Рекомендации по форматированию текста.

Справочные материалы по Markdown

В этой статье приведен алфавитный справочник по написанию Markdown для Microsoft Learn.

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

Вы можете использовать любой текстовый редактор для записи Markdown, но мы рекомендуем Visual Studio Code с пакетом разработки Learn. Пакет разработки Learn предоставляет средства редактирования и функции предварительного просмотра, которые позволяют видеть, как будут выглядеть ваши статьи при отображении в Microsoft Learn.

Оповещения («Примечание», «Совет», «Важно!», «Внимание!», «Предупреждение»)

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

Избегайте использования блоков «Примечание», «Совет», «Важно!». Читатели часто их пропускают. Рекомендуется размещать их сведения непосредственно в тексте статьи.

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

Поддерживаются следующие типы оповещений:

> [!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 считает их HTML-тегами.

Например, следует закодировать как <script name> или \ .

Угловые скобки не обязательно должны быть экранированы в тексте, отформатированном как встроенный код, или в блоках кода.

Апострофы и кавычки

Если вы копируете текст из Word в редактор Markdown, он может содержать книжные (изогнутые) апострофы или кавычки. Их нужно заменить кодом или обычными апострофами или кавычками. В противном случае после публикации файла может отобразиться нечитаемый текст, например Itâ€™s.

Ниже приведены кодировки для этих знаков пунктуации:

левая (открывающая) кавычка: “ ;
правая (закрывающая) кавычка: ” ;
правая закрывающая одинарная кавычка или апостроф: ’ ;
левая открывающая одинарная кавычка (используется редко): ‘ .

Чтобы избежать «умных» символов в файлах Markdown, используйте функцию замены смарт-кавычек пакета разработки Learn. Дополнительные сведения см. в статье Замена смарт-кавычек.

Блок цитирования

Блоки цитирования создаются с помощью символа > :

> This is a blockquote. It is usually rendered indented and with a different background color.

Предыдущий пример отображается следующим образом:

Это блок цитирования. Обычно он отображается с отступом и имеет другой цвет фона.

Полужирное и курсивное начертания

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

This text is **bold**.

Чтобы задать для текста курсивное начертание, заключите его в одинарные звездочки:

This text is *italic*.

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

This text is both ***bold and italic***.

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

Фрагменты кода

Learn Markdown поддерживает размещение фрагментов кода, как встроенных в предложении, так и в виде отдельного «огражденного» блока между предложениями. Дополнительные сведения см. в разделе Как добавить код в документацию.

Столбцы

Расширение Markdown для столбцов дает авторам возможность добавлять макеты содержимого на основе столбцов, которые являются более гибкими и мощными, чем базовые таблицы Markdown, которые подходят только для истинных табличных данных. Можно добавить до четырех столбцов и использовать необязательный атрибут span для объединения двух или более столбцов.

Хотя расширение columns все еще работает, мы больше не рекомендуем использовать его для создания пользовательских макетов. Мы обнаружили, что многие пользовательские макеты столбцов имеют проблемы со специальными возможностями или иным образом нарушают рекомендации по стилю. Не создавайте пользовательские макеты. Используйте стандартные функции Microsoft Learn.

Используйте следующий синтаксис для столбцов:

. row. . column span="". Content. . column-end. . column span="". More content. . column-end. . row-end.

Столбцы должны содержать только базовый Markdown, включая изображения. Заголовки, таблицы, вкладки и другие сложные структуры не должны включаться. Строка не может иметь содержимое вне столбца.

Например, следующий Markdown создает один столбец, охватывающий две ширины столбца, и один стандартный столбец (без span ):

. row. . column span="2". **This is a 2-span column with lots of text.** Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vestibulum mollis nunc ornare commodo. Nullam ac metus imperdiet, rutrum justo vel, vulputate leo. Donec rutrum non eros eget consectetur. . column-end. . column span="". **This is a single-span column with an image in it.** ![Doc.U.Ment](media/markdown-reference/document.png) . column-end. . row-end.

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

Это столбец двойной ширины с большим объемом текста.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vestibulum mollis nunc ornare commodo. Nullam ac metus imperdiet, rutrum justo vel, vulputate leo. Donec rutrum non eros eget consectetur.

Это столбец одинарной ширины с изображением.

Doc.U.Ment

Не включайте конфиденциальные или конфиденциальные сведения в комментарии HTML. Microsoft Learn переносит комментарии HTML в опубликованный HTML-код, который становится общедоступным. Хотя комментарии HTML невидимы для читателя, они отображаются в самом HTML-коде.

Заголовки

Microsoft Learn поддерживает шесть уровней заголовков Markdown:

# This is a first level heading (H1) ## This is a second level heading (H2) . ###### This is a sixth level heading (H6)

Между последним символом # и содержимым заголовка должен присутствовать пробел.
В одном файле Markdown должен быть один и только один заголовок H1.
Заголовок H1 указывается в файле в первую очередь, сразу после блока метаданных YML.
Заголовки H2 автоматически отображаются в правом меню навигации опубликованного файла. Заголовки более низкого уровня не отображаются, поэтому для удобства перехода по содержимому рекомендуется использовать заголовки H2.
Использовать заголовки HTML, такие как , не рекомендуется, и в некоторых случаях из-за них могут возникать предупреждения при сборке.
Привязка к отдельным заголовкам в файле выполняется с помощью ссылок на закладки.

HTML

Хотя Markdown поддерживает встроенный HTML,HTML не рекомендуется для публикации в Microsoft Learn, и, за исключением ограниченного списка значений, это приведет к ошибкам сборки или предупреждениям.

Изображения

Для изображений по умолчанию поддерживаются следующие типы файлов:

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

"resource": [ < "files" : [ "**/*.png", "**/*.jpg, "**/*.gif" ],

Стандартные схематические изображения (Markdown по умолчанию)

Базовый синтаксис Markdown для внедрения изображения:

![]() Example: ![alt text for image](../images/Introduction.png)

Где — краткое описание изображения, а — относительный путь к нему. Заменяющий текст необходим для средств чтения с экрана для слабовидящих. Он также удобен при возникновении ошибок на сайте, из-за которых не удается воспроизвести изображение.

Знаки подчеркивания в замещающем тексте не отображаются должным образом, если они не экранированы с помощью префикса — обратной косой черты ( \_ ). Но не стоит копировать имена файлов для использования в качестве замещающего текста. Например, вместо:

![ADextension_2FA_Configure_Step4](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

![Active Directory extension for two-factor authentication, step 4: Configure](./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)

Стандартные концептуальные изображения (Learn Markdown)

Пользовательское . image. расширение в Microsoft Learn поддерживает стандартные образы, сложные образы и значки.

Для стандартных изображений старый синтаксис Markdown по-прежнему будет работать, но рекомендуется использовать новое расширение, так как оно поддерживает более широкие функциональные возможности, такие как указание области локализации, отличной от родительской темы. В будущем будут доступны другие расширенные функции, такие как выбор из общей коллекции изображений вместо указания локального изображения. Используйте следующий новый синтаксис:

. image type="content" source="" alt-text="".

Если type="content" (по умолчанию), требуются source и alt-text .

Сложные изображения с длинными описаниями

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

. image type="complex" source="" alt-text="". . image-end.

Если type="complex" , source , alt-text , требуется длинное описание и тег . image-end. .

Когда ваши изменения доступны в предварительной версии или опубликованы, вы можете проверить, существует ли длинное описание, щелкнув изображение правой кнопкой мыши и выбрав Проверить (при использовании браузера Microsoft Edge, хотя другие браузеры имеют аналогичные функции). Это действие приведет вас к источнику изображения в HTML-коде, под которым вы найдете визуально скрытый класс. Разверните раскрывающийся список этого класса, и вы увидите его длинное описание:

Снимок экрана: код HTML для изображения и его длинное описание.

Автоматические границы

Расширение . image. также поддерживает свойство border , которое автоматически добавляет серую рамку размером 1 пиксель, окружающую ваше изображение. По умолчанию это свойство border имеет значение true для изображений content и complex , поэтому граница будет применена автоматически, если вы явно не добавите свойство со значением false . По умолчанию свойство border имеет значение false для изображений icon .

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

Указание области локализации

Иногда область локализации для изображения отличается от области локализации для статьи или модуля, в которых оно содержится. Это может привести к неправильному глобальному интерфейсу: например, если снимок экрана продукта случайно локализован на язык, на котором продукт недоступен. Чтобы предотвратить это, вы можете указать необязательный атрибут loc-scope в изображениях типов content и complex . Это требуется для снимков экрана, на которых показан продукт с другой областью локализации, чем соответствующие статья или модуль.

Значки

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

. image type="icon" source="".

Если задано значение type="icon" , нужно указать source , но не alt-text .

По умолчанию свойство border имеет значение false для значков. Если для декоративного изображения требуется стандартная граница изображения, явно добавьте border="true" к тегу . image. .

Включаемые файлы Markdown

Если файлы Markdown необходимо повторить в нескольких статьях, можно использовать включаемый файл. Функция включения предписывает Microsoft Learn заменить ссылку на содержимое включаемого файла во время сборки. Для включения можно использовать следующие способы.

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

Встроенные и блочные включаемые файлы — это файлы Markdown с расширением MD. Они могут содержать любую допустимую разметку Markdown. Включаемые файлы обычно находятся в общем подкаталоге includes в корне репозитория. Когда статья публикуется, включаемый файл легко интегрируется в нее.

Синтаксис включаемых файлов

Блочные включаемые файлы находятся в отдельной строке:

[!INCLUDE []()]

Встроенные включаемые файлы находятся в строке:

Text before [!INCLUDE []()] and after.

Где — имя файла, а — относительный путь к файлу. Слово INCLUDE должно быть написано прописными буквами, а перед должен быть пробел.

Ниже приведены требования к включаемым файлам и соображения по работе с ними:

Блочные включаемые файлы предназначены для значительных объемов текста: один или два абзаца, общая процедура или общий раздел. Не используйте их для фрагментов текста меньше одного предложения.
Включаемые элементы не будут отображаться в представлении вашей статьи, отображаемом на GitHub, так как они используют расширения Microsoft Learn. Они отображаются только после публикации.
Весь текст во включаемом файле должен состоять из полноценных предложений или фраз, не зависящих от остального текста статьи, в которую добавляется ссылка на такой файл. Если не следовать этой инструкции, в статье создаются непереводимые строки.
Не внедряйте одни включаемые файлы в другие.
Папки /Includes исключаются из сборки. Таким образом, изображения, хранящиеся в папках /includes и на которые есть ссылки во включаемых файлах, не будут отображаться в опубликованном содержимом. Храните изображения в папке /media за пределами папки /includes .
Как и в обычных статьях, не используйте общий файл мультимедиа для включаемых файлов. Для каждого включаемого файла в статье должен быть создан отдельный файл мультимедиа с уникальным именем. Файл мультимедиа должен храниться в папке мультимедиа, связанной с включаемым файлом.
Не используйте включаемый файл как единственное содержимое статьи. Включаемые файлы предназначены для дополнения основных материалов статьи.

Indentation;

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

Чтобы задать отступ текста для выравнивания с предыдущим абзацем или элементом в нумерованном или маркированном списке, следует использовать пробелы.

В следующих двух примерах показана отрисовка абзацев с отступами на основе их связи с другими абзацами.

1. This is a numbered list example (one space after the period before the letter T). This sentence is indented three spaces. This code block is indented three spaces. - This is a bulleted list example (one space after the bullet before the letter T). This sentence is indented two spaces. > [!TIP] > This tip is indented two spaces. - This is a second-level bullet (indented two spaces, with one space after the bullet before the letter T). This sentence is indented four spaces. > This quote block is indented four spaces.

Приведенный выше пример отображается следующим образом:

This code block is indented three spaces.

Это пример маркированного списка (один пробел после маркера перед первой буквой). Это предложение имеет отступ в два пробела.

Совет Этот совет имеет отступ в два пробела.

Это маркер второго уровня (с отступом в два пробела, с одним пробелом после маркера перед первой буквой). Это предложение имеет отступ в четыре пробела.

Этот блок цитаты имеет отступ в четыре пробела.

Ссылки

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

Списки (нумерованные, маркированные, контрольные)

Нумерованный список

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

Не используйте в списках, включая вложенные списки, буквы. Они неправильно отображаются при публикации в Microsoft Learn. Вложенные списки с цифрами преобразуются в списки со строчными буквами при публикации. Например:

1. This is 1. a parent numbered list 1. and this is 1. a nested numbered list 1. (fin)

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

Это

родительский нумерованный список,

а это
вложенный нумерованный список

Маркированный список

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

- This is - a parent bulleted list - and this is - a nested bulleted list - All done!

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

Это

родительский маркированный список,

а это
вложенный маркированный список

Независимо от используемого синтаксиса, - или * , используйте его согласованно в статье.

Контрольный список

Контрольные списки доступны для использования в Microsoft Learn через пользовательское расширение Markdown:

> [!div * List item 1 > * List item 2 > * List item 3

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

List item 1
List item 2
List item 3

Контрольные списки используются в начале или конце статьи для подведения итогов "Чему вы научитесь" или "Чему вы научились". Не вставляйте контрольные списки в статьи по случайному принципу.

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

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

Синтаксис выглядит следующим образом:

> [!div [button text](link to topic)

> [!div [Learn about adding code to articles](code-in-docs.md)

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

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

Нелокализованные строки

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

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

Чтобы пометить отдельную строку как не подлежащую локализации, используйте следующий синтаксис:

. no-loc text="String".

Например, в следующем примере только один экземпляр Document будет игнорироваться в процессе локализации:

# Heading 1 of the Document Markdown content within the . no-loc text="Document". The are multiple instances of Document, document, and documents.

Используйте \ , чтобы экранировать специальные символы:

Lorem . no-loc text="Find a \"Quotation\"". Ipsum.

Можно также использовать метаданные в заголовке YAML, чтобы пометить все экземпляры строки в текущем файле Markdown как нелокализуемые:

author: cillroy no-loc: [Global, Strings, to be, Ignored]

Метаданные no-loc не поддерживаются в качестве глобальных метаданных в файле docfx.json. Конвейер локализации не считывает файл docfx.json, поэтому метаданные no-loc должны быть добавлены в каждый отдельный исходный файл.

В следующем примере и в метаданных title , и в заголовке Markdown слово Document будет игнорироваться в процессе локализации.

В метаданных description и основном содержимом Markdown слово document локализовано, так как оно не начинается с прописной буквы D .

--- title: Title of the Document author: author-name description: Description for the document no-loc: [Title, Document] --- # Heading 1 of the Document Markdown content within the document.

[!div data-resources="OutlookServices.Calendar"] > ```cs > > ``` > ```javascript > > ``` ```` The preceding blockquote Markdown text will be rendered as: > [!div data-resources="OutlookServices.Calendar"] > ```cs > > ``` > ```javascript > > ``` -->

Селекторы

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

В каждой статье с возможностью выбора используется одна и та же разметка Markdown для селектора. Поэтому рекомендуется поместить селектор для статьи во включаемый файл. Затем нужно добавить ссылки на этот файл во все статьи, для которых используется селектор.

Сейчас существует два типа селекторов: для единичного и множественного выбора.

Единичный выбор

> [!div - [Universal Windows](../articles/notification-hubs-windows-store-dotnet-get-started/) > - [Windows Phone](../articles/notification-hubs-windows-phone-get-started/) > - [iOS](../articles/notification-hubs-ios-get-started/) > - [Android](../articles/notification-hubs-android-get-started/) > - [Kindle](../articles/notification-hubs-kindle-get-started/) > - [Baidu](../articles/notification-hubs-baidu-get-started/) > - [Xamarin.iOS](../articles/partner-xamarin-notification-hubs-ios-get-started/) > - [Xamarin.Android](../articles/partner-xamarin-notification-hubs-android-get-started/)

. будет иметь следующий вид:

Множественный выбор

> [!div title1="Platform" title2="Backend"] > - [(iOS | .NET)](./mobile-services-dotnet-backend-ios-get-started-push.md) > - [(iOS | JavaScript)](./mobile-services-javascript-backend-ios-get-started-push.md) > - [(Windows universal C# | .NET)](./mobile-services-dotnet-backend-windows-universal-dotnet-get-started-push.md) > - [(Windows universal C# | Javascript)](./mobile-services-javascript-backend-windows-universal-dotnet-get-started-push.md) > - [(Windows Phone | .NET)](./mobile-services-dotnet-backend-windows-phone-get-started-push.md) > - [(Windows Phone | Javascript)](./mobile-services-javascript-backend-windows-phone-get-started-push.md) > - [(Android | .NET)](./mobile-services-dotnet-backend-android-get-started-push.md) > - [(Android | Javascript)](./mobile-services-javascript-backend-android-get-started-push.md) > - [(Xamarin iOS | Javascript)](./partner-xamarin-mobile-services-ios-get-started-push.md) > - [(Xamarin Android | Javascript)](./partner-xamarin-mobile-services-android-get-started-push.md)

. будет иметь следующий вид:

(iOS | .NET)
(iOS | JavaScript)
(Универсальные приложения Windows на C# | .NET)
(Универсальные приложения Windows на C# | Javascript)
(Windows Phone | .NET)
(Windows Phone | Javascript)
(Android | .NET)
(Android | Javascript)
(Xamarin iOS | Javascript)
(Xamarin Android | Javascript)

Подстрочные и надстрочные символы

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

Для подстрочных и надстрочных символов используйте HTML:

Hello _{This is subscript!}

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

Здравствуйте, _{это подстрочный текст!}

Goodbye ^{This is superscript!}

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

До свидания, это надстрочный текст!

Таблицы

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

|This is |a simple |table header| |----------|-----------|------------| |table |data |here | |it doesn't|actually |have to line up nicely!|

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

Это	просто	заголовок таблицы
table	.	здесь
вообще-то	не всегда	отображаются аккуратно!

Можно выровнять столбцы с помощью двоеточий:

| Fun | With | Tables | | :------------------- | -------------------: |:---------------:| | left-aligned column | right-aligned column | centered column | | $100 | $100 | $100 | | $10 | $10 | $10 | | $1 | $1 | $1 |

Отображается следующим образом:

Fun	With	Таблицы
left-aligned column	right-aligned column	centered column
$100	$100	$100
10 долл. США	10 долл. США	10 долл. США
$1	$1	$1

Расширение Разработки Learn для VS Code упрощает добавление базовых таблиц Markdown.

Разрывы строк внутри слов в любой ячейке таблицы

Длинные слова в таблице Markdown могут привести к тому, что таблица сдвинется вправо и станет нечитаемой. Это можно решить, разрешив отрисовке автоматически вставлять разрывы строк в словах при необходимости. Нужно просто заключить таблицу в настраиваемый класс [!div >.

Далее приведен пример Markdown таблицы с тремя строками, которая будет заключена с помощью div с классом mx-tdBreakAll .

> [!div |Name|Syntax|Mandatory for silent installation?|Description| > |-------------|----------|---------|---------| > |Quiet|/quiet|Yes|Runs the installer, displaying no UI and no prompts.| > |NoRestart|/norestart|No|Suppresses any attempts to restart. By default, the UI will prompt before restart.| > |Help|/help|No|Provides help and quick reference. Displays the correct use of the setup command, including a list of all options and behaviors.|

Она будет иметь следующий вид:

Имя	Синтаксис	Обязательно для автоматической установки?	Описание:
Quiet	/quiet	Да	Запускает установщик без отображения пользовательского интерфейса и запросов.
NoRestart	/norestart	Нет	Предотвращает все попытки перезапуска. По умолчанию в пользовательском интерфейсе будет отображаться запрос перед перезапуском.
Справка	/help	Нет	Предоставляет справку и краткий справочник. Отображает правильное использование команды setup, включая список всех параметров и вариантов поведения.

Разрывы строк внутри слов в ячейках второго столбца

Разрывы строк могут вставляться автоматически внутри слов только во втором столбце таблицы. Чтобы разрешить разрывы только во втором столбце, примените класс mx-tdCol2BreakAll с помощью синтаксиса переноса div , как показано выше.

Несогласованные значения ширины столбцов между таблицами

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

Чередование HTML-кода с Markdown делает темы более сложными и может озадачивать участников сообщества.
Таблица, которая хорошо выглядит для определенного размера экрана, может в конечном итоге выглядеть нечитаемой при разных размерах экрана, так как это противоречит принципам адаптивной визуализации.

Таблицы матриц данных

Таблица матрицы данных содержит заголовок и взвешенный первый столбец. Она позволяет создать матрицу с пустой ячейкой в верхнем углу слева. Microsoft Learn имеет пользовательский Markdown для таблиц матрицы данных:

| |Header 1 |Header 2| |------------------|---------|--------| |**First column A**|Cell 1A |Cell 2A | |**First column B**|Cell 1B |Cell 2B |

Пример отображается следующим образом:

Заголовок 1	Заголовок 2
Первый столбец A	Ячейка 1A	Ячейка 2A
Первый столбец B	Ячейка 1B	Ячейка 2B

Каждая запись в первом столбце должна быть выделена полужирным шрифтом ( **bold** ); в противном случае таблицы не будут доступны для средств чтения с экрана или допустимы для Microsoft Learn.

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

Таблицы HTML

Таблицы HTML не рекомендуются для Microsoft Learn. Они трудны для восприятия в исходном виде — это нарушает основной принцип Markdown.

fomvasss / Шпаргалка по Markdown.md

Поиграть с разметкой Markdown можно на демо-странице.

# H1 ## H2 ### H3 #### H4 ##### H5 ###### H6 Кроме того, H1 и H2 можно обозначить подчеркиванием: Alt-H1 ====== Alt-H2 ------

Кроме того, заголовки H1 и H2 можно обозначить подчеркиванием:

Курсив обозначается *звездочками* или _подчеркиванием_. Полужирный шрифт - двойными **звездочками** или __подчеркиванием__. Комбинированное выделение **звездочками и _подчеркиванием_**. Для зачеркнутого текста используются две тильды . ~~Уберите это.~~

Курсив обозначается звездочками или подчеркиванием.

Полужирный шрифт - двойными звездочками или подчеркиванием.

Комбинированное выделение звездочками и подчеркиванием.

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

(В данном примере предшествующие и завершающие пробелы обозначены точками: ⋅)

1. Первый пункт нумерованного списка 2. Второй пункт ⋅⋅*Ненумерованный вложенный список. 1. Сами числа не имеют значения, лишь бы это были цифры ⋅⋅1. Нумерованный вложенный список 4. И еще один пункт. ⋅⋅⋅Внутри пунктов списка можно вставить абзацы с таким же отступом. Обратите внимание на пустую строку выше и на пробелы в начале (нужен по меньшей мере один, но здесь мы добавили три, чтобы также выровнять необработанный Markdown). ⋅⋅⋅Чтобы вставить разрыв строки, но не начинать новый параграф, нужно добавить два пробела перед новой строкой.⋅⋅ ⋅⋅⋅Этот текст начинается с новой строки, но находится в том же абзаце.⋅⋅ ⋅⋅⋅(В некоторых обработчиках, например на Github, пробелы в начале новой строки не нужны.) * Ненумерованный список можно размечать звездочками - Или минусами + Или плюсами

Первый пункт нумерованного списка
Второй пункт

Ненумерованный вложенный список.

Сами числа не имеют значения, лишь бы это были цифры
Нумерованный вложенный список
И еще один пункт. Внутри пунктов списка можно вставить абзацы с таким же отступом. Обратите внимание на пустую строку выше и на пробелы в начале (нужен по меньшей мере один, но здесь мы добавили три, чтобы также выровнять необработанный Markdown). Чтобы вставить разрыв строки, но не начинать новый параграф, нужно добавить два пробела перед новой строкой. Эта текст начинается с новой строки, но находится в том же абзаце. (В некоторых обработчиках, например на Github, пробелы в начале новой строки не нужны.)

Ненумерованный список можно размечать звездочками

Или минусами

Или плюсами

Ссылки можно оформить разными способами.

[Обычная ссылка в строке](https://www.google.com) [Обычная ссылка с title](https://www.google.com "Сайт Google") [Ссылка со сноской][Произвольный регистронезависимый текст] [Относительная ссылка на документ](../blob/master/LICENSE) [Для ссылок со сноской можно использовать цифры][1] Или можно просто вставить ссылку в квадратные скобки [текст ссылки] Произвольный текст, после которого можно привести ссылки. [произвольный регистронезависимый текст]: https://www.mozilla.org [1]: http://slashdot.org [текст ссылки]: http://www.reddit.com

Или можно просто вставить ссылку в квадратные скобки текст ссылки

Произвольный текст, после которого можно привести ссылки.

(*) Для символов не входящих в ASCII, например кириллицы, текст сноски все-таки регистрозависим (прим. перев.)

Вот наш логотип (наведите указатель, чтобы увидеть текст заголовка): Внутри строки: ![alt-текст](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Текст заголовка логотипа 1") В сноске: ![alt-текст][logo] [logo]: https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Текст заголовка логотипа 2"

Вот наш логотип (наведите указатель, чтобы увидеть текст заголовка):

alt-текст

Внутри строки:

alt-текст

В сноске:

Код и подсветка синтаксиса

Блоки кода являются частью функций Markdown, но не подсветка синтаксиса. Однако многие обработчики, например Github или Markdown Here, поддерживают подсветку синтаксиса. Список поддерживаемых языков и способ их указания может различаться. Markdown Here поддерживает десятки языков (и не-языков, например синтаксис diff и заголовки HTTP); полный список и способ указания языков см. на странице highlight.js demo-странице.

`Код` в строке обрамляется `обратными апострофами`.

Код в строке обрамляется обратными апострофами .

Блоки кода выделяются либо тремя обратными апострофами ``` либо четырьмя пробелами в каждой строке. Рекомендуется использовать три апострофа -- они проще и только они поддерживают подсветку синтаксиса.

```javascript var s = "Подсветка JavaScript"; alert(s); ``` ```python s = "Подсветка Python" print s ``` ``` Язык не указан, синтаксис не подсвечен. Но мы вставим в него тег. ```

var s = "Подсветка JavaScript"; alert(s);

s = "Подсветка Python" print s

Язык не указан, синтаксис не подсвечен (некоторые обработчики все же подсвечивают). Но мы вставим в него тег.

Таблицы не являются частью Markdown, но многие обработчики, например Markdown Here и Github, поддерживают их. Они позволяют легко добавить таблицы в электронное письмо -- в других случаях для этого нужно копировать их из другого приложения.

Вертикальные линии обозначают столбцы. | Таблицы | Это | Круто | | ------------- |:------------------:| -----:| | столбец 3 | выровнен вправо | $1600 | | столбец 2 | выровнен по центру | $12 | | зебра-строки | прикольные | $1 | Внешние вертикальные линии (|) не обязательны, и они нужны только чтобы сам код Markdown выглядел красиво. Тот же код можно записать так: Markdown | не такой | красивый --- | --- | --- *Но выводится* | `так же` | **клево** 1 | 2 | 3

Вертикальные линии обозначают столбцы.

Таблицы	Это	Круто
столбец 3	выровнен вправо	$1600
столбец 2	выровнен по центру	$12
зебра-строки	прикольные	$1

Внешние вертикальные линии (|) не обязательны, и они нужны только чтобы сам код Markdown выглядел красиво. Тот же код можно записать так:

Markdown	не такой	красивый
Но выводится	так же	клево
1	2	3

> С помощью цитат очень удобно в письме обозначать исходный текст. > Эта строка - часть той же цитаты. Разрыв цитаты. > Это очень длинная строка, но она будет правильно процитирована даже при размещении на нескольких строках. Продолжаем писать, чтобы эта строка не вмещалась на одной строке в любом окне. Кстати, в цитаты можно *вставлять* даже **Markdown**.

С помощью цитат очень удобно в письме обозначать исходный текст. Эта строка - часть той же цитаты.

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

Часто Markdown понимает чистый HTML.

 Список определений
 Это то, что люди иногда используют.
 Markdown внутри HTML
 Работает *не очень** хорошо. Используйте HTML-теги.

Список определений Это то, что люди иногда используют. Markdown внутри HTML Работает *не очень** хорошо. Используйте HTML-теги.

Три и более. --- Дефисы *** Звездочки ___ Подчеркивания

Jekins / Markdown-docs.md

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

# Заголовок первого уровня ## Заголовок второго уровня ### Заголовок третьего уровня #### Заголовок четвёртого уровня ##### Заголовок пятого уровня ###### Заголовок шестого уровня

Пример:

Заголовок первого уровня

Заголовок второго уровня

Заголовок третьего уровня

Заголовок четвёртого уровня

Заголовок пятого уровня

Заголовок шестого уровня

Параграфы и переносы строк

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

Пример:

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

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

*курсив* _курсив_ **жирный** __жирный__ ***жирный курсив*** ___жирный курсив___ ~~зачеркнутый~~

Пример:

жирный
жирный

жирный курсив
жирный курсив

1. Пункт первый 2. Пункт второй 3. Пункт третий

Пример:

Пункт первый
Пункт второй
Пункт третий

- Пункт первый - Пункт второй - Пункт третий

Пример:

Пункт первый
Пункт второй
Пункт третий

Также можно делать вложенные списки, добавляя 4 пробела перед пунктом:

1. Пункт первый - Подпункт первый - Подпункт второй 2. Пункт второй

Пример:

Пункт первый
- Подпункт первый
- Подпункт второй
Пункт второй

[Текст ссылки](https://www.example.com)

Пример:

![Текст описания](https://www.example.com/image.jpg)

Пример:

`строка кода`

Пример:

\``` Блок кода \```

Пример:

Блок кода

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

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

\```python print("Привет, мир!") \```

Пример:

print("Привет, мир!")

> Первый уровень цитирования >> Второй уровень цитирования >>> Третий уровень цитирования

Пример:

Первый уровень цитирования

Второй уровень цитирования

Третий уровень цитирования

Пример:

| Заголовок 1 | Заголовок 2 | | ----------- | ----------- | | Ячейка 1 | Ячейка 2 | | Ячейка 3 | Ячейка 4 |

Пример:

Заголовок 1	Заголовок 2
Ячейка 1	Ячейка 2
Ячейка 3	Ячейка 4

Таблица как HTML

  Заголовок 1  Заголовок 2  
 Ячейка 1.1  Ячейка 2.1  
 Ячейка 1.2  Ячейка 2.2

Пример:

Заголовок 1	Заголовок 2
Ячейка 1.1	Ячейка 2.1
Ячейка 1.2	Ячейка 2.2

- [x] Задача 1 - [ ] Задача 2 - [ ] Задача 3

Пример:

[Перейти к Заголовку 1](#title1) ## Заголовок 1 Какой-то контент

Пример:

Ссылка на заголовок на английском

[Some title 1](#some-title-1) ## Some Title 1 Some content

Пример:

Пример

Markdown поддерживает использование прямого HTML внутри документа, так что вы можете использовать любые HTML-теги для более сложного оформления:

CTRL + P

Пример:

Например, вы можете использовать HTML-код ¯ для добавления черты над буквой:

Пример:

Вы можете вставить комментарии в свой markdown-файл, которые не будут отображаться в окончательном отформатированном виде:

[//]: # (Это комментарий, он не будет отображаться)

Пример:

Вы можете использовать эмодзи в своих Markdown-файлах. Существует множество эмодзи, которые вы можете использовать, вот некоторые из них:

:smile: :laughing: :blush:

Пример:

vi-k commented Dec 16, 2020 •

этот отличный онлайн редактор показывает не то что отобразит github.. а как сделать что-б было видно сразу что будет на github потом?

Внизу в комментарии напишите и нажмите Preview.

jus1xd commented Feb 6, 2021

я люблю неров сори за мт

vovs03 commented Feb 17, 2021

Преобразование строк в маркерованный список

Коллеги, может кто сталкивался с таким кейсом: "Как в VScode преобразовать строки в маркерованный список?"
Не особо хочется ручками N-строк проходить.

SiAnton commented Mar 11, 2021

Перемещение, траектория, путь

artem-bilas commented May 3, 2021

Спасибо большое) Подсматриваю иногда.

maxrys commented May 18, 2021

Также, можно использовать пробел, чтобы отделять 2 пары квадратных скобок:
[пример][id]:

символ ":" не требуется

maxrys commented May 18, 2021

гиперссылки, заключённый либо в двойные или одиночные кавычки, либо в скобки

официальная версия Markdown поддерживает только двойные кавычки

Li-Deheng commented Jan 5, 2022 •

Task List

Preview

Marked
Unmarked

Write code

- [x] Marked - [ ] Unmarked

nsvk13 commented Oct 6, 2022

Спасибо за руководство, очень полезно.

MikhailMatafonov commented Feb 2, 2023

Ребята! Как делать таблицы на языке верстки Markdown? Видать плохо ищу, но куда бы не зашел нет нигде инфы 🙁

Leksystop commented Feb 2, 2023 via email
http://konvut.github.io/k50articles/ Чт, 2 февр. 2023 г. в 12:12, MikhailMatafonov ***@***.***>:
maxrys commented Feb 2, 2023 •

Ребята! Как делать таблицы на языке верстки Markdown? Видать плохо ищу, но куда бы не зашел нет нигде инфы 🙁

Таблица (как расширение Github)

колонка 1	колонка 2	колонка 3
значение 1.1	значение 2.1	значение 3.1
значение 1.2	значение 2.2	значение 3.2
значение 1.3	значение 2.3	значение 3.3

в Markdown-формате выглядит как:

| колонка 1 | колонка 2 | колонка 3 | | ------------ | ------------ | ------------ | | значение 1.1 | значение 2.1 | значение 3.1 | | значение 1.2 | значение 2.2 | значение 3.2 | | значение 1.3 | значение 2.3 | значение 3.3 |

Таблица как код + псевдографика

┌──────────────┬──────────────┬──────────────┐ │ колонка 1 │ колонка 2 │ колонка 3 │ ├──────────────┼──────────────┼──────────────┤ │ значение 1.1 │ значение 2.1 │ значение 3.1 │ │ значение 1.2 │ значение 2.2 │ значение 3.2 │ │ значение 1.3 │ значение 2.3 │ значение 3.3 │ └──────────────┴──────────────┴──────────────┘

Таблица как HTML

колонка 1	колонка 2	колонка 3
значение 1.1	значение 2.1	значение 3.1
значение 1.2	значение 2.2	значение 3.2
значение 1.3	значение 2.3	значение 3.3

в Markdown-формате выглядит как:

  колонка 1  колонка 2  колонка 3  
 значение 1.1  значение 2.1  значение 3.1  
 значение 1.2  значение 2.2  значение 3.2  
 значение 1.3  значение 2.3  значение 3.3

Li-Deheng commented Feb 2, 2023 •

Ребята! Как делать таблицы на языке верстки Markdown? Видать плохо ищу, но куда бы не зашел нет нигде инфы 🙁

Table in Markdown

Preview

1	2	3	4
Один	Два	Три	Четыре
One	Two	Free	For
一	二	三	四

Write code

| 1 | 2 | 3 | 4 | | ---- | ---- | ---- | ---- | | Один | Два | Три | Четыре | | One | Two | Free | For | | 一 | 二 | 三 | 四 |

MikhailMatafonov commented Feb 3, 2023

Спасибо, за инфу! Разобрал! 🙂

DonLemON228 commented Mar 12, 2023
dmitryloskutnikov commented Mar 15, 2023 •

У меня два вопроса.

2023-03-16_00h44_03

Как закрыть заголовок? Т.е., я открыл заголовок, написал нужный текст, а дальше мне нужно написать текст, который будет всегда виден в заметке, а не скрываться при сворачивании заголовка.
Какие названия цветов поддерживаются? Или как можно проще выделять текст нужным цветом?
Этот текст должен быть серым, а получается зеленым

VladimirMakarof commented Mar 24, 2023
ghost commented Apr 20, 2023

нашёл нужную инфу спс

DmitryChrome commented May 26, 2023

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

Jekins commented May 26, 2023

@DmitryChrome можете попробовать так:

но не везде корректно отображается, бывает не сверху, а рядом отображается

Jekins commented May 26, 2023

Обновил документацию по Markdown ��

IlyaChakov commented May 27, 2023 •

@VladimirMakarof в color = #gray после решетки идет HEX-код цвета, а не его название. Необходимо просто вписать правильный HEX-код, и все будет работать нормально

Jekins commented May 27, 2023 •

@IlyaChakov видимо цвет нельзя задать на гитхаб, так попробовал и не работает:

Этот текст должен быть #218bff

DmitryChrome commented Jun 20, 2023

@Jekins Спасибо, но надо немного другой результат. В виде формулы. Например $ y $ без символов сверху и $ y $ с символом ^ или просто чертой над буквой. Получается только так: $y^-$

Aziza-Nurimova commented Jun 25, 2023

Добрый вечер, а как заголовок можно отображать в середине ячейки?
вот так:
$$ Заголовок $$
отображается в середине, слова слипаются

Jekins commented Jun 25, 2023 •

@Aziza-Nurimova В Markdown нет встроенной функциональности для выравнивания текста в ячейках таблицы. Стандартное поведение - это выравнивание текста в ячейках по левому краю.

Некоторые расширения Markdown или специфические реализации (например, GitHub Flavored Markdown или Markdown Extra) поддерживают расширенное форматирование таблиц, включая выравнивание текста, но это не является стандартным поведением и может не поддерживаться везде.

Если вам нужно выравнивание текста в ячейках таблицы, рассмотрите возможность использования HTML в md файлах вместо стандартного Markdown. Например, вы можете использовать тег

для выравнивания текста по центру:

table> tr> th>center>Заголовок 1center>th> th>center>Заголовок 2center>th> tr> tr> td>Текст 1td> td>Текст 2td> tr> table>

Обратите внимание, что поддержка HTML в Markdown может варьироваться в зависимости от реализации.

Заголовок 1	Заголовок 2
Текст текст текст текст 1	Текст текст текст текст 2

Как вставить код в markdown

Включение кода в документацию

Элементы кода

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

Полужирный стиль

Создание ссылок

Заполнители

Блоки кода

Снимки экрана

Проверка кода

Выделение

Горизонтальные полосы прокрутки

Явное определение неправильного кода

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

Ссылки на фрагмент кода в репозитории

Путь к файлу кода

Выбранные номера строк

Именованный фрагмент кода

Выделение выбранных строк

Ссылки на фрагменты кода в другом репозитории

Фрагменты кода в записной книжке Jupyter

Добавление метаданных в записную книжку

Настройка доступа к репозиторию

Справочник по синтаксису фрагмента кода записной книжки Jupyter

Интерактивные фрагменты кода

Встроенные блоки интерактивного кода

Фрагменты кода, включаемые по ссылке

Синтаксис ссылок на фрагменты

Поддерживаемые языки

Огороженные блоки кода

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

Справочные материалы по Markdown

Оповещения («Примечание», «Совет», «Важно!», «Внимание!», «Предупреждение»)

Угловые скобки

Апострофы и кавычки

Блок цитирования

Полужирное и курсивное начертания

Фрагменты кода

Столбцы

Комментарии

Заголовки

HTML

Изображения

Стандартные схематические изображения (Markdown по умолчанию)

Стандартные концептуальные изображения (Learn Markdown)

Сложные изображения с длинными описаниями

Автоматические границы

Указание области локализации

Значки

Включаемые файлы Markdown

Синтаксис включаемых файлов

Indentation;

Ссылки

Списки (нумерованные, маркированные, контрольные)

Нумерованный список

Маркированный список

Контрольный список

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

Нелокализованные строки

Селекторы

Единичный выбор

Множественный выбор

Подстрочные и надстрочные символы

Таблицы

Разрывы строк внутри слов в любой ячейке таблицы

Разрывы строк внутри слов в ячейках второго столбца

Несогласованные значения ширины столбцов между таблицами

Таблицы матриц данных

Таблицы HTML

fomvasss / Шпаргалка по Markdown.md

Jekins / Markdown-docs.md

Преобразование строк в маркерованный список

Task List

Preview

Write code

Таблица (как расширение Github)

Таблица как код + псевдографика

Таблица как HTML

Table in Markdown

Preview