README выглядит идеально в локальном редакторе с плагином предпросмотра, а после пуша на GitHub таблица разваливается: часть строк съезжает в одну колонку, часть текста вылезает за пределы ячеек, а где-то посреди таблицы появляется лишняя пустая строка. Причины почти всегда сводятся к паре мелких синтаксических деталей, которые разные рендереры Markdown обрабатывают немного по-разному.
Минимальный корректный синтаксис
| Колонка 1 | Колонка 2 |
| --- | --- |
| значение | значение |Три обязательных элемента: строка заголовков, разделительная строка с дефисами, и строки данных, все с вертикальной чертой по краям и между колонками. Пропуск разделительной строки это самая частая причина, по которой GitHub вообще отказывается рендерить таблицу и показывает сырой текст с палочками как есть.
Проблема первая: вертикальная черта внутри значения
| Команда | Описание |
| --- | --- |
| grep -o "a|b" | ищет a или b |Вертикальная черта внутри самого значения ячейки, даже часть регулярного выражения, воспринимается парсером Markdown как разделитель новой колонки, а не как обычный символ текста. Строка визуально разваливается на лишние колонки.
Решение простое, экранировать символ обратным слэшем прямо перед ним.
| grep -o "a\|b" | ищет a или b |Проблема вторая: выравнивание через двоеточия
| Слева | По центру | Справа |
| :--- | :---: | ---: |
| текст | текст | текст |Двоеточие слева от дефисов означает выравнивание по левому краю, с двух сторон означает по центру, справа означает по правому краю. Частая ошибка — поставить двоеточие только с одной стороны, рассчитывая на центрирование, и получить неожиданное выравнивание по краю вместо центра.
| Синтаксис разделителя | Результат выравнивания |
|---|---|
| три дефиса без двоеточий | По умолчанию, обычно по левому краю |
| двоеточие слева, дефисы, без справа | По левому краю явно |
| двоеточие с обеих сторон | По центру |
| дефисы, без слева, двоеточие справа | По правому краю |
Проблема третья: разное число столбцов в разных строках
Если в разделительной строке указано три колонки, а в какой-то строке данных случайно оказалось четыре ячейки из-за лишней вертикальной черты, разные рендереры Markdown реагируют по-разному: одни молча обрежут лишнюю ячейку, другие сломают всю визуальную структуру таблицы целиком, начиная с этой строки и до конца.
Проблема четвертая: перенос строки внутри ячейки
Стандартный синтаксис Markdown таблиц вообще не поддерживает настоящий перенос строки внутри одной ячейки. Попытка вставить реальный Enter внутри ячейки просто разорвет строку таблицы на две части, а не создаст многострочную ячейку.
Обходной путь для действительно нужного переноса строки внутри ячейки, это HTML тег <br> прямо внутри markdown ячейки, большинство рендереров, включая GitHub, поддерживают такую вставку HTML внутри Markdown таблицы.
| Поле | Значение |
| --- | --- |
| Адрес | Москва<br>ул. Ленина, 1 |Быстрая проверка перед пушем
Если данные для таблицы изначально лежат в Excel или CSV файле, надежнее не собирать таблицу руками построчно, а прогнать исходные данные через CSV to Markdown Table или Markdown Table Generator, которые автоматически расставят все вертикальные черты и экранирование в нужных местах, не оставляя шанса на опечатку в разделительной строке.
Итоговый чеклист
Обязательно включайте разделительную строку с дефисами сразу после заголовков, без нее многие рендереры вообще не распознают таблицу как таблицу.
Экранируйте вертикальную черту обратным слэшем, если она встречается внутри самого значения ячейки, а не только между колонками.
Для выравнивания по центру ставьте двоеточие с обеих сторон дефисов, а не только с одной, иначе получите выравнивание по краю вместо центра.
Следите, чтобы во всех строках таблицы было одинаковое число ячеек, разделенных вертикальной чертой, расхождение в числе колонок ломает рендеринг непредсказуемо в разных системах.
Для переноса строки внутри ячейки используйте HTML тег br, обычный перенос строки Markdown внутри таблицы не работает.