Руководство по Markdown

Мэтт Коун

перевод В.Айсин

Исходный текст: https://github.com/mattcone/markdown-guide-book

Эта работа находится под международной лицензией Creative Commons Attribution-ShareAlike 4.0 International.

Саймону Насиму

Введение

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

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

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

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

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

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

У Markdown Guide скромное начало. Он начался как единая веб-страница в 2017 году. Получив положительные отзывы от друзей и коллег, я решил расширить сайт. К моему удивлению, к началу 2018 года Markdown Guide принимал сотни уникальных посетителей в день. Тогда мне пришло в голову, что люди также могут оценить Markdown Guide в книжном формате.

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

Где взять эту книгу

Я хочу, чтобы все прочитали Руководство по Markdown. Вот почему его можно бесплатно скачать в форматах PDF, MOBI и EPUB. Надеюсь, вы поделитесь этим со своими друзьями и семьей. Подавляющее большинство книги также доступно в Интернете по адресу https://www.markdownguide.org.

Как читать эту книгу

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

Ресурсы для начинающих

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

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

Примеры синтаксиса

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

Markdown: это то, что вы будете вводить в своем приложении Markdown.
HTML: это HTML-код, который будет сгенерирован процессором Markdown.
Визуализированный вывод: это то, что увидит читатель.

Чтобы узнать больше о преобразовании Markdown в HTML, см. Раздел о том, как работает Markdown.

Ремарки

Дополнительная информация помечена значком «i», например:

Вот дополнительная информация, которая может оказаться вам полезной.

Советы помечаются значком ключа, например:

Вот отличный совет, который может оказаться полезным.

Странности

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

Содействие

Эта книга является проектом с открытым исходным кодом, и мы будем рады вашим вкладам. Репозиторий размещен на GitHub. Инструкции и рекомендации см. в README.

Сообщения о проблемах

Что-то не так? Создайте issue на GitHub, и я исправлю ошибку как можно скорее. Спасибо!

Благодарности

Я бесконечно благодарен Рим и нашим детям Финну и Саймону. Эта книга не существовала бы без их любви и поддержки.

Я очень признателен А. К. Молтени, Гэйлин Уолли, Хуану Торресу, Дайане Линч и моим родителям, Стиву Коуну и Кэти Латан, которые работали над созданием сайта и книги. Спасибо Джошу Эллингсону за создание изумительной, потрясающей иллюстрации на обложке. И последнее, но не менее важное: я хотел бы поблагодарить вас и всех, кто прочитал Руководство по Markdown и внес свой вклад в него. Вы не только сделали эту книгу возможной, но и сделали ее лучше!

1. Начало работы

Markdown - это облегченный язык разметки, который можно использовать для добавления элементов форматирования в текстовые документы с неформатированным (plain) текстом. Markdown, созданный Джоном Грубером в 2004 году, сейчас является одним из самых популярных языков разметки в мире.

Использование Markdown отличается от использования редактора WYSIWYG. В таком приложении, как Microsoft Word, вы нажимаете кнопки для форматирования слов и фраз, и изменения сразу видны. Markdown не такой. Когда вы создаете файл в формате Markdown, вы добавляете в текст синтаксис Markdown, чтобы указать, какие слова и фразы должны выглядеть иначе.

