Язык разметки Markdown создан Джоном Грубером (англ. John Gruber) в 2004 году. Авторы задавались целью создать максимально удобочитаемый и удобный в публикации облегчённый язык разметки, пригодный для последующего преобразования в HTML (а также и в другие форматы).
Также реализации Markdown варьируют в зависимости от парсера. В этом руководстве будет указано, какие функции универсальны для языка, а какие зависят от конкретного парсера.
HTML-элементы ¶
Markdown является надмножеством HTML, поэтому любой HTML-файл является корректным документом Markdown.
1<!-- Это позволяет использовать напрямую
2любые элементы HTML-разметки, такие, например, как этот комментарий.
3 Встроенные в документ HTML-элементы не затрагиваются парсером Markdown
4и попадают в итоговый HTML без изменений. Однако следует понимать,
5что эта же особенность не позволяет использовать разметку Markdown внутри
6HTML-элементов -->
Заголовки ¶
HTML-элементы от <h1> до <h6> размечаются очень просто:
текст, который должен стать заголовком, предваряется
соответствующим количеством символов «#»:
1# Это заголовок h1
2## Это заголовок h2
3### Это заголовок h3
4#### Это заголовок h4
5##### Это заголовок h5
6###### Это заголовок h6
Markdown позволяет размечать заголовки <h1> и <h2> ещё одним способом:
1Это заголовок h1
2================
3
4А это заголовок h2
5------------------
Простейшая стилизация текста ¶
Текст легко сделать полужирным и/или курсивным:
1*Этот текст будет выведен курсивом.*
2_Так же, как этот._
3
4**А этот текст будет полужирным.**
5__И этот тоже.__
6
7***Полужирный курсив.***
8**_И тут!_**
9*__И даже здесь!__*
В GitHub Flavored Markdown, стандарте, который используется в GitHub, текст также можно сделать зачёркнутым:
1~~Зачёркнутый текст.~~
Абзацы ¶
Абзацами являются любые строки, следующие друг за другом. Разделяются же абзацы одной или несколькими пустыми строками:
1Это абзац. Я печатаю в абзаце, разве это не прикольно?
2
3А тут уже абзац №2.
4Эта строка всё ещё относится к абзацу №2!
5
6
7О, а вот это уже абзац №3!
Для вставки принудительных переносов можно завершить абзац двумя дополнительными пробелами:
1Эта строка завершается двумя пробелами (выделите, чтобы увидеть!).
2
3Над этой строкой есть <br />!
Цитаты размечаются с помощью символа «>»:
1> Это цитата. В цитатах можно
2> принудительно переносить строки, вставляя «>» в начало каждой следующей строки. А можно просто оставлять их достаточно длинными, и такие длинные строки будут перенесены автоматически.
3> Разницы между этими двумя подходами к переносу строк нет, коль скоро
4> каждая строка начинается с символа «>»
5
6> А ещё цитаты могут быть многоуровневыми:
7>> как здесь
8>>> и здесь :)
9> Неплохо?
Списки ¶
Маркированные списки размечаются вставкой в начало каждого элемента одного из символов «*», «+» или «-»: (символ должен быть одним и тем же для всех элементов)
1* Список,
2* Размеченный
3* Звёздочками
4
5либо
6
7+ Список,
8+ Размеченный
9+ Плюсами
10
11либо
12
13- Список,
14- Размеченный
15- Дефисами
В нумерованных списках каждая строка начинается с числа и точки вслед за ним:
11. Первый элемент
22. Второй элемент
33. Третий элемент
Заметьте, нумеровать элементы корректно необязательно. Достаточно указать любое число в начале каждого элемента, и парсер пронумерует элементы сам! Правда, злоупотреблять этим не стоит :)
11. Первый элемент
21. Второй элемент
31. Третий элемент
(Этот список будет отображён так же, как и предыдущий!)
Списки могут быть вложенными:
11. Введение
22. Начало работы
33. Примеры использования
4 * Простые
5 * Сложные
64. Заключение
Можно даже делать списки задач. Блок ниже создаёт HTML-флажки.
1Для отметки флажка используйте «x»
2- [ ] Первая задача
3- [ ] Вторая задача
4Этот флажок ниже будет отмечен
5- [x] Задача была завершена
Блоки кода ¶
Фрагменты исходного кода (обычно отмечаемые тегом <code>) выделяются просто:
каждая строка блока должна иметь отступ в четыре пробела либо в один символ табуляции.
1 Это код,
2 причём многострочный
Вы также можете делать дополнительные отступы, добавляя символы табуляции или пробелы:
1 my_array.each do |item|
2 puts item
3 end
Иногда бывает нужно вставить фрагмент кода прямо в строку текста, не выделяя код в блок. Для этого фрагменты кода нужно обрамлять символами «`»:
1Ваня даже не знал, что делает функция `go_to()`!
В GitHub Flavored Markdown для блоков кода можно использовать специальный синтаксис:
1```ruby
2def foobar
3 puts "Привет, мир!"
4end
5```
Во фрагменте, приведённом выше, отступ не требуется.
Кроме того, GitHub подсветит синтаксис языка, указанного после ```
Горизонтальный разделитель ¶
Разделители (<hr>) добавляются вставкой строки из трёх и более
(одинаковых) символов «*» или «-», с пробелами или без них:
1***
2---
3- - -
4****************
Ссылки ¶
Одной из сильных сторон Markdown можно смело считать то, как просто размечаются гиперссылки. Для создания ссылки укажите текст ссылки, заключив его в квадратные скобки, и сразу после — URL-адрес, заключенный в круглые
1[Ссылка!](http://test.com/)
Также для ссылки можно указать всплывающую подсказку (title), используя
кавычки внутри круглых скобок:
1[Ссылка!](http://test.com/ "Ссылка на Test.com")
Относительные пути тоже возможны:
1[Перейти к музыке](/music/).
Markdown также позволяет размечать ссылку в виде сноски:
1[Щёлкните эту ссылку][link1] для подробной информации!
2[Также посмотрите эту ссылку,][foobar] если хотите.
3
4[link1]: http://test.com/ "Круто!"
5[foobar]: http://foobar.biz/ "Нормально!"
Title также может быть в одинарных кавычках или круглых скобках, а также
отсутствовать вовсе. Ссылки на сноски могут быть в любом месте документа,
а идентификаторы могут быть какими угодно, лишь бы они были уникальными.
Существует также неявное именование, когда ссылка является идентификатором.
1[Это][] ссылка.
2
3[это]: http://thisisalink.com/
Правда, эта возможность не очень распространена.
Изображения ¶
Разметка изображений очень похожа на разметку ссылок. Нужно всего лишь добавить перед ссылкой восклицательный знак!
1
Изображения тоже могут быть оформлены как сноски.
1![Это альтернативный текст.][myimage]
2
3[myimage]: relative/urls/cool/image.jpg "Если нужна подсказка, её можно добавить"
Разное ¶
Автоссылки ¶
1Ссылка вида <http://testwebsite.com/> эквивалентна
2[http://testwebsite.com/](http://testwebsite.com/)
Автоссылки для адресов электронной почты ¶
1<foo@bar.com>
Экранирование символов ¶
1Я хочу напечатать *текст, заключённый в звёздочки*, но я не хочу,
2чтобы он был курсивным. Тогда я делаю так:
3\*Текст, заключённый в звёздочки\*
Клавиши на клавиатуре ¶
В GitHub Flavored Markdown для представления клавиш на клавиатуре
вы можете использовать тег <kbd>.
1Ваш компьютер завис? Попробуйте нажать
2<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd>
Таблицы ¶
Таблицы официально поддерживаются только в GitHub Flavored Markdown, да и синтаксис имеют не слишком удобный. Но если очень нужно, размечайте таблицы так:
1| Столбец 1 | Столбец 2 | Столбец 3 |
2| :----------- | :----------: | -----------: |
3| Выравнивание | Выравнивание | Выравнивание |
4| влево | по центру | вправо |
Или более компактно
1Столбец 1|Столбец 2|Столбец 3
2:--|:-:|--:
3Выглядит|это|страшновато...
Ну вот и всё!
За более подробной информацией обращайтесь к статье Джона Грубера о синтаксисе Markdown.
Также часто бывает полезной отличная «шпаргалка» по Markdown от Адама Притчарда.