Базовый синтаксис Markdown: полное руководство с примерами

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

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

Заголовки

Markdown Headings

Заголовки организуют контент в логическую иерархию. Markdown поддерживает шесть уровней заголовков — для их создания перед текстом ставятся символы #.

# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6

В HTML это выглядит так:

<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>

Абзацы и переносы строк

Абзацы — самый простой элемент Markdown: просто пишите текст. Разделяйте абзацы пустой строкой.

This is the first paragraph.

This is the second paragraph.

Переносы строк

Здесь многие новички допускают ошибку. Однократное нажатие Enter не создаёт новую строку в большинстве рендереров Markdown. Для переноса строки нужно:

Завершить строку двумя или более пробелами (и нажать Enter)
Использовать HTML-тег

This is the first line.
This is the second line.

Or use HTML:<br>
This starts a new line.

Типичная ошибка

Простое нажатие Enter между двумя строками объединит их в один абзац при рендеринге:

Line one
Line two

Это отобразится как: «Line one Line two» — одна строка. Всегда используйте пустую строку для нового абзаца или завершающие пробелы для переноса внутри абзаца.

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

Markdown Text Formatting

Markdown позволяет легко выделять текст. Вот основные варианты форматирования:

Жирный шрифт

Оберните текст двойными звёздочками или двойными подчёркиваниями:

**This is bold text**
__This is also bold__

HTML-вывод: This is bold text

Курсив

Оберните текст одинарными звёздочками или одинарными подчёркиваниями:

*This is italic text*
_This is also italic_

HTML-вывод: This is italic text

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

Используйте тройные звёздочки для одновременного выделения:

***Bold and italic***
___Also bold and italic___
**_Or mix like this_**

HTML-вывод: Bold and italic

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

Используйте двойные тильды (это расширение GFM, но оно поддерживается практически везде):

~~This text is crossed out~~

HTML-вывод: <del>This text is crossed out</del>

Типичная ошибка

Использование подчёркиваний внутри слова работает ненадёжно. Для выделения в середине слова используйте звёздочки:

✅ This is**very**important
❌ This is__very__important

Цитаты

Цитаты создаются с помощью символа >. Они часто используются для цитирования источников, выделения важных замечаний или ключевой информации.

> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber

HTML-вывод:

<blockquote>
  <p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
  — John Gruber</p>
</blockquote>

Многоабзацные цитаты

Добавьте > на пустой строке между абзацами:

> First paragraph of the quote.
>
> Second paragraph of the quote.

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

Используйте >> для вложенности:

> This is the outer quote.
>
>> This is a nested quote inside it.

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

Внутри цитат можно использовать другие элементы форматирования Markdown:

> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.

Списки

Markdown Lists

Списки — один из самых часто используемых элементов Markdown. Существует три типа: маркированные, нумерованные и списки задач.

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

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

- First item
- Second item
- Third item

HTML-вывод:

<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
</ul>

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

Используйте числа с точкой. Фактические номера не имеют значения — Markdown автоматически их пронумерует:

1. First step
2. Second step
3. Third step

Интересно, что следующий вариант даёт тот же результат:

1. First step
1. Second step
1. Third step

Оба варианта отображаются как корректно пронумерованный список 1-2-3. Тем не менее лучшая практика — использовать последовательные номера для удобства чтения исходного файла.

Вложенные списки

Используйте отступ в два или четыре пробела для создания подсписков:

1. Main item
   - Sub-item A
   - Sub-item B
     - Sub-sub-item
2. Another main item

Списки задач

Списки задач (функция GFM) используют - [ ] для невыполненных и - [x] для выполненных пунктов:

- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish

Типичная ошибка

Пропуск пустой строки перед списком, если он идёт после абзаца. Некоторые парсеры требуют её наличия:

✅ Here is my list:

- Item one
- Item two

❌ Here is my list:
- Item one
- Item two

Код

Markdown Code

Отображение кода — одна из сильнейших сторон Markdown, и важно делать это правильно для удобства чтения.

Строчный код

Оберните код в одинарные обратные кавычки для строчного отображения:

Use the `print()` function to output text.

HTML-вывод: Use the <code>print()</code> function to output text.

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

``There is a literal `backtick` here.``

Блоки кода

Для многострочного кода используйте тройные обратные кавычки (огороженные блоки кода) с необязательным идентификатором языка для подсветки синтаксиса:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Идентификатор языка (javascript, python, html, css, bash и др.) включает подсветку синтаксиса в большинстве рендереров. Всегда указывайте его — это значительно улучшает читаемость.

Блоки кода с отступами

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

    function add(a, b) {
      return a + b;
    }

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

Ссылки

Ссылки необходимы для связывания контента. Markdown поддерживает несколько форматов ссылок.

Встроенные ссылки

Самый распространённый формат — текст в квадратных скобках, URL в круглых:

