Язык разметки Markdown

Кратко

Markdown — удобочитаемый язык разметки, который прозрачно конвертируется в HTML. Его можно открывать и изменять в любом редакторе текста. Широко используется для написания документаций и README-файлов.

Пример

Вы можете встретить Markdown в .md или .markdown файлах. Давайте посмотрим на пример одного из таких:

# Дока

Дока — это **добрая** энциклопедия для веб-разработчиков.
Вы можете [открыть её](https://doka.guide) в своём браузере.

## Преимущества

- Понятный материал
- Нескучные объяснения
- Удобный поиск

Он содержит базовые элементы, которые можно найти почти в любом README.md:

• Заголовок первого уровня для названия
• Выделение жирным шрифтом важных частей в описании
• Ссылка на сайт с понятным текстом
• Заголовок второго уровня для подпунктов
• Маркированный список для перечисления преимуществ

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

Синтаксис

Параграф

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

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

• Добавить два (или больше) пробелов в конце строки <пробел><пробел>
• Добавить обратную косую черту в конце строки \
• Добавить HTML тег переноса строки <br>

Привет,
мир!

Привет,<пробел><пробел>
пробел!

Привет,\
косая черта!

Привет,<br>
тег бр-р-р!

Заголовки

Markdown предлагает два стиля написания заголовков: через решётки (#) и через подчёркивания (====). Можно использовать до 6 уровней заголовков, но подчёркивания позволяют создавать только первые два (<h1> и <h2>).

Решётки (Atx-style)

Для того, чтобы выделить заголовок, необходимо поставить от 1 до 6 решёток (#) и пробел в самом начале строки. Уровень заголовка зависит только от количества решёток.

# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
#### Заголовок 4 уровня
##### Заголовок 5 уровня
###### Заголовок 6 уровня

Подчёркивания (Setext-style)

«Подчёркивание» параграфа знаками равно (=) или дефисами (-) делает его заголовком первого или второго уровня соответственно. Уровень заголовка зависит только от типа «чёрточек», их количество значения не имеет.

Между текстом и «подчёркиванием» не должно быть пустых строк.

Заголовок 1 уровня
==================

Заголовок 2 уровня
------------------

Заголовок, который подчеркнули одним символом
-

Заголовок второго
уровня из нескольких
строчек текста
------------------

Списки

Маркированные

Для создания маркированных (ненумерованных) списков, перед каждым пунктом нужно поставить минус (-), плюс (+) или звёздочку (*). Маркер и текст пункта необходимо разделять пробелом.

- Помидор
- Огурец

+ Бублик
+ Ватрушка

* Молоко
* Кефир

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

- Помидор
+ Бублик
* Молоко

Упорядоченные

Если в качестве маркеров использовать цифры c точкой на конце (1., 2. и т. д.), то мы получим упорядоченный (нумерованный) список.

1. Хлеб
2. Молоко
3. Помидоры

Номера пунктов в итоговой разметке будут идти по порядку (1, 2, 3), даже если в Markdown будут стоять 1., 4., 9.. Такая особенность позволяет нам использовать «ленивую нумерацию», когда перед каждым пунктом ставится одно и то же число.

1. Хлеб
1. Молоко
1. Помидоры

Число перед первым пунктом показывает с чего нужно начинать нумеровать элементы списка, поэтому если в Markdown поставить 99., 1., 2., то в итоговой разметки пункты будут стоять под номерами 99, 100, 101.

99. Хлеб
1. Молоко
2. Помидоры

Вложенность

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

+ Хлеб
+ Молочные продукты
  1. Кефир
  2. Ряженка

1. Молоко
2. Хлебобулочные изделия
    + Бублик
    + Ватрушка

Количество пробелов, которое нужно использовать, чтобы вложить один список в другой, может варьироваться. Оно зависит от количества символов в родительском маркере (L):

• + — 1 символ (L = 1)
• 1. — 2 символа (L = 2)
• 99. — 3 символа (L = 3)

Перед вложенным списком нужно поставить от L + 1 до L + 4 пробелов.

Цитаты

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

> Одна треугольная скобка
превращает в цитату несколько строк,
идущих друг за другом.

> # Цитаты великих людей
> Ваша работа заполнит большую часть жизни и единственный способ быть
> полностью довольным — делать то, что по-вашему является великим делом.
> И единственный способ делать великие дела — любить то, что вы делаете.
>
> *— Стив Джобс, Речь в Стенфорде*

> Первая, родительская цитата
> > А это уже вторая,\
> > дочерняя цитата

Исходный код

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

• Обернуть код одной-двумя парами бэктиков (`код`)
• Обернуть код тремя и более парами бэктиков (```код```)
• Поставить таб или 4 пробела перед каждой строчкой кода

Одна-две пары бэктиков

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

Функция `alert()`
вызывает диалоговое окно.

Сумму двух переменных
можно вывести так:
``let a = 1;
let b = 2;
alert(a + b);``

Три и более пар бэктиков

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

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

Функция ```console.log()```
выводит текст в консоль.

Сумму двух переменных
можно вывести так:
```javascript
let a = 1;
let b = 2;

console.log(a + b);
```

Отступ

Другой способ выделить код — поставить перед ним таб или 4 пробела. Исходный код необходимо отделять пустой строкой от предыдущего блока.

Метод ```.toString()```
превращает числа в строку.

Его можно использовать так:

    let a = 1;
    let b = 2;

    (a + b).toString();

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

Если обернуть текст звёздочками (*) или нижними подчёркиваниями (_), то он станет жирным или курсивным. Оба символа работают одинаково, стиль выделения зависит только от их количества:

• Одна пара * или _ сделает текст *курсивным*
• Две пары * или _ сделают текст **жирным**
• Три пары * или _ применят ***оба стиля***

Обычный текст

*Курсивный текст*<br>
_Другой курсивный текст_

**Жирный текст**<br>
__Другой жирный текст__

***Оба стиля***<br>
___Оба стиля___<br>

Для экранирования служебных символов Markdown нужно поставить обратную косую черту перед каждым из них (\*, \_, \*\*).

**_Оба стиля из \* и \__**<br>
__*Оба стиля из \* и \_*__

\*\*Экранирование звёзд\*\*<br>
\_\_\_Экранирование подчёркиваний\_\_\_

Ссылки

Markdown предлагает 3 стиля разметки ссылок: строчный, справочный и автоматический.

Строчные

Для вставки ссылки в строчном стиле необходимо воспользоваться следующей конструкцией [Текст ссылки]​(URL). Есть возможность добавить подсказку, для этого нужно после URL дописать текст в кавычках: [Текст ссылки]​(URL "Подсказка").

Привет, [Дока](https://doka.guide "Энциклопедия про web-dev")!

Справочные

Для вставки ссылки в справочном стиле нужно написать [Текст ссылки]​[Ключ] в том месте, где вы хотите её поместить, а где-нибудь выше или ниже добавить сноску [Ключ]: URL "Подсказка".

У [Доки][1] есть свой [репозиторий][repo].


[1]: https://doka.guide "Энциклопедия про web-dev"
[repo]: https://github.com/doka-guide "Репозиторий Доки"

Автоматические

Markdown позволяет использовать упрощённый вариант для вставки ссылок, для этого нужно просто обернуть URI треугольными скобками (<URI>).

Можно вставлять email адреса (<hi@doka.guide>), тогда мы автоматически получим ссылку типа mailto:.

Заходите на <https://doka.guide>
или присылайте нам письма на <hi@doka.guide>

Изображения

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

Строчные

Для вставки изображения в строчном стиле необходимо воспользоваться конструкцией !⁠[Alt текст]​(URL картинки). При желании можно добавить подсказку: !⁠[Alt текст]​(URL картинки "Подсказка").

![Одна собака](dog.png "Собака смотрит влево")

Справочные

Для вставки изображения в справочном стиле нужно написать !⁠[Alt текст]​[Ключ] в том месте, где вы хотите его поместить, а где-нибудь выше или ниже описать картинку по ключу [Ключ]: URL картинки "Подсказка".

![Одна собака][1]

[1]: dog.png "Собака смотрит влево"

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

Для разделения смысловых блоков можно поставить горизонтальную черту (<hr>). Чтобы это сделать, необходимо поставить на одной строке три (или более) дефиса (-), подчёркивания (_) или звёздочки (*). Они не обязательно должны идти друг за другом, между ними могут быть табы или пробелы.

---

***

_	_	_

*  * *  *

------------

Стандартизация

У Markdown есть оригинальная спецификация от одного из создателей языка — Джона Грубера. К сожалению, она не всегда однозначно описывает синтаксис, из-за чего многие конверторы Markdown работают по-разному. Чтобы исправить эту ситуацию, группа ~~разработчиков~~ «поклонников Markdown» создала CommonMark — спецификацию, которая описывает многие частные случаи, и эталонную реализацию парсера Markdown на js.

Диалекты

Простой Markdown не всегда подходит для тех или иных проектов, поэтому существуют спецификации, которые расширяют или сужают его.

GitHub Flavored Markdown

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

Таблицы

Колонки таблицы размечаются с помощью вертикальных черт (|), а заголовок отделяется дефисами (-).

| Место | Участник | Рейтинг |
|-------|----------|---------|
| 1     | Саша     | 118     |
| 2     | Юля      | 92      |
| 3     | Даниил   | 36      |

Можно поставить двоеточие (:) рядом с дефисами для выравнивания текста:

• по левой стороне (|:----|)
• по центру (|:----:|)
• по правой стороне (|----:|)

| Место | Участник | Рейтинг |
|------:|:--------:|:--------|
| 1     | Саша     | 118     |
| 2     | Юля      | 92      |
| 3     | Даниил   | 36      |

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

|Место|Участник|Рейтинг|
|-:|:-:|:-|
|1|Саша|118|
|2|Юля|92|
|3|Даниил|36|

Список задач

Для создания списка задач используется синтаксис маркированного списка, но с добавлением чекбоксов ([ ] или [x]) после маркеров.

- [x] Выйти на улицу
- [x] Зайти в магазин
- [ ] Купить продукты
  - [x] Молоко
  - [x] Хлеб
  - [ ] Помидоры
- [ ] Вернуться домой

Зачёркивание

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

~~Привет, Вова!~~\
Здравствуйте, Владимир!

Stack Exchange Additions

Популярный среди разработчиков сайт Stack Overflow и все остальные сайты, входящие в группу Stack Exchange, используют в редакторе вопросов Markdown, основанный на спецификации CommonMark. Он расширен следующим образом:

Теги

Ссылка на вопросы по определённому тегу пишется просто в квадратных скобках с префиксом tag:

Все вопросы по тегу [tag:javascript] на нашем сайте.

Спойлер

Если после символа цитирования поставить восклицательный знак (>!), то цитата выведется свёрнутой, и развернуть её пользователь сможет, кликнув по ней.

В конце пятого эпизода выясняется, что
>! он его отец.

Другие отличия

Stack Exchange использует тот же синтаксис для создания таблиц, что и GitHub Flavored Markdown, а также некоторые HTML-теги из числа безопасных.

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

Мессенджеры

Многие мессенджеры, например Telegram или Discord, используют упрощённую версию Markdown. Там отсутствует разметка заголовков, списков и цитат, но поддерживается расширенный синтаксис выделения текста: жирный шрифт, курсив, зачёркивания, ссылки, разметка исходного кода.