Markdown таблица

Таблица: минимальный пример#

| Тема | Статус | Задач решено |
| --- | --- | --- |
| Дроби | готово | 24 |
| Проценты | в работе | 7 |

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

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

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

Выравнивание столбцов#

Выравнивание задаётся двоеточиями в строке-разделителе:

| Тема | Дата | Часы |
| :--- | :---: | ---: |
| Степени | 12.09 | 3 |
| Уравнения | 5.10 | 12 |

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

Перенести строку внутри ячейки нельзя: любая таблица — одна строка
исходника на одну строку таблицы. Если текст длинный, ставят <br> — но
он сработает только там, где разрешён HTML внутри markdown (GitHub его
разрешает, строгие движки — нет), — или выносят подробности под таблицу. Вертикальная черта внутри ячейки
экранируется обратным слешем — \|, иначе она разорвёт ячейку надвое.

Таблицы удобны для конспектов, где у каждой записи одинаковые поля: правило
слева, пример справа. Например, конспект по теме формулы сокращённого
умножения укладывается в две
колонки — формула и типичная ошибка.

Заголовки#

Заголовок — решётки в начале строки, пробел, текст. Одна решётка — верхний
уровень (# Заголовок), две — второй уровень, и так до шести. Пробел после
решёток обязателен: без него строка останется обычным текстом.

## Раздел

### Подраздел

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

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

Списки#

- первый пункт
- второй пункт
  - вложенный пункт

1. нумерованный пункт
2. ещё один

Маркированный список начинается с дефиса, звёздочки или плюса — все три
дают одинаковый результат, но внутри одного документа стоит держаться
одного знака. Нумерованный — число, точка, пробел. Вложенность задаётся
отступом в два-четыре пробела; табуляция работает не везде, поэтому
надёжнее пробелы.

Перед списком нужна пустая строка. Без неё абзац и список слипаются в один
текст с дефисами — самая частая жалоба на «сломанную разметку».

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

Ссылки и картинки#

Текст со [ссылкой](https://commonmark.org/) внутри.

![Схема решения](shema.png)

Ссылка — текст в квадратных скобках, адрес в круглых. Картинка — то же
самое с восклицательным знаком впереди; текст в скобках становится
подписью для тех, кто не видит изображение. Если в адресе есть пробелы,
адрес берут в угловые скобки или заменяют пробел на %20.

Пропущенный восклицательный знак — причина ситуации «вместо картинки
появилась ссылка». Разметка при этом верная, просто описывает другое.

Код, цитаты и списки задач#

Код внутри строки заключают в одинарные обратные кавычки. Блок кода —
три обратные кавычки до и после, а после первых трёх пишут язык, чтобы
подсветка была верной:

```python
print("привет")
```

Цитата — знак «больше» в начале строки:

> Цитата занимает
> две строки.

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

Список задач — расширение, знакомое по GitHub:

- [ ] выучить свойства степеней
- [x] решить пять уравнений

Скобки с пробелом внутри дают пустой флажок, скобки с буквой x —
отмеченный. Пробел между скобками обязателен: запись без пробела останется
обычным пунктом списка.

Что ещё стоит помнить#

Одиночный перевод строки внутри абзаца при отрисовке пропадает — текст
склеивается в один абзац. Чтобы получить перенос, ставят два пробела в
конце строки или обратный слеш.

Курсив — текст между одинарными звёздочками, полужирный — между двойными.
Звёздочку, решётку или подчёркивание, которые должны остаться символами,
экранируют обратным слешем.

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

План по этапам

1. Шаг 1 — таблица из трёх строкСобрать шапку, разделитель и две строки данных; проверить совпадение числа столбцов.
2. Шаг 2 — выравниваниеДобавить двоеточия в разделитель и выровнять числовой столбец вправо.
3. Шаг 3 — остальная разметкаНаписать страницу с заголовками, списком, ссылкой, картинкой и блоком кода.
4. Шаг 4 — ловушкиПроверить пустые строки перед списками и таблицами, экранирование черты и звёздочки.
5. Шаг 5 — предпросмотрСверить исходник с отрисовкой в редакторе и исправить места, где разметка сработала не так.

Проверь себя

Источники

• Markdown GuideСправочник по синтаксису и расширениям с примерами
  бесплатно
• CommonMarkСпецификация базового синтаксиса и песочница для проверки разметки
  бесплатно

Было полезно?

Да Нет