Markdown - язык разметки и его синтаксис

Markdown (маркда́ун) — это язык упрощённой разметки, который был создан в 2004 году специально для написания наиболее читаемого и удобного для правки текста. При этом markdown может быть перекомпилирован в HTML. Файлы использующие markdown обозначаются как формат .md

Конечно маркдаун уступает по функционалу HTML5, но он активно используется в документациях, инструкциях, на гитхабе и много где ещё.

Синтаксис Markdown

У данного языка несложный синтаксис и его легко запомнить.

Заголовки

Чтобы в markdown задать заголовки (в html теги <h1>...</h1>, <h2>...</h2>, <h3>...</h3> и т.д.), для этого в начале строки ставят знак решётки # и через пробел пишут заголовок. Количество символов # задаёт уровень заголовка:

# Это заголовок H1
## Это заголовок H2
### Это заголовок H3
#### Это заголовок H4
##### Это заголовок H5
###### Это заголовок H6

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

• Так под заголовком H1 ставят подчёркивание из знаков равно ===
• для заголовков H2 - делают подчёркивание из дефисов ---

В обоих вариантах должно быть не меньше 3-х символов подряд (обычно подчёркивают весь текст заголовка, чтобы бросалось в глаза):

Это заголовок уровня H1
=======================


А вот это заголовок H2
----------------------

Параграфы

Чтобы выделить строку в отдельный параграф (теги <p> </p> в HTML), её отделяют пустыми строками (минимум одна пустая строка, но можно и больше ставить пустых строк, как вам удобно).

Списки в markdown

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

Для маркированного списка (в HTML теги <ul><li>...</li></ul>) в начале строки ставят символ звёздочки * и через пробел текст. Пример:

Домашние животные:
* Кошки
* Хомячки
* Тараканы

Получим вот такой результат:

Домашние животные:

• Кошки
• Хомячки
• Тараканы

Так же для обозначения списка вместо * в начале строки можно использовать символы + или -. Результат будет аналогичным.

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

Для нумерованного списка (в HTML <ol><li>...</li></ol>) всё ещё проще - просто ставим число с точкой в начале строки и через пробел пишем пункты списка.

Пример:

Список дел на сегодня:
1. Проснуться
2. Исполнить супружеский долг
3. Поужинать
4. Смотреть телевизор
5. Позавтракать
6. Исполнить супружеский долг
7. Уснуть

Работа c текстом в Markdown

В маркдауне можно текст задавать жирным, курсивом, зачёркнутым.

Выделение жирным

Для того чтобы выделить текст жирным (<strong>...</strong> в хтмл), нужно поставить по две звёздочки ** по краям выделяемого текста

Что то там, а **этот текст будет выделен жирным**, а вот этот уже нет.

Курсивом

По одной звёздочке по краям текста *текст курсивом* сделают его курсивным (наклонённым).

Жирный курсивом

По три звёздочки по краям текста ***текст жирным курсивом*** сделают его жирным курсивом.

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

Зачёркнутый текст это вот так вот по краям текста поставить по две тильды ~~ по краям зачёркнутого текста. Тильда на клавиатуре находится на клавише Ё, при включённой английской раскладке.

Внутри двойных тильд ~~этот текст будет зачёркнутым~~ а этот нет.

Цитата в Markdown

Чтобы написать цитату (тег <blockquote>...</blockquote> в html), для этого необходимо в начале строки поставить знак больше > после которого через пробел написать непосредственно текст цитаты:

> Этот текст будет цитатой

Ссылка в Markdown

Ссылка в маркдауне имеет следующий синтаксис: [Текст ссылки](url). При этом в параметр урла можно добавить тайтл (всплывающая подсказка при наведении курсора на ссылку).

Пример:

[Методы массивов JavaScript](https://v3c.ru/javascript/metods-array "Простые методы массивов")

Результат: Методы массивов JavaScript

Якорные ссылки

Для ссылки по якорю в документе применяется следующий синтаксис:

[Текст ссылки](#test)

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

<a id="test"></a> Текст для которого установлен якорь...

Вставка изображения

Для вставки изображения используется следующий синтаксис: ![Alt-атрибут](url-изображения "title-атрибут")

Пример:

![логотип гугла](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png "Google")

В результате выводит изображение логотипа гугла.

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

Полоса разделитель

Так же в маркдауне можно вставлять вот такую полосу:

---

В HTML это тег <hr>

В markdown для этого нужно в отдельной строке поставить как минимум три дефиза (тире) подряд ---, но можно и всю строку забить тирешкой. Главное чтобы эта строка отделялась пустыми строками от окружающего её текста, иначе, если помните выше из заголовков, мы можем получить заголовок H2.

Пример:

После этого текста будет стоять разделительная полоса.

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

Новый абзац с текстом после полосы

Вывод кода в markdown

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

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

Пример:

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

	function posylalka(name) {
		txt = `${name}, идика ты за хлебушком`;
		return txt;
	}
	posylalka('Donald');

Язык markdown не стоит на месте и постепенно тоже развивается. Двигать фрагмент кода на таб или 4-пробела не всегда удобно и поэтому в синтаксис ввели возможность делать это проще. Достаточно фрагмент кода выделить строками с тремя апострафами ```:

```
тут фрагмент кода
```

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

```javascript
optionsApp.keyId[2].forEach(el => {
    if (params['settings_' + el]) {
        document.querySelector('#item_' + el + '_on').checked = true;
        document.querySelector('.block_' + el).classList.add('active');
    }
});
```

Экранирование

Символы, которые обычно рассматриваются в Markdown как специальные, могут быть экранированы с помощью обратного слеша. Для этого перед каждым символом который может быть обработан маркдауном или кампилятором ставят обратный слеш \

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

\[Текст ссылки\]\(url\)