Три разных результата из одного файла
Конвертер не пытается свести любой JSON к таблице. Сначала файл разбирается, и от формы данных зависит, что вы увидите. Первая строка всегда одинаковая: имя файла становится заголовком первого уровня — по нему потом понятно, откуда взялся кусок текста.
| Форма файла | Что получится | Когда это удобно |
|---|---|---|
| Массив объектов | pipe-таблица, колонки — ключи первого объекта | выгрузка из API, список заказов, логи, справочники |
| Объект верхнего уровня | секции ## для вложенных объектов, поля — списком ключ: значение, массивы объектов — таблицами | карточка заказа, ответ вебхука, конфиг |
| Массив простых значений, строка, пустой файл, битый JSON | код-блок json с исходным содержимым | структуру нельзя показать таблицей — лучше сохранить как есть |
Массив объектов превращается в таблицу
Самый частый случай: выгрузка, где каждая запись — объект с одинаковым набором полей. На входе обычный ответ API:
[
{"id": 1, "name": "Ноутбук", "price": 74990,
"tags": ["электроника", "техника"], "stock": {"msk": 4, "spb": 0}},
{"id": 2, "name": "Мышь", "price": 2490,
"tags": [], "stock": {"msk": 12, "spb": 7}}
]На выходе — Markdown-таблица, которую понимает GitHub, GitLab, Obsidian, любой рендерер и любая модель:
| id | name | price | tags | stock |
| --- | --- | --- | --- | --- |
| 1 | Ноутбук | 74990 | ["электроника", "техника"] | {"msk": 4, "spb": 0} |
| 2 | Мышь | 2490 | [] | {"msk": 12, "spb": 7} |Колонки берутся из ключей первого объекта. Вложенные массивы и объекты остаются в ячейке JSON-строкой: разложить их по плоским колонкам без потери смысла нельзя, а молча выбрасывать — нечестно. Пустой массив так и выглядит — [].
Объект верхнего уровня — это секции, а не таблица
Если файл начинается с фигурной скобки, сверху таблицы не будет. Вложенные объекты становятся заголовками второго уровня, их поля — списком, а массивы объектов внутри — таблицами на своём месте:
- **order_id:** 42
## customer
- **name:** Alex
- **city:** Самара
**items:**
| id | name | price | tags | stock |
| --- | --- | --- | --- | --- |
| 1 | Ноутбук | 74990 | ["электроника", "техника"] | {"msk": 4, "spb": 0} |Когда получится код-блок
- массив простых значений вроде
[1, 2, 3]— таблица из одной колонки читается хуже исходника; - пустой массив или пустой объект — показывать нечего;
- файл не разбирается как JSON: лишняя запятая, комментарии, BOM в начале (частая история с файлами, пересохранёнными в Windows).
Это не ошибка и не потеря данных: содержимое целиком остаётся внутри ```json, файл .md валиден, текст можно отдать модели как есть. Просто структура не превратилась в разметку.
Где ломается таблица и что делать
| Симптом | Причина | Что делать |
|---|---|---|
| В строке появились лишние ячейки | в значении есть | — это разделитель колонок | заменить на / или экранировать \| до конвертации |
| Одна запись разорвала таблицу на две | перенос строки внутри значения | убрать переносы или заменить на пробел |
| Колонки не хватает, в части строк пусто | ключи берутся из первого объекта, у остальных этого поля нет | поставить первым объект с полным набором ключей |
| Вложенный объект обрезан | в ячейку пишется JSON-строка не длиннее 60 символов | вынести вложенность в отдельный файл или развернуть заранее |
| Длинный текст в ячейке обрезан | значение режется по 100 символов | оставить файл в JSON, если важна каждая буква |
| Строк меньше, чем в исходнике | в таблицу идут первые 50 записей, дальше пометка «... and N more rows» | разбить файл на части или забрать данные через API |
Вместо true и null — True и None | значения печатаются как в Python | учитывать, если Markdown потом разбирается скриптом |
Порядок действий
- Откройте конвертер и перетащите файл
.json— регистрация и почта не нужны. - Посмотрите результат: таблица, секции или код-блок — это уже ответ, годится файл как есть или данные надо готовить.
- Скопируйте Markdown или скачайте
.mdи положите туда, где он нужен: вики, репозиторий, корпус для модели, текст задачи.
Файл читается в память процесса и никуда не записывается: на диске его нет, в базу он не попадает, сторонние API не вызываются. В журнал пишется только факт события — тип, размер, хеш IP. Если документы нельзя отдавать наружу вообще, есть вариант on-prem внутри вашей сети.
YAML, TOML и XML ведут себя иначе
Форматы данных ведут себя по-разному: .yaml, .yml и .toml отдаются код-блоком, а .xml разбирается по структуре — повторяющиеся записи (item, entry) приезжают таблицей, вложенность уходит разделами. YAML при этом пересобирается заново: комментарии исчезают, а списки печатаются в стиле PyYAML — без отступа под ключом. Это нормально, если файл нужен человеку, и плохо, если YAML потом должен вернуться в прод.
app:
name: markit
port: 8090
features:
- oauth
- ssoНужна именно таблица из конфига — сначала переведите данные в JSON с массивом объектов, потом конвертируйте.
Когда Markdown из JSON только вредит
Если файл — входные данные для скрипта или аргумент инструмента, таблица всё испортит: типы теряются, значения обрезаются, вложенность превращается в строку. Markdown нужен человеку и модели, а не программе. Для больших наборов (тысячи записей) правильнее оставить JSON и показать модели несколько строк как пример — иначе таблица съест весь контекст и ничего не объяснит.
JSON Lines и выгрузки из логов
Выгрузки часто приходят не одним массивом, а построчно — по объекту в строке, расширение .jsonl или .ndjson. Такой файл конвертер не узнаёт: расширения нет в списке поддерживаемых, поэтому содержимое уходит в общий текстовый разбор и вы получаете код-блок с исходником. Таблицы не будет — и это лучше, чем молча потерять половину строк.
Лечится одной строкой в терминале: собрать строки в массив и переименовать файл в .json.
python3 -c "import json; rows=[json.loads(l) for l in open('dump.jsonl', encoding='utf-8') if l.strip()]; json.dump(rows, open('dump.json', 'w', encoding='utf-8'), ensure_ascii=False)"После этого файл разбирается как обычный массив объектов и превращается в таблицу — с теми же ограничениями на 50 строк и длину значений.
Лимиты и что с Pro
Бесплатно — 25 файлов в сутки с одного IP, каждый до 25 МБ, без регистрации; счётчик обнуляется раз в сутки. Платных тарифов нет: деньги мы не принимаем, платёжной формы нет. Нужен больший лимит, API-ключ или установкав своей сети — оставьте заявку на странице тарифов, напишем, когда будет готово.
Для автоматизации есть POST /api/convert: та же логика, результат лежит в поле markdown ответа. Примеры на curl, Python и JavaScript — в документации API.