Модуль 01 — Что такое Markdown и форматирование текста

Откуда взялся Markdown, где он встречается и как размечать обычный текст

Прогресс курса Модуль 1 из 5

Что вы освоите в этом модуле

01

Что такое Markdown

Markdown — облегчённый язык разметки. Документ остаётся обычным текстовым файлом, который удобно читать и без обработки, а специальная программа превращает его в HTML: заголовки, списки, ссылки, таблицы, код.

Язык придумал Джон Грубер в 2004 году. Исходное описание было неточным, и разные программы толковали спорные места по-своему. В 2014 году появилась спецификация CommonMark — строгие правила, по которым один и тот же текст везде даёт один и тот же результат.

Диалекты

  • CommonMark — базовый стандарт: заголовки, абзацы, выделение, списки, ссылки, изображения, код, цитаты
  • GFM (GitHub Flavored Markdown) — CommonMark плюс таблицы, списки задач, зачёркивание и автоссылки; его понимает большинство git-хостингов
  • Расширения платформ — сноски, диаграммы, вики-ссылки: зависят от конкретного сервиса и работают не везде

Где встречается

  • README.md в репозиториях GitFlic, GitLab, GitHub — первая страница проекта
  • Документация: вики, генераторы сайтов документации, базы знаний
  • Заметки и личные базы знаний: Obsidian, Joplin
  • Сообщения и комментарии: задачи в трекерах, запросы на слияние, чаты
  • Системы обучения и CMS: многие редакторы принимают Markdown как формат ввода
Главное достоинство Markdown — текст живёт в git вместе с кодом. Изменения документации видны в истории построчно, их можно обсуждать в запросе на слияние так же, как изменения программы. С файлами .docx так не получится.
02

Рабочее место: файл .md и предпросмотр

Для работы достаточно любого текстового редактора. В курсе используем VS Code: в нём встроенный предпросмотр Markdown, ничего устанавливать не нужно.

Порядок действий

  • Создайте файл с расширением .md, кодировка — UTF-8
  • Ctrl+Shift+V — открыть предпросмотр во вкладке
  • Ctrl+K, затем V — предпросмотр рядом с исходником, обновляется при наборе
  • Файл README.md в корне репозитория git-хостинг показывает на главной странице проекта автоматически
Предпросмотр VS Code близок к GFM, но не совпадает с каждой платформой. Если документ будет жить на конкретном сервисе, финальную проверку делайте в его предпросмотре.
03

Заголовки

Заголовок — строка, которая начинается с символов #. Число решёток — уровень от 1 до 6. После решёток обязателен пробел.

Исходник
# Руководство пользователя

## Установка

### Требования к системе

#Без пробела — это не заголовок
Результат

Руководство пользователя

Установка

Требования к системе

#Без пробела — это не заголовок

Правила хорошего тона

  • Один заголовок первого уровня на документ — его название
  • Уровни не перескакивают: после ## идёт ###, а не ####
  • Пустая строка до и после заголовка — так исходник легче читать, а часть программ иначе не распознаёт заголовок
  • Заголовки подчёркиванием (=== и --- на следующей строке) тоже допустимы, но в новых документах их не используют
04

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

Абзацы разделяются пустой строкой. Одиночный перенос строки внутри абзаца превращается в пробел: строки склеиваются. Это частая неожиданность у новичков.

Исходник
Первая строка
продолжение того же абзаца.

Новый абзац после пустой строки.

Строка с принудительным переносом\
следующая строка.
Результат

Первая строка продолжение того же абзаца.

Новый абзац после пустой строки.

Строка с принудительным переносом
следующая строка.

Принудительный перенос

  • Обратная косая черта \ в конце строки — видна в исходнике, рекомендуемый способ
  • Два пробела в конце строки — работает, но пробелы не видны, редакторы и линтеры их часто удаляют
  • Если нужен перенос, чаще правильнее новый абзац или список
05

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

Исходник
*Курсив* и _тоже курсив_

**Жирный** и __тоже жирный__

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

~~Зачёркнутый~~ (GFM)

имя_файла_без_курсива.md
Результат

Курсив и тоже курсив

Жирный и тоже жирный

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

Зачёркнутый (GFM)

имя_файла_без_курсива.md

Тонкости

  • Выберите один вариант — * или _ — и придерживайтесь его во всём документе
  • Подчёркивания внутри слова не дают курсива: имя_файла_без_курсива остаётся как есть. Звёздочки внутри слова — дают
  • Между символом выделения и текстом не должно быть пробела: ** жирный ** не сработает
  • Подчёркнутого текста в Markdown нет — подчёркивание в вебе выглядит как ссылка
06

Цитаты и горизонтальная линия

Исходник
> Цитата может состоять
> из нескольких строк.
>
> > И содержать вложенную цитату.

Текст перед линией.

---

Текст после линии.
Результат

Цитата может состоять из нескольких строк.

И содержать вложенную цитату.

Текст перед линией.

Текст после линии.

Перед --- обязательна пустая строка. Если написать --- сразу под строкой текста, эта строка станет заголовком второго уровня. Надёжнее использовать *** или ___ — у них такого побочного эффекта нет.
07

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

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

Исходник
\# Это не заголовок

Цена 5\*3 = 15, а не курсив.

1986\. Год, а не пункт списка.

Путь C:\\Users\\student
Результат

# Это не заголовок

Цена 5*3 = 15, а не курсив.

1986. Год, а не пункт списка.

Путь C:\Users\student

Что экранируют чаще всего

  • \* \_ — звёздочка и подчёркивание вне выделения
  • \# — решётка в начале строки
  • 1986\. — число с точкой в начале строки, иначе получится нумерованный список
  • \\ — сама обратная косая черта
  • \| — вертикальная черта внутри таблицы (модуль 03)

Запомните главное

  • Абзацы разделяет пустая строка; одиночный перенос склеивает строки
  • После # в заголовке нужен пробел, уровни не перескакивают
  • Базовые правила задаёт CommonMark; таблицы и списки задач — расширения GFM
  • Перед --- всегда пустая строка, иначе получится заголовок
  • Символ разметки как обычный текст — через \
Практические задания — на учебном портале. Задания, критерии оценивания, сдача работ и оценки преподавателя — в курсе на portal.nevabit.ru. Учётную запись выдаёт преподаватель.
Все модули Модуль 02: Списки и ссылки