Markdown за 5 минут
Вы наверняка уже использовали Markdown, даже не подозревая об этом. Когда-нибудь набирали **жирный** в сообщении Slack? Писали README на GitHub? Форматировали пост на Reddit? Это и есть Markdown.
Markdown — это лёгкий способ форматирования обычного текста с помощью простых символов. Вместо нажатия кнопок на панели инструментов для жирного шрифта, курсива, заголовков и списков вы набираете несколько символов, обозначающих нужное форматирование. Он был создан в 2004 году Джоном Грубером и Аароном Шварцем и с тех пор стал стандартным языком форматирования для разработчиков, писателей и всех, кто работает с текстом в интернете.
Зачем нужен Markdown
До Markdown форматирование текста для веба означало написание HTML. Чтобы сделать слово жирным, нужно было набрать <strong>жирный</strong>. Чтобы создать список — <ul><li>элемент</li></ul>. HTML мощный, но многословный и плохо читается в исходном виде.
Markdown решает эту проблему, предоставляя человекочитаемую сокращённую запись. Исходный текст легко читается даже до обработки. Отформатированный результат чист и профессионален. Вы получаете лучшее из обоих миров: читаемый исходный текст и красивый вывод.
Знаете ли вы? Философия дизайна Markdown заключается в том, что исходный текст должен быть «пригодным для публикации как есть, как обычный текст, не выглядя так, будто он размечен тегами или инструкциями форматирования». Вот почему синтаксис Markdown использует символы, которые визуально намекают на создаваемое ими форматирование.
Основной синтаксис
Вот всё, что нужно знать, чтобы начать продуктивно использовать Markdown.
Заголовки
Используйте символы решётки (#) для создания заголовков. Чем больше решёток, тем меньше заголовок.
# Заголовок 1 (самый крупный)
## Заголовок 2
### Заголовок 3
#### Заголовок 4
Жирный и курсив
Оберните текст звёздочками или подчёркиваниями:
**жирный текст**
*курсивный текст*
***жирный и курсивный***
Списки
Неупорядоченные списки используют дефисы, звёздочки или знаки плюс. Упорядоченные — числа.
- Первый элемент
- Второй элемент
- Третий элемент
1. Первый шаг
2. Второй шаг
3. Третий шаг
Ссылки
Квадратные скобки для текста, круглые — для URL:
[Нажмите здесь](https://example.com)
Изображения
Как ссылки, но с восклицательным знаком перед ними:
Цитаты
Используйте знак «больше»:
> Это цитата. Она будет отображаться с отступом и другим стилем.
Код
Обратные кавычки для встроенного кода, тройные обратные кавычки для блоков кода:
Используйте функцию `print()` для вывода текста.
Для многострочных блоков кода используйте тройные обратные кавычки с необязательным идентификатором языка:
```python
def hello():
print("Hello, world!")
```
Горизонтальные линии
Три или более дефисов, звёздочек или подчёркиваний:
---
Таблицы
Используйте вертикальные черты и дефисы:
| Имя | Роль | Местоположение |
| --- | --- | --- |
| Алиса | Разработчик | Берлин |
| Боб | Дизайнер | Лондон |
Где используется Markdown
Markdown повсюду:
Разработка программного обеспечения
- GitHub, GitLab, Bitbucket: README, задачи, запросы на слияние и документация — всё пишется на Markdown.
- Stack Overflow: Вопросы и ответы используют форматирование Markdown.
- Документация кода: Многие генераторы документации (Docusaurus, MkDocs, Jekyll) используют Markdown как исходный формат.
Коммуникация
- Slack: Поддерживает подмножество Markdown для форматирования сообщений.
- Discord: Использует Markdown для жирного шрифта, курсива, блоков кода и многого другого.
- Reddit: Посты и комментарии форматируются с помощью Markdown.
Писательство и публикация
- Блоги: Многие генераторы статических сайтов используют файлы Markdown как источники контента.
- Книги: Некоторые издательские инструменты принимают рукописи в Markdown.
- Заметки: Такие приложения, как Obsidian, Notion, Bear и Typora, построены вокруг Markdown.
Документация
- Техническая документация: API-документация, руководства пользователя и вики обычно используют Markdown.
- Внутренние базы знаний: Многие команды используют вики на основе Markdown.
Совет Вы можете предварительно просмотреть и попрактиковаться в Markdown прямо сейчас, бесплатно, в браузере: Написать на Markdown. Видите отформатированный результат в реальном времени по мере ввода.
Разновидности Markdown
Стоит знать: существуют различные «разновидности» Markdown. Базовый синтаксис одинаков везде, но некоторые платформы добавляют расширения:
| Разновидность | Дополнительные возможности | Где используется |
|---|---|---|
| CommonMark | Строгая спецификация | Общий стандарт |
| GitHub Flavored Markdown (GFM) | Списки задач, таблицы, зачёркивание, автоссылки | GitHub |
| MultiMarkdown | Сноски, цитирования, метаданные | Академическое письмо |
| R Markdown | Встроенный код R, анализ данных | Наука о данных |
Различия в основном касаются продвинутых функций. Основы (заголовки, жирный, курсив, списки, ссылки, изображения, код) работают одинаково везде.
Типичные ошибки
Отсутствие пустых строк
Markdown требует пустой строки перед и после многих элементов. Заголовку нужна пустая строка перед ним. Списку нужна пустая строка перед и после. Пропуск пустых строк — самая распространённая причина проблем с отображением.
Несогласованные маркеры списков
Смешивание -, * и + в одном списке может привести к неожиданному отображению. Выберите один вариант и придерживайтесь его.
Пробелы после символов
Некоторые процессоры Markdown требуют пробела после # в заголовках и после - в списках. Всегда добавляйте пробел для надёжности.
# Правильный заголовок
#Неправильный заголовок
- Правильный элемент списка
-Неправильный элемент списка
Предупреждение Markdown не покрывает все потребности в форматировании. Если вам нужны сложные макеты, цветной текст, точная типографика или документы, готовые к печати, вам может понадобиться HTML, LaTeX или текстовый редактор. Markdown лучше всего подходит для структурированного, текстового контента.
Почему стоит изучить Markdown
На изучение Markdown уходит пять минут, а экономия времени — на долгие годы. Освоив его, вы сможете:
- Писать документацию, которая красиво отображается на GitHub
- Форматировать сообщения в Slack и Discord, не прикасаясь к мыши
- Делать структурированные заметки, переносимые между приложениями
- Создавать посты для блога и веб-контент из обычных текстовых файлов
- Совместно работать над текстовыми документами без проблем совместимости форматов
Соотношение затрат к отдаче — одно из лучших во всём мире технологий.
Начните писать на Markdown прямо сейчас:
Бесплатно, в браузере, с предварительным просмотром в реальном времени по мере ввода.