[Visit Example](https://example.com)

HTML-вывод: <a href="https://example.com">Visit Example</a>

Ссылки с заголовками

Добавьте заголовок в кавычках после URL (отображается как всплывающая подсказка при наведении):

[Visit Example](https://example.com "Example Website")

Ссылки-сноски

Для более чистого исходного текста при большом количестве ссылок используйте ссылки-сноски:

I use [Google][1] and [GitHub][2] daily.

[1]: https://google.com "Google"
[2]: https://github.com "GitHub"

Это позволяет не загромождать абзацы и сгруппировать все URL внизу — особенно удобно в длинных документах.

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

Оберните URL или email в угловые скобки для автоматического создания ссылки:

<https://example.com>
<contact@example.com>

Большинство современных рендереров (например, GitHub) автоматически превращают URL в ссылки и без угловых скобок, но их использование гарантирует совместимость.

Типичная ошибка

Пробелы в URL нужно кодировать. Используйте %20 вместо пробелов:

✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)

Изображения

Markdown Links and Images

Изображения используют тот же синтаксис, что и ссылки, но с восклицательным знаком ! впереди:

![Alt text describing the image](/path/to/image.webp)

HTML-вывод: <img src="/path/to/image.webp" alt="Alt text describing the image">

Изображения с заголовками

![A sunset over the ocean](/images/sunset.webp "Beautiful sunset")

Изображения-ссылки

Комбинируйте синтаксис ссылки и изображения, чтобы сделать картинку кликабельной:

[![Alt text](/images/photo.webp)](https://example.com)

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

Горизонтальная линия (тематический разделитель) визуально разделяет секции. Используйте три или более дефиса, звёздочки или подчёркивания:

---
***
___

Все три варианта создают одинаковый HTML: <hr>

Лучшая практика: используйте --- единообразно и всегда добавляйте пустые строки до и после:

Content above the rule.

---

Content below the rule.

Экранирование символов

Что если нужно отобразить буквальную звёздочку или символ решётки, не вызывая форматирование Markdown? Поставьте обратный слеш \ перед символом:

\* This is not italic \*
\# This is not a heading
\- This is not a list item

Полный список символов, которые можно экранировать:

\   Backslash
`   Backtick
*   Asterisk
_   Underscore
{}  Curly braces
[]  Square brackets
()  Parentheses
#   Hash
+   Plus sign
-   Hyphen
.   Dot
!   Exclamation mark
|   Pipe

Краткая шпаргалка

Все элементы базового синтаксиса в одной таблице для быстрого поиска:

Element         Syntax              HTML
--------------  ------------------  -----------
Heading 1       # Text              <h1>
Heading 2       ## Text             <h2>
Heading 3       ### Text            <h3>
Bold            **text**            <strong>
Italic          *text*              <em>
Bold + Italic   ***text***          <strong><em>
Strikethrough   ~~text~~            <del>
Blockquote      > text              <blockquote>
Ordered list    1. item             <ol><li>
Unordered list  - item              <ul><li>
Inline code     `code`              <code>
Link            [text](url)         <a href>
Image           ![alt](src)         <img>
Horizontal rule ---                 <hr>
Line break      spaces + Enter      <br>

Применяйте на практике

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

Практикуйтесь: Создайте файл notes.md и попробуйте каждый элемент синтаксиса. Чем больше вы пишете, тем естественнее это становится.
Используйте предпросмотр: Встроенный предпросмотр Markdown в VS Code (Ctrl+Shift+V / Cmd+Shift+V) позволяет видеть результат рендеринга в реальном времени.
Конвертируйте и делитесь: Когда ваш Markdown-документ готов, преобразуйте его в профессиональный вывод — конвертируйте Markdown в HTML для веб-публикации, создайте PDF для документов, готовых к печати, или экспортируйте в Word для совместного редактирования.
Изучайте дальше: Освоив базовый синтаксис, переходите к нашему руководству по расширенному синтаксису Markdown — таблицы, сноски, списки определений и многое другое. Совсем новичок в Markdown? Начните с Что такое Markdown для общей картины.

Красота Markdown в том, что эти базовые элементы покрывают подавляющее большинство всего, что вам когда-либо понадобится написать. Освойте их один раз — и будете использовать повсюду: от GitHub до Notion, от документации до статей в блоге вроде этой.

Базовый синтаксис Markdown: полное руководство с примерами

Заголовки

Рекомендации по использованию заголовков

Абзацы и переносы строк

Переносы строк

Типичная ошибка

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

Жирный шрифт

Курсив

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

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

Типичная ошибка

Цитаты

Многоабзацные цитаты

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

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

Списки

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

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

Вложенные списки

Списки задач

Типичная ошибка

Код

Строчный код

Блоки кода

Блоки кода с отступами

Ссылки

Встроенные ссылки

Ссылки с заголовками

Ссылки-сноски

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

Типичная ошибка

Изображения

Изображения с заголовками

Изображения-ссылки

Рекомендации по alt-тексту

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

Экранирование символов

Краткая шпаргалка

Применяйте на практике