Например, чтобы обозначить заголовок, вы добавляете перед ним решетку (например, # Первый заголовок). Или, чтобы выделить фразу жирным шрифтом, добавляете две звездочки до и после нее (например, **этот текст выделен жирным шрифтом**). Чтобы привыкнуть к синтаксису Markdown в тексте, может потребоваться некоторое время, особенно если вы привыкли к приложениям WYSIWYG. На снимке экрана ниже показан файл Markdown, отображаемый в текстовом редакторе Atom.

Это файл Markdown в текстовом редакторе Atom.

Вы можете добавить элементы форматирования Markdown в текстовый файл с помощью текстового редактора. Или использовать одно из множества приложений Markdown для операционных систем macOS, Windows, Linux, iOS и Android. Также существует несколько веб-приложений, специально разработанных для написания на Markdown.

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

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

Почему стоит использовать Markdown?

Вам может быть интересно, почему люди используют Markdown вместо WYSIWYG-редактора. Зачем писать с помощью Markdown, если вы можете нажимать кнопки в интерфейсе для форматирования текста? Как оказалось, есть несколько причин, по которым люди используют Markdown вместо редакторов WYSIWYG.

Markdown можно использовать для всего. Люди используют его для создания веб-сайтов, документов, заметок, книг, презентаций, сообщений электронной почты и технической документации.
Markdown переносимый. Файлы, содержащие текст в формате Markdown, можно открывать практически в любом приложении. Если вы решите, что вам не нравится приложение Markdown, которое вы сейчас используете, вы можете импортировать файлы Markdown в другое приложение Markdown. Это резко контрастирует с приложениями для обработки текста, такими как Microsoft Word, которые блокируют ваш контент в проприетарном формате файла.
Markdown не зависит от платформы. Вы можете создавать текст в формате Markdown на любом устройстве под управлением любой операционной системы.
Markdown - это гарантия будущего. Даже если приложение, которое вы используете, перестанет работать в какой-то момент в будущем, вы все равно сможете прочитать текст в формате Markdown с помощью приложения для редактирования текста. Это важное соображение, когда речь идет о книгах, университетских диссертациях и других важных документах, которые необходимо хранить бессрочно.
Markdown везде. Такие сайты, как Reddit и GitHub, поддерживают Markdown, как и множество настольных и веб-приложений.

Прощупываем почву

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

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

Редактор Dillinger Markdown - это бесплатный и простой способ начать работу с Markdown.

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

Как работает Markdown

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

Когда вы пишете в Markdown, текст сохраняется в текстовом файле с расширением .md или .markdown. Но что потом? Как ваш файл в формате Markdown конвертируется в HTML или готовый к печати документ?

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

Приложения Markdown используют так называемый процессор Markdown (также обычно называемый «синтаксическим анализатором» или «реализацией»), чтобы взять текст в формате Markdown и вывести его в формат HTML. На этом этапе ваш документ можно просмотреть в веб-браузере или объединить с таблицей стилей и распечатать. Вы можете увидеть визуальное представление этого процесса ниже.

Приложение и процессор Markdown - это два отдельных компонента. Для краткости я объединил их в один элемент («Приложение Markdown») на рисунке ниже.

Это визуальный обзор процесса Markdown.

Подводя итог, это процесс, состоящий из четырех частей:

Создайте файл Markdown с помощью текстового редактора или специального приложения Markdown. Файл должен иметь расширение .md или .markdown.
Откройте файл Markdown в приложении Markdown.
Используйте приложение Markdown, чтобы преобразовать файл Markdown в документ HTML.
Просмотрите файл HTML в веб-браузере или используйте приложение Markdown, чтобы преобразовать его в другой формат файла, например PDF.

С вашей точки зрения, процесс будет несколько отличаться в зависимости от используемого вами приложения. Например, Диллинджер, по сути, объединяет шаги 1–3 в единый цельный интерфейс - все, что вам нужно сделать, это ввести текст в левой панели, и визуализированный результат волшебным образом появится на правой панели. Но если вы воспользуетесь другими инструментами, такими как текстовый редактор с генератором статических веб-сайтов, вы обнаружите, что процесс намного более заметен.

Дополнительные ресурсы

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

Документация Джона Грубера по Markdown. Оригинальное руководство, написанное создателем Markdown.
Учебник по Markdown. Веб-сайт с открытым исходным кодом, который позволяет вам попробовать Markdown в своем веб-браузере.
Потрясающий Markdown. Список инструментов и учебных ресурсов Markdown.
Верстка в Markdown. Серия из нескольких статей, в которой описывается экосистема для набора документов Markdown с использованием pandoc и ConTeXt.

2. Работа с Markdown

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

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

Вот несколько примеров того, что вы можете делать с Markdown.

Веб-сайты

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

Если вы ищете самый простой способ создать веб-сайт с файлами Markdown, посетите blot.im и smallvictori.es. После того, как вы зарегистрируетесь в одной из этих служб, они создадут папку Dropbox на вашем компьютере. Просто перетащите файлы Markdown в папку и - хрясь! - они есть на вашем сайте. Нет ничего проще.

Если вы знакомы с HTML, CSS и контролем версий, обратите внимание на Jekyll, популярный генератор статических сайтов, который принимает файлы Markdown и создает HTML-сайт. Одним из преимуществ этого подхода является то, что GitHub Pages предоставляет бесплатный хостинг для веб-сайтов, созданных в Jekyll. Если Jekyll вам не по душе, просто выберите один из множества других доступных генераторов статических сайтов.

Я использовал Jekyll для создания веб-сайта Markdown Guide. Вы можете просмотреть исходный код на GitHub.

Если вы хотите использовать систему управления контентом (CMS) для управления своим сайтом, обратите внимание на Ghost. Это бесплатная блог-платформа с открытым исходным кодом и красивым редактором Markdown. Если вы являетесь пользователем WordPress, вы будете рады узнать, что есть поддержка Markdown для веб-сайтов, размещенных на WordPress.com. Самостоятельные сайты WordPress могут использовать плагин Jetpack.

Документы

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

Вот несколько рекомендуемых нами приложений для создания документов Markdown:

Mac: MacDown, iA Writer или Marked
iOS / Android: iA Writer
Windows: ghostwriter или Markdown Monster
Linux: ReText или ghostwriter
Web: Dillinger или StackEdit

iA Writer предоставляет шаблоны для предварительного просмотра, печати и экспорта документов в формате Markdown. Например, шаблон «Academic - MLA Style» делает отступы между абзацами и добавляет двойной интервал между предложениями.

Заметки

Практически во всех отношениях Markdown - идеальный синтаксис для заметок. К сожалению, Evernote и OneNote, два самых популярных приложения для заметок, в настоящее время не поддерживают Markdown. Хорошей новостью является то, что несколько других приложений для заметок поддерживают Markdown:

Simplenote - это бесплатное приложение для создания заметок, доступное для любой платформы.
Notable - приложение для заметок, которое работает на различных платформах.
Bear - приложение, подобное Evernote, доступное для устройств Mac и iOS. По умолчанию он не использует исключительно синтаксис Markdown, но вы можете включить режим совместимости Markdown.
Boostnote позиционирует себя как «приложение для заметок с открытым исходным кодом, разработанное для программистов».

Если вы не можете расстаться с Evernote, попробуйте Marxico, редактор Markdown для Evernote на основе подписки, или используйте Markdown Here с веб-сайтом Evernote.

Книги

Хотите самостоятельно опубликовать роман? Попробуйте Leanpub, сервис, который преобразует файлы в формате Markdown в электронную книгу. Leanpub выводит вашу книгу в форматах файлов PDF, EPUB и MOBI. Если вы хотите создавать копии книги в мягкой обложке, вы можете загрузить файл PDF в другую службу, например Kindle Direct Publishing. Чтобы узнать больше о написании и самостоятельной публикации книги с помощью Markdown, прочитайте это сообщение в блоге.

Презентации

Вы не поверите, но вы можете создавать презентации из файлов в формате Markdown. К созданию презентаций в Markdown нужно немного привыкнуть, но как только вы освоитесь, это будет намного быстрее и проще, чем при использовании таких приложений, как PowerPoint или Keynote. Remark (проект GitHub) - популярный инструмент для создания слайд-шоу Markdown на основе браузера, как и Cleaver (проект GitHub). Если вы используете Mac и предпочитаете использовать приложение, посмотрите Deckset или Marked.

Электронные письма

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

Документация

Markdown естественно подходит для технической документации. Такие компании, как GitHub, все чаще переходят на Markdown для своей документации - посмотрите их сообщение в блоге о том, как они перенесли свою документацию в формате Markdown на Jekyll. Если вы пишете документацию для продукта или услуги, обратите внимание на эти удобные инструменты:

Read the Docs может создать веб-сайт документации из файлов Markdown с открытым исходным кодом. Просто подключите свой репозиторий GitHub к их сервису и выполните push - Read the Docs сделает все остальное. Также у них есть сервис для коммерческих организаций.
MkDocs - это быстрый и простой генератор статических сайтов, предназначенный для создания документации. Исходные файлы написаны на Markdown и организованы с помощью одного файла конфигурации YAML. MkDocs имеет несколько встроенных тем, включая перенос темы документации Read the Docs. Одна из новейших тем - MkDocs Material, которая включает в себя элементы Material Design Google.
Docusaurus - это генератор статических сайтов, предназначенный исключительно для создания веб-сайтов с документацией. Он поддерживает переводы, поиск и управление версиями.
VuePress - это генератор статических сайтов, работающий на Vue и оптимизированный для написания технической документации.
Jekyll упоминался ранее в разделе, посвященном веб-сайтам, но это также хороший вариант для создания веб-сайта документации из файлов Markdown. Если вы пойдете по этому пути, обязательно ознакомьтесь с темой документации Jekyll.

3. Базовый синтаксис

Почти все приложения Markdown поддерживают базовый синтаксис, описанный в исходном проектном документе Джона Грубера. Между процессорами Markdown есть незначительные вариации и несоответствия - они отмечены встроенными везде, где это возможно.

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

Заголовки

Чтобы создать заголовок, добавьте цифровые знаки (#) перед словом или фразой. Количество используемых цифровых знаков должно соответствовать уровню заголовка. Например, чтобы создать заголовок третьего уровня (<h3>), используйте три символа решетки (например, ### Мой заголовок).

Markdown	HTML
`# Заголовок уровня 1`	`<h1>Заголовок уровня 1</h1>`
`## Заголовок уровня 2`	`<h2>Заголовок уровня 2</h2>`
`### Заголовок уровня 3`	`<h3>Заголовок уровня 3</h3>`
`#### Заголовок уровня 4`	`<h4>Заголовок уровня 4</h4>`
`##### Заголовок уровня 5`	`<h5>Заголовок уровня 5</h5>`
`###### Заголовок уровня 6`	`<h6>Заголовок уровня 6</h6>`

Альтернативный синтаксис

Либо в строке под текстом добавьте любое количество символов == для уровня заголовка 1 или символов -- для уровня заголовка 2.

Markdown	HTML
`Заголовок уровня 1 ===============`	`<h1>Заголовок уровня 1</h1>`
`Заголовок уровня 2 ---------------`	`<h2>Заголовок уровня 2</h2>`

Заголовки — лучшие практики

Приложения Markdown не единодушны в том, как обрабатывать недостающий пробел между символами решетки (#) и названием заголовка. Для совместимости всегда ставьте пробел между знаками и названием заголовка.

Правильно	Не правильно
`# Вот заголовок`	`#Вот заголовок`

Абзацы

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

Markdown

Мне очень нравится использовать Markdown.

Думаю, с этого момента я буду им пользоваться.

HTML

<p>Мне очень нравится использовать Markdown.</p>

<p>Думаю, с этого момента я буду им пользоваться.</p>

Отрендеренный вывод выглядит так:

Мне очень нравится использовать Markdown.

Думаю, с этого момента я буду им пользоваться.

Абзацы — лучшие практики

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

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

Разрывы строк

Чтобы создать разрыв строки (<br>), завершите строку двумя или более пробелами, а затем нажмите Enter.

Markdown

Это первая строка.
А это вторая строка.

HTML

<p>Это первая строка.<br />
А это вторая строка.</p>

Отрендеренный вывод выглядит так:

Это первая строка.
А это вторая строка.

Разрывы строк — лучшие практики

Вы можете использовать два или более пробелов (обычно называемые «конечные пробелы») для разрыва строки почти в любом приложении Markdown, но это спорно. В редакторе трудно увидеть завершающие пробелы, и многие люди случайно или намеренно ставят два пробела после каждого предложения. По этой причине вы можете использовать что-то другое, кроме конечных пробелов для разрывов строк. К счастью, почти каждое приложение Markdown поддерживает еще один вариант: HTML-тег <br>.

Для совместимости используйте завершающий пробел или HTML-тег <br> в конце строки.

Есть два других варианта, которые я не рекомендую использовать. CommonMark и несколько других облегченных языков разметки позволяют вводить обратную косую черту (\) в конце строки, но не все приложения Markdown поддерживают это, так что это не лучший вариант с точки зрения совместимости. И, по крайней мере, пара легких языков разметки ничего не требует в конце строки — просто введите Enter, и они создадут разрыв строки.

Правильно	Не правильно
`Первая строка с двумя пробелами после. И следующая строка.`	`Первая строка с обратной косой чертой после. \ И следующая строка.`
`С тегом HTML после.<br> И следующая строка.`	`Без ничего после. И следующая строка.`

Акцент

Вы можете выделить текст, выделив его жирным шрифтом или курсивом.

Жирный

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

Markdown

Мне нравится **жирный текст**.

Мне нравится __жирный текст__.

Любовь**это**смело

HTML-вывод первых двух примеров одинаковый.

HTML

Мне нравится <strong>жирный текст</strong>.

Любовь<strong>это</strong>смело

Отрендеренный вывод выглядит так:

Мне нравится жирный текст.

Любовьэтосмело

Жирный текст — лучшие практики

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

Правильно	Не правильно
`Любовьэтосмело`	`Любовь__это__смело`

Курсив

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

Markdown

Кот *сказал мяу*.

Кот _сказал мяу_.

Кот*сказал*мяу

HTML-вывод первых двух примеров такой же.

HTML

Кот <em>сказал мяу</em>.

Кот<em>сказал</em>мяу

Отрендеренный вывод выглядит так:

Кот сказал мяу.

Котсказалмяу

Курсив - лучшие практики

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

Правильно	Не правильно
`Котсказалмяу`	`Кот_сказал_мяу`

Полужирный и курсив

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

Markdown

***Важный*** текст.

___Важный___ текст.

__*Важный*__ текст.

**_Важный_** текст.

Действительно***очень***важный текст.

HTML-вывод первых четырех примеров одинаков.

HTML

<strong><em>Важный</em></strong> текст.

Действительно<strong><em>очень</em></strong>важный текст.

Отрендеренный вывод выглядит так:

Важный текст.

Действительнооченьважный текст.

Жирный и курсив - лучшие практики

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

Правильно	Не правильно
`Действительно*очень*важный текст.`	`Действительно___очень___важный текст.`

Цитаты

Чтобы создать цитату, добавьте > перед абзацем.

Markdown

> Дороти последовала за ней через множество комнат.

HTML

<blockquote>Дороти последовала за ней через множество комнат.</blockquote>

Отрендеренный вывод выглядит так:

Дороти прошла за ней через множество комнат.

Цитаты с несколькими абзацами

Цитаты могут содержать несколько абзацев. Добавьте > в пустые строки между абзацами.

Markdown

> Это первый абзац.
>
> Это второй абзац.

HTML

<blockquote>
    <p>Это первый абзац.</p>
    <p>Это второй абзац.</p>
</blockquote>

Отрендеренный вывод выглядит так:

Это первый абзац.

А это второй абзац.

Вложенные цитаты

Цитаты могут быть вложенными. Добавьте >> перед абзацем, который хотите вложить.

Markdown

> Это первый абзац.
>
> А это вложенный абзац.

HTML

<blockquote>
    <p>Это первый абзац.</p>
    <blockquote>
        <p>Это второй абзац.</p>
    </blockquote>
</blockquote>

Отрендеренный вывод выглядит так:

Это первый абзац.

А это вложенный абзац.

Цитаты с другими элементами

Цитаты могут содержать другие отформатированные элементы Markdown. Не все элементы можно использовать - вам нужно поэкспериментировать, чтобы увидеть, какие из них работают.

Markdown

> ##### Квартальные результаты выглядят великолепно!
>
> - Доход был за пределами графика.
> - Прибыль была выше, чем когда-либо.
>
>  *Все* идет **хорошо**.

HTML

<blockquote>
  <h5>Квартальные результаты выглядят великолепно!</h5>
  <ul>
    <li>Доход был за пределами графика.</li>
    <li>Прибыль была выше, чем когда-либо.</li>
  </ul>
  <p><em>Все</em> идет <strong>хорошо</strong>.</p>
</blockquote>

Отрендеренный вывод выглядит так:

Квартальные результаты выглядят великолепно!

Доход был за пределами графика.

Прибыль была выше, чем когда-либо.

Все идет хорошо.

Списки

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

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

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

Markdown

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

1. Первый пункт
1. Второй пункт
1. Третий пункт
1. Четвертый пункт

1. Первый пункт
8. Второй пункт
3. Третий пункт
5. Четвертый пункт

HTML-вывод всех трех примеров списков одинаков.

HTML

<ol>
  <li>Первый пункт</li>
  <li>Второй пункт</li>
  <li>Третий пункт</li>
  <li>Четвертый пункт</li>
</ol>

Отрендеренный вывод выглядит так:

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

Вложенные элементы списка

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

Markdown

1. Первый пункт
2. Второй пункт
3. Третий пункт
    1. Вложенный пункт
    2. Вложенный пункт
4. Четвертый пункт

HTML-вывод всех трех примеров списков одинаков.

HTML

<ol>
  <li>Первый пункт</li>
  <li>Второй пункт</li>
  <li>Третий пункт
    <ol>
      <li>Вложенный пункт</li>
      <li>Вложенный пункт</li>
    </ol>
  </li>
  <li>Четвертый пункт</li>
</ol>

Отрендеренный вывод выглядит так:

Первый пункт
Второй пункт
Третий пункт
1. Вложенный пункт
2. Вложенный пункт
Четвертый пункт

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

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

Markdown

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

* Первый пункт
* Второй пункт
* Третий пункт
* Четвертый пункт

+ Первый пункт
* Второй пункт
- Третий пункт
+ Четвертый пункт

HTML-вывод всех трех примеров списков одинаков.

HTML

<ul>
  <li>Первый пункт</li>
  <li>Второй пункт</li>
  <li>Третий пункт</li>
  <li>Четвертый пункт</li>
</ul>

Отрендеренный вывод выглядит так:

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

Вложенные элементы списка

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

Markdown

- Первый пункт
- Второй пункт
- Третий пункт
    - Вложенный пункт
    - Вложенный пункт
- Четвертый пункт

HTML-вывод всех трех примеров списков одинаков.

HTML

<ul>
  <li>Первый пункт</li>
  <li>Второй пункт</li>
  <li>Третий пункт
    <ul>
      <li>Вложенный пункт</li>
      <li>Вложенный пункт</li>
    </ul>
  </li>
  <li>Четвертый пункт</li>
</ul>

Отрендеренный вывод выглядит так:

Первый пункт
Второй пункт
Третий пункт
- Вложенный пункт
- Вложенный пункт
Четвертый пункт

Добавление элементов в списки

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

Абзацы

Markdown

* Это первый пункт списка.
* Вот второй пункт списка.

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

* И вот третий пункт списка.

HTML

<ul>
    <li><p>Это первый пункт списка.</p></li>
    <li><p>Вот второй пункт списка.</p>
        <p>Мне нужно добавить еще один абзац под вторым элементом списка.</p>
    </li>
    <li><p>И вот третий пункт списка.</p></li>
</ul>

Отрендеренный вывод выглядит так:

Это первый пункт списка.
Вот второй пункт списка.

Мне нужно добавить еще один абзац под вторым элементом списка.
И вот третий пункт списка.

Цитаты

Markdown

* Это первый пункт списка.
* Вот второй пункт списка.

    > Здесь отлично бы смотрелась цитата.

* И вот третий пункт списка.

HTML

<ul>
    <li><p>Это первый пункт списка.</p></li>
    <li><p>Вот второй пункт списка.</p>
        <blockquote>
            <p>Здесь отлично бы смотрелась цитата.</p>
        </blockquote>
    </li>
    <li><p>И вот третий пункт списка.</p></li>
</ul>

Отрендеренный вывод выглядит так:

Это первый пункт списка.
Вот второй пункт списка.

Здесь отлично бы смотрелась цитата.
И вот третий пункт списка.

Блоки кода

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

Markdown

1. Откройте файл.
2. Найдите следующий блок кода в строке 21:

        <html>
            <head>
                <title>Test</title>
            </head>

3. Обновите заголовок, чтобы он соответствовал названию вашего веб-сайта.

HTML

<ol>
    <li><p>Откройте файл.</p></li>
    <li><p>Найдите следующий блок кода в строке 21:</p>
        <pre><code>&lt;html&gt;
            &lt;head&gt;
                &lt;title&gt;Test&lt;/title&gt;
            &lt;/head&gt;
        </code></pre>
    </li>
    <li><p>Обновите заголовок, чтобы он соответствовал названию вашего веб-сайта.</p></li>
</ol>

Отрендеренный вывод выглядит так:

Откройте файл.
Найдите следующий блок кода в строке 21:
```
<html>
    <head>
        <title>Test</title>
    </head>
```
Обновите заголовок, чтобы он соответствовал названию вашего веб-сайта.

Изображения

Markdown

1. Откройте файл, содержащий Тукса, талисмана Linux.
2. Полюбуйтесь его красотой.

    ![Tux](images/tux.png)

3. Закройте файл.

HTML

<ol>
    <li><p>Откройте файл, содержащий Тукса, талисмана Linux.</p></li>
    <li>
        <p>Полюбуйтесь его красотой.</p>
        <p><img src="images/tux.png" alt="Tux" /></p>
    </li>
    <li><p>Закройте файл.</p></li>
</ol>

Отрендеренный вывод выглядит так:

Откройте файл, содержащий Тукса, талисмана Linux.
Полюбуйтесь его красотой.
Закройте файл.

Код

Чтобы обозначить слово или фразу как код, заключите их в обратные кавычки (`).

Markdown

В командной строке введите `nano`.

HTML

В командной строке введите <code>nano</code>.

Отрендеренный вывод выглядит так:

В командной строке введите nano.

Экранирование обратных кавычек

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

Markdown

``Используйте `code` в вашем файле Markdown``

HTML

<code>Используйте `code` в вашем файле Markdown.</code>

Отрендеренный вывод выглядит так:

Используйте `code` в вашем файле Markdown.

Блоки кода

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

Markdown


    <html>
        <head>
        </head>
    </html>

HTML

<pre>
    <code>
        &lt;html&gt;
            &lt;head&gt;
            &lt;/head&gt;
        &lt;/html&gt;
    </code>
</pre>

Отрендеренный вывод выглядит так:

<html>
    <head>
    </head>
</html>

Чтобы создать блоки кода без отступов строк, используйте изолированные блоки кода.

Горизонтальные линии

Чтобы создать горизонтальную линию, используйте три или более звездочек (***), тире (---) или подчеркивания (___) в отдельной строке.

Markdown

***

---

_________________

HTML

<pre>
<hr />

<hr />

<hr />

Визуализированный вывод всех трех выглядит одинаково:

Горизонтальные линии - лучшие практики

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

Правильно:

Markddown

Попробуйте поставить перед...

---

...и после горизонтальной линии.

Не правильно:

Markddown

Без пустых строк это был бы заголовок.
---
Не делай так!

Ссылки

Чтобы создать ссылку, заключите текст ссылки в квадратные скобки (например, [Duck Duck Go]), а затем сразу же за ним, укажите URL-адрес в круглых скобках (например, (https://duckduckgo.com)).

Markdown

Используйте [Duck Duck Go](https://duckduckgo.com).

HTML

Используйте <a href="https://duckduckgo.com">Duck Duck Go</a>.

Результат рендеринга выглядит так:

Используйте Duck Duck Go.

Добавление атрибутов title

При желании вы можете добавить атрибут title для ссылки. Это будет отображаться в виде всплывающей подсказки, когда пользователь наведет курсор на ссылку. Чтобы добавить title, добавьте его в круглые скобки после URL-адреса.

Markdown

Используйте [Duck Duck Go](https://duckduckgo.com "Моя поисковая система!").

HTML

Используйте <a href="https://duckduckgo.com" title="Моя поисковая система!">Duck Duck Go</a>.

Отрендеренный вывод выглядит так:

Используйте Duck Duck Go.

URLы и Email-адреса

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

Markdown

<https://eff.org>
<fake@example.com>

HTML

<a href="https://eff.org">https://eff.org</a>
<a href="mailto:fake@example.com">fake@example.com</a>

Отрендеренный вывод выглядит так:

https://eff.org
fake@example.com

Форматирование ссылок

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

Markdown

Мне нравится поддерживать **[EFF](https://eff.org)**.
Это *[EFF](https://eff.org)*.
См. раздел [`код`](#code).

HTML

Мне нравится поддерживать <strong><a href="https://eff.org">EFF</a></strong>.
Это <em><a href="https://eff.org">EFF</a></em>.
См. раздел <a href="#code"><code>код</code></a>.

Отрендеренный вывод выглядит так:

Мне нравится поддерживать EFF.
Это EFF.
См. раздел код.

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

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

Форматирование первой части ссылки

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

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

Это означает, что все следующие форматы примеров примерно эквивалентны для первой части ссылки:

[хоббитовая нора] [1]
[хоббитовая нора] [1]
[хоббит-нора] [а]
[хоббитовая нора] [A]

Форматирование второй части ссылки

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

Метка в скобках, сразу за которой следует двоеточие и хотя бы один пробел (например, [label]:).
URL-адрес ссылки, который при желании можно заключить в угловые скобки.
Необязательный атрибут title для ссылки, который вы можете заключить в двойные или одинарные кавычки или круглые скобки.

Это означает, что все следующие форматы примеров примерно эквивалентны для второй части ссылки:

[нора хоббита]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
[нора хоббита]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Образ жизни хоббита"
[нора хоббита]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Образ жизни хоббита'
[нора хоббита]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle (Образ жизни хоббита)
[нора хоббита]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "Образ жизни хоббита"
[нора хоббита]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Образ жизни хоббита'
[нора хоббита]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> (Образ жизни хоббита)

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

Пример соединения частей

Допустим, вы добавляете URL-адрес в качестве стандартной ссылки URL в абзац, и в Markdown он выглядит следующим образом:

Markdown

В яме в земле жил хоббит. Это была не мерзкая, грязная, мокрая яма, где со всех сторон торчат хвосты червей и пахнет плесенью, и не сухая, голая, песчаная яма, где не на что сесть и нечего съесть: это была [нора хоббита]( https://en.wikipedia.org/wiki/Hobbit#Lifestyle "Образ жизни хоббита"), а значит -- благоустроенная.

Markdown

В яме в земле жил хоббит. Это была не мерзкая, грязная, мокрая яма, где со всех сторон торчат хвосты червей и пахнет плесенью, и не сухая, голая, песчаная яма, где не на что сесть и нечего съесть: это была [нора хоббита][1], а значит -- благоустроенная.

В обоих приведенных выше случаях HTML-код ссылки будет идентичным:

HTML

<a href="https://en.wikipedia.org/wiki/Hobbit#Lifestyle" title="Образ жизни хоббита">нора хоббита</a>

Вывод также идентичен:

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

Ссылки - лучшие практики

Приложения Markdown не единодушны в том, как обрабатывать пробелы в середине URL. Для совместимости попробуйте кодировать любые пробелы в URL с помощью %20.

Правильно:

Markddown

[link](https://www.example.com/my%20great%20page)

Не правильно:

Markddown

[link](https://www.example.com/my great page)

Изображения

Чтобы добавить изображение, добавьте восклицательный знак (!), за которым следует текст атрибута alt в квадратных скобках, а также путь или URL-адрес ресурса изображения в круглых скобках. При желании вы можете добавить заголовок после URL-адреса в круглых скобках.

Markdown

![Волшебные сады Филадельфии. Это было так здорово!](images/philly-magic-garden.png "Волшебные сады Филадельфии")

HTML

<img src="images/philly-magic-garden.png" alt="Волшебные сады Филадельфии. Это было так здорово!" title="Волшебные сады Филадельфии" />

Отрендеренный вывод выглядит так:

Волшебные сады Филадельфии. Это было так здорово!

Изображение в качестве ссылки

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

Markdown

[![Старая скала в пустыне](images/shiprock.jpg)](https://en.wikipedia.org/wiki/Shiprock)

HTML

<a href="https://en.wikipedia.org/wiki/Shiprock"><img src="images/shiprock.jpg" alt="Старая скала в пустыне"></a>

Экранирующие символы

Чтобы отобразить буквальный символ, который в противном случае использовался бы для форматирования текста в документе Markdown, добавьте обратную косую черту (\) перед символом.

Markdown

\* Без обратной косой черты это было бы маркером в неупорядоченном списке.

HTML

* Без обратной косой черты это было бы маркером в неупорядоченном списке.

Отрендеренный вывод выглядит так:

* Без обратной косой черты это было бы маркером в неупорядоченном списке.

Символы, которые вы можете избежать

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

Символ	Название
`\`	обратная косая черта
`	обратная кавычка (см. также экранирование обратных кавычек в коде)
`*`	звездочка
`_`	подчеркивание
`{}`	фигурные скобки
`[]`	квадратные скобки
`()`	круглые скобки
`#`	решетка (знак фунта)
`+`	знак плюс
`-`	знак минус (дефис)
`.`	точка
`!`	восклицательный знак
`\|`	вертикальная черта (pipe) (см. также экранирование вертикальной черты в таблицах)

HTML

Многие приложения Markdown позволяют использовать HTML-теги в тексте в формате Markdown. Это полезно, если вы предпочитаете определенные HTML-теги синтаксису Markdown. Например, некоторым людям проще использовать HTML-теги для изображений. Использование HTML также полезно, когда вам нужно изменить атрибуты элемента, например указать цвет текста или изменить ширину изображения.

Чтобы использовать HTML, поместите теги в текст файла в формате Markdown.

Markdown

Это **слово** выделено жирным шрифтом. Это слово выделено курсивом.

HTML

Это <strong>слово</strong> выделено жирным шрифтом. Это <em>слово</em> выделено курсивом.

Отрендеренный вывод выглядит так:

Это слово выделено жирным шрифтом. Это слово выделено курсивом.

HTML - лучшие практики

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

Используйте пустые строки для отделения HTML-элементов уровня блока, таких как <div>, <table>, <pre> и <p>, от окружающего содержимого. Старайтесь не делать отступы в тегах табуляцией или пробелами — это может помешать форматированию.

Вы не можете использовать синтаксис Markdown внутри HTML-тегов блочного уровня. Например, <p>*курсив* и **полужирный**</p> не работают.

4. Расширенный синтаксис

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

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

Доступность

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

Облегченные языки разметки

Есть несколько облегченных языков разметки, которые являются надмножествами Markdown. Они включают базовый синтаксис Грубера и основываются на нем, добавляя дополнительные элементы, такие как таблицы, блоки кода, выделение синтаксиса, автоматическое связывание URL-адресов и сноски. Многие из самых популярных приложений Markdown используют один из следующих облегченных языков разметки:

Markdown процессоры

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

Таблицы

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

Markdown

| Синтаксис      | Описание |
| ----------- | ----------- |
| Заголовок      | Название       |
| Абзац   | Текст        |

HTML

<table>
    <thead>
    <tr class="header">
        <th>Синтаксис</th>
        <th>Описание</th>
    </tr>
    </thead>
    <tbody>
    <tr class="odd">
        <td>Заголовок</td>
        <td>Название</td>
    </tr>
    <tr class="even">
        <td>Абзац</td>
        <td>Текст</td>
    </tr>
    </tbody>
</table>

Отрендеренный вывод выглядит так:

Синтаксис	Описание
Заголовок	Название
Абзац	Текст

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

| Синтаксис | Описание |
| --- | ----------- |
| Заголовок | Название |
| Абзац | Текст |

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

Выравнивание

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

Markdown

| Синтаксис      | Описание | Тестовый текст     |
| :---        |    :----:   |          ---: |
| Заголовок      | Название       | Вот этот   |
| Абзац   | Текст        | И многое другое      |

HTML

<table>
    <thead>
        <tr class="header">
            <th style="text-align: left;">Синтаксис</th>
            <th style="text-align: center;">Описание</th>
            <th style="text-align: right;">Тестовый текст</th>
        </tr>
    </thead>
    <tbody>
        <tr class="odd">
            <td style="text-align: left;">Заголовок</td>
            <td style="text-align: center;">Название</td>
            <td style="text-align: right;">Вот этот</td>
        </tr>
        <tr class="even">
            <td style="text-align: left;">Абзац</td>
            <td style="text-align: center;">Текст</td>
            <td style="text-align: right;">И многое другое</td>
        </tr>
    </tbody>
</table>

Отрендеренный вывод выглядит так:

Синтаксис	Описание	Тестовый текст
Заголовок	Название	Вот этот
Абзац	Текст	И многое другое

Форматирование текста в таблицах

Вы можете форматировать текст в таблицах. Например, вы можете добавить ссылки, код (только слова или фразы в обратных кавычках (`), а не блоки кода) и акцентирование.

Вы не можете добавлять заголовки, цитаты, списки, горизонтальные линии, изображения или HTML-теги.

Экранирование символов вертикальной черты в таблицах

Вы можете отобразить вертикальную черту (|) в таблице, используя ее код символа HTML (|).

Изолированные блоки кода

Базовый синтаксис Markdown позволяет создавать блоки кода путем отступа строк четырьмя пробелами или одной табуляцией. Если вам это неудобно, попробуйте использовать изолированные блоки кода. В зависимости от вашего процессора или редактора Markdown вы будете использовать три обратных кавычки (```) или три тильды (~~~) в строках до и после блока кода. И что чудесно — Вам не нужно делать отступы!

Markdown

```
{
    "firstName": "John",
    "lastName": "Smith",
    "age": 25
}
```

HTML

<pre>
    <code>
        {
            &quot;firstName&quot;: &quot;John&quot;,
            &quot;lastName&quot;: &quot;Smith&quot;,
            &quot;age&quot;: 25
        }
    </code>
</pre>

Отрендеренный вывод выглядит так:

{
    "firstName": "John",
    "lastName": "Smith",
    "age": 25
}

Необходимо отобразить обратные кавычки внутри блока кода? См. этот раздел, чтобы узнать, как их экранировать.

Подсветка синтаксиса

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

Markdown

```json
{
    "firstName": "John",
    "lastName": "Smith",
    "age": 25
}
```

HTML

<pre>
    <code class="language-json">
        {
            &quot;firstName&quot;: &quot;John&quot;,
            &quot;lastName&quot;: &quot;Smith&quot;,
            &quot;age&quot;: 25
        }
    </code>
</pre>

Отрендеренный вывод выглядит так:

{
    "firstName": "John",
    "lastName": "Smith",
    "age": 25
}

Сноски

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

Чтобы создать ссылку на сноску, добавьте курсор и идентификатор в квадратные скобки ([^1]). Идентификаторы могут быть числами или словами, но не могут содержать пробелов или табуляции. Идентификаторы только коррелируют ссылку на сноску с самой сноской — в выводе сноски нумеруются последовательно.

Добавьте сноску, используя другую вставку и номер в квадратных скобках с двоеточием и текстом ([^1]: Моя сноска.). Необязательно ставить сноски в конце документа. Вы можете разместить их где угодно, кроме других элементов, таких как списки, кавычки и таблицы.

Markdown

Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

HTML

<p> Here’s a simple footnote,<a href="#fn1" class="footnote-ref" id="fnref1"><sup>1</sup></a> and here’s a longer one.<a href="#fn2" class="footnote-ref" id="fnref2"><sup>2</sup></a> </p>
<section class="footnotes">
    <hr />
    <ol>
        <li id="fn1">
            <p>This is the first footnote.<a href="#fnref1" class="footnote-back">↩︎</a></p>
        </li>
        <li id="fn2">
            <p>Here’s one with multiple paragraphs and code.</p>
            <p>Indent paragraphs to include them in the footnote.</p>
            <p><code>{ my code }</code></p>
            <p>Add as many paragraphs as you like.<a href="#fnref2" class="footnote-back">↩︎</a></p>
        </li>
    </ol>
</section>

Отрендеренный вывод выглядит так:

Вот простая сноска¹, а вот и более длинная².

¹ Это первая сноска.

² А эта с несколькими абзацами и кодом.
Сделайте абзацы отступом, чтобы включить их в сноску.
{ мой код }
Добавьте столько абзацев, сколько хотите.

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

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

Markdown

### Мой отличный заголовок {#custom-id}

HTML

<h3 id="custom-id">Мой отличный заголовок</h3>

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

Вы можете связать заголовки с пользовательскими идентификаторами в файле, создав стандартную ссылку со знаком нумерации (#), за которым следует пользовательский идентификатор заголовка.

Markdown

[Идентификаторы заголовков](#heading-ids)

HTML

<a href="#heading-ids">Идентификаторы заголовков</a>

Списки определений

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

Markdown

Первый термин
: Это определение первого термина.

Второй термин
: Это одно из определений второго термина.
: Это еще одно определение второго термина.

HTML

<dl>
    <dt>Первый термин</dt>
    <dd>Это определение первого термина.</dd>
    <dt>Второй термин</dt>
    <dd>Это одно из определений второго термина. </dd>
    <dd>Это еще одно определение второго термина.</dd>
</dl>

Отрендеренный вывод выглядит так:

Первый термин: Это определение первого термина.
Второй термин: Это одно из определений второго термина.; Это еще одно определение второго термина.

Зачеркнутый текст

Вы можете «зачеркивать» слова, проводя горизонтальную линию в центре. Эта функция позволяет указать, что определенные слова являются ошибкой, не предназначенной для включения в документ. Чтобы зачеркнуть слова, используйте два символа тильды (~~) до и после слов.

Markdown

Мир ~~плоский~~ круглый.

HTML

<p>Мир <del>плоский</del> круглый.</p>

Отрендеренный вывод выглядит так:

Мир ~~плоский~~ круглый.

Списки задач

Списки задач позволяют создавать список элементов с флажками. В приложениях Markdown, поддерживающих списки задач, рядом с содержимым будут отображаться флажки. Чтобы создать список задач, добавьте тире (-) и квадратные скобки с пробелом ([ ]) перед элементами списка задач. Чтобы установить флажок, добавьте x в скобки ([x]).

Markdown

- [x] Написать пресс-релиз
- [ ] Обновить сайт
- [ ] Связаться со СМИ

Отрендеренный вывод выглядит так:

Написать пресс-релиз
Обновить сайт
Связаться со СМИ

Эмодзи

Есть два способа добавить смайлики в файлы Markdown: скопировать и вставить смайлы в текст в формате Markdown или ввести короткие коды смайлов.

Копирование и вставка эмодзи

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

Если вы используете генератор статических сайтов, убедитесь, что вы кодируете HTML-страницы как UTF-8.

Использование шорткодов эмодзи

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

Markdown

Ушел в поход! :tent: Скоро вернусь.

Это так смешно! :joy:

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

Автоматическая привязка URL

Многие процессоры Markdown автоматически превращают URL-адреса в ссылки. Это означает, что если вы введете http://www.example.com, ваш процессор Markdown автоматически превратит его в ссылку, даже если вы не использовали скобки.

Markdown

http://example.com

HTML

<a href="http://example.com">http://example.com</a>

Отрендеренный вывод выглядит так:

http://example.com

Отключение автоматического связывания URL-адресов

If you don’t want a URL to be automatically linked, you can remove the link by denoting the URL as code with tick marks.

Markdown 1 `http://www.example.com` HTML 1 http://www.example.com

Отрендеренный вывод выглядит так:

http://www.example.com

Отключение автоматического связывания URL

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

Markdown

`http://www.example.com`

HTML

<code>http://www.example.com</code>

Отрендеренный вывод выглядит так:

http://www.example.com

5. Cheat Sheet

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

Базовый синтаксис

Эти элементы обозначены в исходном проектном документе Джона Грубера. Все приложения Markdown поддерживают эти элементы.

Элемент	Синтаксис Markdown
Заголовки	`# H1` `## H2` `### H3`
Полужирный	`полужирный текст`
Курсив	`курсивный текст`
Цитата	`> цитата`
Упорядоченный список	`1. Первый пункт` `2. Второй пункт` `3. Третий пункт`
Неупорядоченный список	`- Первый пункт` `- Второй пункт` `- Третий пункт`
Код	`код`
Горизонтальная линия	`---`
Ссылка	`[текст ссылки](https://www.example.com)`
Изображение	`![alt-текст](image.jpg)`

Расширенный синтаксис

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

Элемент	Синтаксис Markdown
Таблица	`\| Синтаксис \| Описание \| \| --------- \| -------- \| \| Заголовок \| Название \| \| Абзац \| Текст \|`
Изолированный блок кода	``` { "firstName": "John", "lastName": "Smith", "age": 25 } ```
Сноска	`Вот предложение со сноской. [^1] [^1]: Это сноска.`
Идентификатор заголовка	`### Мой заголовок {#custom-id}`
Список определений	`термин : определение`
Зачеркнутый текст	`~~Земля плоская.~~`
Список задач	`- [x] Написать пресс-релиз - [ ] Обновить сайт - [ ] Связаться со СМИ`

Об авторе

Мэтт Коун — технический писатель в Fastly. У него есть опыт создания документации для таких организаций, как Linode и Министерство здравоохранения и социальных служб США. Первая книга Мэтта Master Your Mac была опубликована издательством No Starch Press. Чтобы связаться с Мэттом, посетите https://www.mattcone.com.

Руководство по Markdown

Мэтт Коун перевод В.Айсин

Введение

Где взять эту книгу

Как читать эту книгу

Ресурсы для начинающих

Примеры синтаксиса

Ремарки

Странности

Содействие

Сообщения о проблемах

Благодарности

1. Начало работы

Почему стоит использовать Markdown?

Прощупываем почву

Как работает Markdown

Дополнительные ресурсы

2. Работа с Markdown

Веб-сайты

Документы

Заметки

Книги

Презентации

Электронные письма

Документация

3. Базовый синтаксис

Заголовки

Альтернативный синтаксис

Заголовки — лучшие практики

Абзацы

Абзацы — лучшие практики

Разрывы строк

Разрывы строк — лучшие практики

Акцент

Жирный

Жирный текст — лучшие практики

Курсив

Курсив - лучшие практики

Полужирный и курсив

Жирный и курсив - лучшие практики

Цитаты

Цитаты с несколькими абзацами

Вложенные цитаты

Цитаты с другими элементами

Квартальные результаты выглядят великолепно!

Списки

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

Вложенные элементы списка

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

Вложенные элементы списка

Добавление элементов в списки

Абзацы

Цитаты

Блоки кода

Изображения

Код

Экранирование обратных кавычек

Блоки кода

Горизонтальные линии

Горизонтальные линии - лучшие практики

Ссылки

Добавление атрибутов title

URLы и Email-адреса

Форматирование ссылок

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

Форматирование первой части ссылки

Форматирование второй части ссылки

Пример соединения частей

Ссылки - лучшие практики

Изображения

Изображение в качестве ссылки

Экранирующие символы

Символы, которые вы можете избежать

HTML

HTML - лучшие практики

4. Расширенный синтаксис

Доступность

Облегченные языки разметки

Markdown процессоры

Таблицы

Мэтт Коун

перевод В.Айсин