Совместимость с Markdown
Что Kirbon правит визуально, что хранит как защищенные блоки и как пишет Markdown.
Формат
Kirbon читает и записывает CommonMark с GitHub Flavored Markdown — таблицы, списки задач, зачеркивание и автоссылки, — а также GitHub alerts для выносок, сноски и YAML front matter. Он никогда не пишет в файлы скрытые метаданные или собственный формат.
Что Kirbon правит, что хранит и чего не предлагает
| Правится в режиме «Визуальный» | Хранится защищенными блоками | Не предлагается |
|---|---|---|
| Заголовки, абзацы, жирный, курсив, зачеркнутый, код в строке, маркированные, нумерованные списки и списки задач, цитаты, выноски, блоки кода, таблицы, ссылки, изображения с замещающим текстом, подписью и размером, ссылки на файлы, разделители | HTML-блоки, front matter, HTML-комментарии, незнакомые блоки в ограждениях (Mermaid, формулы), определения сносок, определения ссылок, таблицы с объединенными или вложенными ячейками | Подчеркивание, выравнивание и обтекание изображений, заголовки выносок, ширина столбцов, объединение ячеек — в Markdown нет стандартного способа это записать |
Защищенные блоки показываются в подписанной рамке — «Блок HTML · 6 строк», «Свойства страницы · 3 поля» — с кнопкой Изменить в Markdown. Режим «Визуальный» оставляет их в точности такими, как есть.
Как Kirbon пишет Markdown
- Нетронутое остается нетронутым. Открыть и сохранить файл без правок — значит получить байт в байт тот же файл: с окончаниями строк, пробелами в конце, последним переводом строки, маркерами списков и выделения, ограждениями, пустыми строками, HTML и комментариями.
- Переписываются только измененные блоки. Все остальное копируется из оригинала.
- Новые блоки следуют стилю файла: его маркеру списка (
-или*), маркерам выделения, символам ограждений, стилю заголовков и окончаниям строк. Файл без явного стиля получает-,**/*, ограждения из обратных кавычек, заголовки#и LF.
| Элемент | Как записывается |
|---|---|
| Заголовки 1–6 | # … ###### — первый # это название страницы |
| Жирный, курсив, зачеркнутый | **текст**, *текст*, ~~текст~~ |
| Ссылка | [текст](../раздел/страница.md#заголовок) |
| Изображение |  |
| Изображение на 50 % | <img src="…" alt="…" width="50%"> |
| Задача | - [ ] Сделать, - [x] Готово |
| Таблица | Таблица GFM со строкой заголовка и выравниванием; вертикальная черта в ячейке экранируется обратной косой чертой, <br> — перенос строки |
| Выноска | > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION] |
| Разделитель | --- |
Ссылки и якоря
Ссылки на другие страницы — относительные пути с расширением .md, закодированные там, где нужно (%20 для пробела). Якоря заголовков следуют правилам GitHub: строчные буквы, без знаков препинания, пробелы — дефисы, повторы нумеруются -1, -2. Ссылки, которые Kirbon не может найти, остаются как написаны и перечисляются в сведениях о странице — без вашей команды ничего не переписывается.
Файлы, которые Kirbon не может прочитать
Файл, который не является корректным UTF-8 или содержит двоичные данные, открывается в режиме «Markdown» с баннером, объясняющим, почему «Визуальный» недоступен. Он никогда не переписывается, пока вы его не измените.