Markdown

Обзор

Markdown - это облегченный язык разметки, предназначенный для указания форматирования в обычном тексте при максимальном сохранении удобочитаемости для пользователя и подходящий для машинного перевода на продвинутые языки публикации. Первоначально создан в 2004 году Джоном Грубером и Аароном Шварцем. Многие языковые идеи были заимствованы из существующих соглашений о разметке текста в электронных письмах. Реализации языка Markdown преобразуют текст Markdown в допустимый, правильно построенный XHTML и заменяют левые угловые скобки ("<") и амперсанды ("&") соответствующими кодами объектов. Первой реализацией Markdown была реализация на Perl, написанная Грубером, но через некоторое время появилось много реализаций от сторонних разработчиков (см. Ниже). Реализация Perl распространяется под лицензией типа BSD. Реализации Markdown на различных языках программирования включены (или доступны в виде плагина) во многие системы управления контентом. Вы можете использовать любой текстовый редактор для написания Markdown, но мы рекомендуем использовать Visual Studio Code с расширением Docs Authoring Pack. Расширение Doc Authoring Pack содержит инструменты редактирования и функции предварительного просмотра, которые позволяют вам увидеть, как будут выглядеть статьи на сайте документации. Оповещения - это специальное расширение Markdown, которое используется для создания блоков цитирования, отображаемых на сайте документации с использованием цветов и значков, указывающих на важность контента.

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

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

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