Чтобы исходный код таблицы Markdown оставался читаемым, добавляйте в ячейки пробелы и выравнивайте столбцы после значительных правок. На Mac в Obsidian редактируйте таблицу во встроенном редакторе, а затем проверьте её в режиме исходного кода. Отступы в исходном коде и выравнивание текста при отображении нужно проверять отдельно.

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

Что делает исходный код таблицы Markdown читаемым?

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

Например, эту условную таблицу в компактном виде становится труднее просматривать после добавления длинного названия:

| Item | Finish | Count |
| --- | --- | ---: |
| Pencil | Matte | 4 |
| Large sketchbook | Linen | 12 |

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

| Item             | Finish | Count |
| ---------------- | ------ | ----: |
| Pencil           | Matte  |     4 |
| Large sketchbook | Linen  |    12 |

В GFM пробелы между вертикальными чертами и содержимым ячеек обрезаются. Поэтому отступы не задают ширину столбца при отображении. Двоеточие в ----: задаёт выравнивание отображаемого столбца по правому краю; пробелы перед 4 просто облегчают просмотр этого примера в исходном виде. Спецификация GitHub Flavored Markdown, таблицы.

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

Какая программа будет отображать таблицу?

Таблицы с вертикальными чертами — это расширение, а не часть ядра CommonMark. Текущая версия спецификации CommonMark — 0.31.2, а опубликованная спецификация GFM от GitHub прямо определяет таблицы как расширение CommonMark. Если программа заявляет только о совместимости с CommonMark, это ещё не гарантирует поддержку таблиц с вертикальными чертами. Проверьте, поддерживает ли она также расширение для таблиц. Спецификация CommonMark, Спецификация GitHub Flavored Markdown.

При переносе заметки между приложениями важно учитывать следующие различия:

Целевое приложение Документированное поведение Практический выбор
Ядро CommonMark Синтаксис таблиц с вертикальными чертами не входит в основную спецификацию Проверьте, доступно ли расширение для таблиц
GitHub В руководстве по таблицам указано, что в каждой ячейке строки-разделителя должно быть не менее трёх дефисов Используйте --- или больше
Obsidian В руководстве по таблицам допускается минимум два дефиса; выравнивание ячеек в исходном коде не требуется Если таблица предназначена и для GitHub, используйте три дефиса или больше

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

Для таблицы, предназначенной и для Obsidian, и для GitHub, используйте вертикальные черты в начале и конце строк, обычные пробелы для отступов и пустую строку до и после таблицы. В руководстве GitHub требуется пустая строка перед таблицей; спецификация GFM указывает, что пустая строка завершает таблицу. Явные границы также упрощают поиск таблицы в исходном коде. Документация GitHub по таблицам, Границы таблиц в GFM.

Как поддерживать таблицу в Obsidian на Mac

В Obsidian есть удобный способ редактировать ячейки, а затем просматривать Markdown в читаемом виде. В примечаниях к выпуску настольной версии 1.5.8 появилась информация об автоматическом форматировании таблиц при вводе текста; там же говорится, что столбцы выглядят аккуратнее в режиме исходного кода. Это задокументированное поведение редактора, а не особенность синтаксиса Markdown. Примечания к выпуску Obsidian 1.5.8 Desktop.

Для обычной заметки выполните следующие действия:

  1. Откройте заметку в режиме Live Preview. При необходимости выберите его через значок состояния редактора.
  2. Вставьте таблицу командой Insert Table либо щёлкните правой кнопкой мыши и выберите Insert → Table.
  3. Введите или измените содержимое ячеек в редакторе таблиц. Чтобы добавить, удалить, переместить или отсортировать строки и столбцы, щёлкните правой кнопкой мыши по таблице.
  4. Выберите Source mode через значок состояния и проверьте получившийся код Markdown.
  5. Переключитесь в Reading view, чтобы проверить отображение таблицы.

Переключение режимов описано в разделе Режимы просмотра и редактирования; вставка таблиц и операции через контекстное меню — в разделе Синтаксис расширенного форматирования.

Если вы часто переключаетесь между режимами, назначьте горячую клавишу для команды Toggle Live Preview/Source mode. В macOS сочетание Cmd+E переключает между режимами чтения и редактирования; если вам нужно именно переключение между двумя режимами редактирования, используйте соответствующую команду. Режимы просмотра и редактирования Obsidian.

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

Как выровнять столбцы в исходном коде после значительной правки

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

Вот пример с использованием только простого ASCII-текста. Начните с этой таблицы:

| Item   | Finish | Count |
| ------ | ------ | ----: |
| Pencil | Matte  |     4 |
| Folder | Linen  |    12 |

Теперь замените Folder на Large sketchbook. В новой записи 16 символов, поэтому содержимому первого столбца нужно выделить 16 символов. Оставьте по одному пробелу непосредственно внутри каждой граничной вертикальной черты, а затем добавьте справа столько пробелов, сколько требуется, чтобы заполнить эту область:

  • В слове Item 4 символа: добавьте после него 12 пробелов для выравнивания, а затем пробел у границы.
  • В слове Pencil 6 символов: добавьте после него 10 пробелов для выравнивания, а затем пробел у границы.
  • Запись Large sketchbook полностью занимает область в 16 символов, поэтому после неё нужен только пробел у границы.
  • Увеличьте длину первой ячейки-разделителя до 16 дефисов, чтобы получилась соответствующая визуальная направляющая.

В результате получится таблица с отступами, показанная выше. Расширить нужно было только первый столбец. В остальных сохраняются прежние интервалы и маркеры выравнивания.

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

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

Что проверить, если таблица сломалась?

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

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

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

Для буквальных вертикальных черт GitHub рекомендует ставить перед символом обратную косую черту. В этом полном примере текст Blue | Green остаётся внутри одной ячейки:

| Item   | Options       |
| ------ | ------------- |
| Folder | Blue \| Green |

Экранирование влияет на структуру; добавление пробелов вокруг неэкранированной черты не решит проблему. Пример GitHub с буквальной вертикальной чертой.

Obsidian также описывает экранирование вертикальной черты в псевдониме внутренней ссылки внутри таблицы. Это особенность синтаксиса Obsidian, поэтому экранированный псевдоним сам по себе не гарантирует, что ссылка будет так же работать на GitHub. Рекомендации Obsidian по форматированию таблиц.

Не нажимайте Enter посреди длинной ячейки, чтобы сделать её исходный код визуально уже. Таблицы GFM допускают встроенное содержимое и исключают блочные элементы; универсального формата для многострочного исходного кода ячеек в них нет. Если строки в одну линию становятся неудобными, перенесите длинные пояснения за пределы таблицы. Правила содержимого таблиц GFM.

Поддерживайте таблицу простым способом: внесите изменения в содержимое, проверьте границы ячеек, добавьте пробелы в затронутые столбцы и просмотрите результат. В Obsidian удобнее всего начать со встроенного редактора таблиц, а затем перейти в Source mode. Ручные отступы пригодятся, если вам нужен особый вид таблицы в обычном текстовом формате.

Источники