MarkItDown часто ставят в один ряд с веб-скраперами, но это ошибка. У него нет краулера, нет JavaScript-движка и нет способа открыть URL, вычистить с него шаблонный мусор и вернуть только нужное. Он делает другое: берет уже имеющиеся у вас байты — PDF, документ Word, таблицу, слайды — и преобразует всё это в Markdown, понятный языковой модели.
В течение пары недель я прогонял Microsoft MarkItDown через набор реальных документов на одном Mac, сверяя каждую таблицу с заранее подготовленным манифестом и замеряя время каждой конвертации. Коротко: на чистых входных данных он быстрый и точный, в упаковке скрыт 73 МБ ML-рантайм, о котором вы не просили, а таблицы ломаются так, что проходят проверку «текст сохранился?», но проваливают проверку «данные встали в нужный столбец?». Ниже — полная картина с цифрами.
Что такое MarkItDown на самом деле
MarkItDown — это Python-утилита от Microsoft, которая конвертирует файлы и офисные документы в Markdown, оптимизированный для LLM. Дайте ему PDF, .docx, .xlsx, .pptx, изображение, HTML-файл или несколько других форматов — и он вернет Markdown. Запускать его можно тремя способами: через CLI (markitdown file.pdf -o out.md или через stdin), через Python API (MarkItDown().convert(...)) и через необязательный MCP-сервер для агентных сценариев.
Самое важное здесь — не то, что MarkItDown делает, а то, чего он не делает. И это не просто мое предположение: README этого тоже не обещает, а в тестах я подтвердил, что краулинга нет, JS-рендеринга нет, перехода по ссылкам нет, пагинации нет и извлечения основного контента по принципу readability тоже нет. Это конвертер целых документов. Вы приносите байты — он приводит их к единому виду. Именно это различие решает, место ли этому инструменту в вашем стеке, поэтому я к нему еще не раз вернусь.
Сам репозиторий по меркам GitHub выглядит солидно: 165 282 звезды и 11 790 форков по состоянию на середину июля 2026 года, лицензия MIT, последний релиз (v0.1.6) вышел 2026-05-26. Но этот звездный счет — скорее следствие популярности Microsoft-репозитория на волне интереса к LLM-инструментам, чем показатель зрелости внутренней логики конвертации. При этом открытых issues — 833, и часть из них важно учитывать еще до установки (об этом ниже).
HTML в Markdown: быстро, полно и вместе с мусором шаблона
Поскольку остальная часть моей серии обзоров скраперов использует одни и те же четыре веб-страницы, я прогнал MarkItDown на тех же локальных HTML-файлах — не чтобы оценивать его как скрапер, а чтобы понять, насколько хороша его конвертация HTML в Markdown. На хорошо размеченных страницах он действительно хорош.
Все четыре страницы конвертировались на базовой установке без дополнительных пакетов, и все контрольные точки по body-контенту сохранились. Статья Wikipedia про Web scraping (226 КБ) сохранила структуру заголовков — один h1, семь h2, двенадцать h3, что совпадает с реальной структурой разделов — и 418 ссылок остались корректными [текст](url). Таблица хоккейной статистики 26×9 на странице Scrape This Site forms превратилась в аккуратную GFM pipe-таблицу из 27 строк (заголовок + разделитель + 26 строк данных), с пустыми ячейками и всеми деталями. По скорости тоже без сюрпризов: медиана от 48 мс для небольшой страницы с цитатами до 352 мс для Wikipedia на 226 КБ.
Но есть нюанс, и это скорее осознанное решение, чем баг. MarkItDown не вычищает boilerplate. Он конвертирует весь <body>, так что элементы оболочки сайта идут следом — и этот «хвост» растет вместе с количеством шаблонного контента на странице.
| Страница | Размер вывода, знаков | Заголовки (h1/h2/h3) | Ссылки | Строки с шаблонным контентом сайта |
|---|---|---|---|---|
| Books to Scrape | 10,478 | 1 / 0 / 0 | 94 | 0.6% (1/159) |
| Quotes to Scrape | 2,973 | 1 / 1 / 0 | 55 | 1.2% (1/86) |
| ScrapeThisSite forms | 3,385 | 1 / 0 / 0 | 31 | 6.7% (5/75) |
| Wikipedia Web scraping | 60,159 | 1 / 7 / 12 | 418 | 12.4% (42/338) |
На почти «чистой» главной Books to Scrape шаблонный мусор составляет всего 0,6% строк вывода. На Wikipedia — уже 12,4%: 42 из 338 непустых строк это «перейти к содержанию», «показать оглавление», «22 языка», «извлечено из», cookie- и license-футеры. Эти служебные баннеры Wikipedia вроде «This article needs additional citations» даже честно превращаются в двухколоночные pipe-таблицы — отсюда девять строк таблиц на странице, где реальной таблицы данных нет.
Но MarkItDown здесь ничего «не ломает». Он конвертирует целый документ, а не извлекает чистую статью: честная HTML-to-Markdown конвертация — это не то же самое, что извлечение основного контента. Trafilatura и Firecrawl-подобные инструменты стараются вернуть только главный текст; MarkItDown возвращает всю страницу. Внутри _html_converter.py он удаляет <script> и <style>, а затем передает весь body в библиотеку markdownify — без какого-либо эвристического выделения main content. Если вам нужна только статья, это не тот слой.
Родная стихия: PDF, DOCX, XLSX, PPTX
Именно для документов MarkItDown и создавался. Я прогнал его по реальным публичным файлам — статье arXiv с текстовым слоем, Bitcoin whitepaper, отсканированному PDF без текста, который я подготовил так, чтобы в нем не было ни одного символа, а также по DOCX/XLSX/PPTX из собственного тестового набора MarkItDown (с UUID-сигнатурами, чтобы ловить тихую потерю контента).
| Документ | Входной размер | Размер вывода, знаков | Проверки | Медианное время | Примечания |
|---|---|---|---|---|---|
| arXiv 1706.03762 (PDF с текстовым слоем) | 2.2 MB | 40,174 | 7/7 | 3.7 s (warm) | title, "Transformer", "BLEU", "References" на месте |
| Bitcoin whitepaper (PDF на 9 стр.) | 184 KB | 22,485 | 6/6 | 1.4 s | "Satoshi Nakamoto", "proof-of-work", "Conclusion" на месте |
| Отсканированный PDF (без текстового слоя) | 89 KB | 0 | 0/4 | 15 ms | пустой вывод, без ошибки, без OCR |
| DOCX (test.docx) | 136 KB | 4,651 | — | 70 ms | заголовки + GFM-таблица; встроенные UUID сохранены |
| DOCX с формулами | 15 KB | 240 | — | 101 ms | Office Math сохранен как LaTeX |
| XLSX (test.xlsx) | 12 KB | 808 | — | 57 ms | каждый лист → ## SheetName + GFM-таблица |
| PPTX (test.pptx) | 278 KB | 2,047 | — | 52 ms | маркеры номеров слайдов, таблицы, график → таблица |
На PDF с текстовым слоем извлечение текста оказалось отличным — 7 из 7 заранее заданных проверок на статье arXiv Attention Is All You Need, 6 из 6 на Bitcoin whitepaper — и ни один офисный файл не потерял ни одной UUID-сигнатуры, так что на собственных регрессионных фикстурах проекта тихой потери контента не было. Особенно приятная узкая победа: путь DOCX (через mammoth) сохраняет формулы Office Math как LaTeX, превращая equations.docx в настоящую математику $$...$$. Если вы скармливаете LLM Word-документы с плотной математикой, это реальное, пусть и нишевое, преимущество, о котором я не нашел хорошего описания в других местах.
Но на этой территории есть два вывода, на которые стоит обратить особое внимание — именно они с наибольшей вероятностью создадут вам проблемы.
Отсканированный PDF, который просто исчезает
Если дать MarkItDown PDF только с изображением, без текстового слоя, он вернет пустую строку. Ноль символов, без исключения, без предупреждения — конвертация занимает около 15 мс, потому что извлекать просто нечего. PDF-путь у MarkItDown занимается только извлечением текста (под капотом работают pdfminer и pdfplumber), а OCR в базовую установку и в любые pip extras не входит.
В пакетной обработке это критично. Разработчик, который скармливает папку с PDF, где часть файлов — сканы, получит для них тихо пустой результат, без какого-либо сигнала, что что-то было пропущено. Я проверил, что проблема не в поврежденной фикстуре, напрямую прогнав по ней extract_text из pdfminer — stripped-символов ноль, текстового слоя нет, всё подтверждено — так что пустой вывод действительно отражает поведение MarkItDown на реальном скане. Это воспроизводит давно открытый пробел с OCR-fallback (#1268), который давно отслеживается upstream. Документированный путь — опциональный Azure Document Intelligence backend или плагин; ни один из них не входит в стандартную установку.
PDF выходят как плоский текст, а не как структура
На обоих PDF с текстовым слоем MarkItDown не создал ни одного Markdown-маркера заголовка. В PDF нет семантических тегов заголовков, а MarkItDown не пытается выводить их из размера шрифта, поэтому каждая строка остается на уровне body. Текст извлекается хорошо; структура остается плоской.
И это не только мой результат. Публичные внешние бенчмарки оценивают точность иерархии заголовков MarkItDown в PDF примерно в 0.0, а качество таблиц — около 0.27, что заметно ниже 0.88 у Docling с TableFormer (см. сравнение MarkItDown vs Docling vs Marker и бенчмарк READoc). Мои тесты подтверждают их результаты, и это плюс к достоверности: мои цифры совпали с внешним источником. Компромисс, который показывают те же бенчмарки, в том, что MarkItDown работает примерно в 100 раз быстрее Docling, и это совпадает с моими временами в секундах, а не в минутах, на документах, которые layout-model-инструмент пережевывает минутами. Вывод: MarkItDown дает вам чистый, быстрый PDF-текст, но не дает PDF-структуру. Если заголовки и таблицы должны сохраниться, нужен инструмент на уровне layout model, например Docling или Marker.
Таблицы: текст сохраняется всегда, структура — не всегда
Таблицы — это место, где расходятся «текст сохранился?» и «данными можно пользоваться?». Поэтому я собрал матрицу из 13 случаев — по одной <table> на кейс, каждый оценивался по заранее написанному манифесту — чтобы точно понять, какие формы выдерживаются, а какие ломаются.
Главный итог: MarkItDown ни разу не потерял содержимое таблиц. Во всех 13 случаях сохранилось 100% заранее отмеченных токенов. Но структурная точность разделилась на три группы. В семи из тринадцати случаев получалась корректная GFM-grid таблица (простая, с colspan в заголовке, шириной 24 столбца, без заголовка, с пустыми ячейками, с блоком внутри ячейки и арабская справа налево). Четыре случая были рваными, потому что в Markdown нет понятия ячейки с объединением, поэтому rowspan, colspan и битые источники дают короткие строки. И две таблицы были просто сломаны.
Два поломанных кейса стоит назвать отдельно. Вложенная таблица (<table> внутри <td>) расплющивается в строку: ее собственные вертикальные черты и строка-разделитель попадают в ячейку родительской таблицы, создавая мусорную строку на 14 «столбцов». И еще: буквальный символ | внутри ячейки не экранируется — текст a | b превращается в два столбца, x || y — в три, так что двухколоночная таблица начинает выдавать строки на два, три и четыре столбца, а любой последующий Markdown-парсер читает границы неправильно. Любопытно, что звездочки и обратные кавычки внутри ячеек экранируются, а вот вертикальная черта — нет. Причина в том, что HTML-путь MarkItDown использует стандартную обработку таблиц markdownify, а его кастомный подкласс переопределяет ссылки, изображения и заголовки, но не ячейки таблиц. Та же категория бага с неэкранированной pipe-черточкой есть и как открытая проблема у CSV-конвертера (#2019), хотя это исправление не затрагивает HTML-путь, который я тестировал.
Есть и более тонкий момент — тот, который я бы особенно хотел показать data engineer. Это rowspan. Случай t03 не просто становится рваным; он тихо сдвигает данные. Метка rowspan=2 («Fruit») выводится один раз, а строка под ней превращается в короткую двухколоночную строку (| Banana | 8 |), поэтому «Banana» оказывается под колонкой Group вместо Item. Все токены на месте. Наивный потребитель, который просто читает второй столбец, получит неверное значение. Это именно тот тип ошибки, который проходит проверку на сохранение текста и незаметно портит датасет.
Само ограничение по span — уже известный и отслеживаемый компромисс дизайна (#1211, #1248): плоская GFM pipe-таблица действительно не может выразить объединения ячеек или вложенность, поэтому конвертер жертвует структурой ради полноты содержания. Но есть и хорошие моменты: таблицы без заголовков получают сгенерированную пустую строку заголовка, так что данные не превращаются в заголовок незаметно; пустые ячейки сохраняются; а <caption> остается как текстовая строка над таблицей.
Установка и запуск: налог, о котором не предупреждает «легкая утилита»
Ничего здесь не удивило меня сильнее, и именно здесь описание в духе «легкая Python-утилита» тихо обещает больше, чем есть на самом деле.
Во-первых, не ставьте pip install 'markitdown[all]'. На Python 3.14 он молча откатывается к markitdown 0.0.2 — релизу двухлетней давности, и я воспроизвел это в чистом venv. Почему так происходит, показывает pinning: pip install 'markitdown[all]==0.1.6' завершается ошибкой, потому что extra [all] фиксирует youtube-transcript-api~=1.0.0, а в текущем PyPI все сборки в этом диапазоне доступны только для Python <3.14, тогда как совместимые с 3.14 сборки выходят за пределы этого pin. Поэтому resolver уходит назад до последнего релиза, чьи зависимости можно удовлетворить. Это совпадает с открытой upstream-проблемой (#2179). Решение простое: зафиксировать версию и ставить extras по отдельности — pip install 'markitdown==0.1.6', затем pip install 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'. Каждый из них ставится без проблем; токсичный pin находится только в объединенном [all]. (Этот капкан зависит от версии Python — на Python 3.13 и ниже ограничение может не сработать, и [all] разрулится иначе.)
Во-вторых, размер установки. Базовая установка занимает 161 МБ: пустой venv на 13 МБ плюс еще 148 МБ. Из этого onnxruntime (73 МБ) и numpy (34 МБ) вместе дают 107 МБ — то есть 66% всего базового веса — и оба пакета тянет одна жесткая зависимость: magika, машинный детектор типа файла от Google. То есть текстовый конвертер в базовой установке уже приносит с собой 73-МБ ONNX inference runtime, еще до того как вы добавите хотя бы один документный extra. Если добавить extras для документов, venv вырастает до 310 МБ. Это намного легче, чем стек на headless-браузере, но если вы ожидали микрoутилиту в стиле pip install и готово, знайте: ONNX runtime идет в комплекте.
В-третьих — и это единственный результат во всей моей серии, который прошел все проверки на редкость, какие я только запускал, — даже после чистой установки import markitdown стоит примерно 3,35 секунды на этой машине. Почти вся цена платится на этапе импорта: markitdown._markitdown заранее подтягивает весь реестр конвертеров (2,56 с суммарно, 76% от общего времени), а вместе с ним pandas (594 мс через XLSX-конвертер), python-pptx (427 мс), magika (354 мс) и requests (270 мс) — независимо от того, будете ли вы реально конвертировать эти форматы. Для долгоживущего сервиса это амортизируется и почти неважно. Для CLI-вызова или serverless cold start это реальный налог на каждый процесс, которого название «легкая утилита» не предполагает. (Честная оговорка: это один профилированный прогон, одна наблюдаемая точка, а не распределение по множеству запусков.)
Масштаб: не падает, но для PDF закладывайте CPU, а для таблиц — RAM
Я прогнал четыре крупные сущности, каждую в отдельном процессе, чтобы пиковая память не искажалась предыдущим запуском. Ничего не упало. Но профиль затрат получился очень неровным.
| Объект | Входной размер | Размер вывода, знаков | Медианное время | Пик RSS Δ |
|---|---|---|---|---|
| NIST SP 800-53r5 (PDF на 492 стр.) | 5.9 MB | 1,625,365 | 192.5 s | +40 MB |
| XLSX 50 000 строк × 8 столбцов | 2.1 MB | 3,722,955 | 62.1 s | +374 MB |
| arXiv 1706.03762 (~15-страничный PDF) | 2.2 MB | 40,174 | 12.6 s | +25 MB |
| XLSX 200 строк × 64 столбца | 46 KB | 120,129 | 2.9 s | +22 MB |
492-страничный PDF NIST SP 800-53r5 занял в медиане 192,5 секунды — примерно 3,2 минуты, или 0,39 с/страница — потому что pdfplumber выполняет поиск форм по позициям слов на каждой странице. Пиковый RSS остался на уровне +40 МБ, так что узкое место здесь CPU, а не память. Даже 15-страничный arXiv PDF в отдельном изолированном процессе занял 12,6 секунды — примерно в 3,4 раза больше, чем 3,7 секунды у того же файла в «теплом» прогоне внутри моего набора документов. Эта разница — цена холодного процесса, и она подтверждает, что решающим является покадровая работа, а не размер файла как таковой. Если нужен один переносимый показатель для этого PDF, берите изолированные 12,6 с.
Путь для таблиц и листов переворачивает узкое место. XLSX на 2,1 МБ и 50 000 строк раздулся до +374 МБ пикового RSS (и 3,7 миллиона знаков в выводе), потому что конвертер загружает весь лист и строит одну огромную Markdown-строку. Практический совет здесь прямой: для больших PDF закладывайте минуты CPU; для больших таблиц — сотни мегабайт RAM. Это цифры с одной машины, macOS arm64 и Python 3.14, и константы на страницу/строку зависят от платформы, но сама форма зависимости — PDF медленный и CPU-bound, XLSX прожорлив к памяти, ничего не падает — переносится вполне хорошо.
Где Thunderbit подходит — а где нет
Попробуйте Thunderbit для извлечения веб-данных
Это как раз та часть сравнения, где легко перегнуть палку, поэтому я аккуратно проведу границу. MarkItDown и Thunderbit решают соседние, но не одинаковые задачи.
MarkItDown конвертирует файлы, которые у вас уже есть. Thunderbit сначала забирает страницу. Эндпоинт Thunderbit /distill превращает живую веб-страницу в чистый Markdown, готовый для LLM — включая JS-рендеринг, антибот-защиту и динамический контент, с которыми у MarkItDown просто нет инструментов, — а эндпоинт /extract возвращает структурированный JSON, совпадающий со схемой, а не только сырой Markdown. Для разработчиков это доступно через API (POST /distill / POST /extract), MCP-сервер и CLI (npx @thunderbit/thunderbit-cli) поверх одного AI-движка — того же, что стоит за расширением с более чем 100 000 пользователями.
То есть пересечение у них только одно — оба могут выдавать «LLM-ready Markdown» — но домен входных данных разный: distill в Thunderbit берет URL в открытом интернете, а MarkItDown принимает локальный файл. Это не взаимозаменяемые инструменты, и я не буду делать вид, что это так. Реалистичный стек использует оба: веб-сбор и краулинг делаете через Thunderbit (или сервис в стиле Firecrawl), а затем нормализуете смешанные локальные документы, которые у вас тоже есть — PDF, презентации и таблицы — через MarkItDown. Один работает с сетью; другой — с файловым шкафом.
Плюсы и минусы
Сильные стороны
- Полностью сохраняет body на чистом HTML (4/4 страниц), честно переносит дерево заголовков и ссылки
- Высокая точность извлечения текста из PDF/DOCX (arXiv 7/7 проверок, Bitcoin 6/6) и отсутствие тихой потери контента на собственных офисных фикстурах проекта
- Формулы Office Math сохраняются как LaTeX — действительно полезная нишевая возможность
- Ни разу не упал ни на одном тесте, вплоть до PDF на 492 страницы и XLSX на 50 тыс. строк
- Очень простой запуск: CLI,
convert(), piping из stdin и необязательный MCP-сервер - Лицензия MIT, активная поддержка Microsoft, живой issue tracker
Слабые стороны
- Оставляет boilerplate — до 12,4% строк-шапки на Wikipedia; это не извлекатель статей
- Таблицы ломаются на объединениях, вложенности и символах pipe внутри ячеек (2/13 сломаны, 4/13 рваны), а rowspan может тихо сдвигать данные не в тот столбец
- Отсканированные PDF/изображения без текста возвращают пустой вывод без OCR и без ошибки
- В PDF полностью отсутствует структура заголовков (что совпадает с публичными бенчмарками)
- Базовая установка весит 161 МБ и тянет 73-МБ ONNX runtime; холодный импорт занимает около 3,35 с
- Extra
[all]на Python 3.14 молча откатывает вас на двухлетний 0.0.2
Кому он подойдет, а кому — нет
Берите MarkItDown, если вам нужно стандартизовать пачку смешанных локальных документов — Word, Excel, PowerPoint, PDF с текстовым слоем — в Markdown для LLM-пайплайна, и вам важнее полный текст, чем сохранение структуры. Как последний этап пакетной обработки, когда вы подаете модели чистый текст, он быстрый, точный и бесплатный.
Не берите его, либо комбинируйте с другим инструментом, если ваша задача относится к одному из этих случаев: вам нужен только основной текст статьи с веб-страницы (тогда нужен readability-инструмент или сервис в стиле Firecrawl); вам нужно, чтобы у PDF сохранились заголовки и таблицы (это зона Docling или Marker); или среди входных данных есть отсканированные документы, где необходим OCR (тогда потребуется Azure backend или другой инструмент). И если ты думал, что покупаешь скрапер — то есть инструмент, который ходит по страницам и их забирает, — это вообще не он.
Мой пробный скоринг по «скраперной» шкале дает MarkItDown 60/100, но низкая сумма здесь — артефакт того, что конвертер оценивают тестом для краулера. На своей территории он хорошо держит текст; слабые места у него структурные (таблицы, заголовки PDF) и упаковочные (размер, импорт, ловушка [all]), а не текстовое качество. Если судить его как то, чем он является — конвертер файлов в Markdown, — это надежный, хорошо поддерживаемый инструмент с несколькими острыми краями, которые стоит знать до того, как вы подключите его к продакшену.
Часто задаваемые вопросы
MarkItDown — это веб-скрапер?
Нет. У него нет краулера, нет рендеринга JavaScript, нет перехода по ссылкам и нет пагинации. Он конвертирует уже имеющиеся у вас файлы и документы — PDF, DOCX, XLSX, PPTX, изображения, HTML — в Markdown. Если вам нужно забирать и обходить живые веб-страницы, используйте инструмент для скрапинга вроде Thunderbit или Firecrawl; MarkItDown — это следующий шаг, когда нужно превратить уже полученные или локальные файлы в чистый Markdown.
Почему pip install markitdown[all] ставит старую версию?
На Python 3.14 extra [all] фиксирует youtube-transcript-api~=1.0.0, а все сборки в этом диапазоне доступны только для Python ниже 3.14. Resolver не может удовлетворить этот pin, поэтому молча откатывается к markitdown 0.0.2, релизу двухлетней давности. Решение — зафиксировать версию и ставить extras по отдельности: pip install 'markitdown==0.1.6', затем добавить 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'. Это отслеживается как issue #2179.
Делает ли MarkItDown OCR для отсканированных PDF?
Не в базовой установке. Его PDF-путь занимается только извлечением текста, поэтому PDF только с изображением и без текстового слоя вернет пустую строку — без ошибки, без предупреждения. Для OCR нужен опциональный Azure Document Intelligence backend или плагин, и ни один из них по умолчанию не поставляется. Это давний открытый пробел (issue #1268).
Насколько хорошо MarkItDown работает с таблицами?
По содержанию — очень хорошо: в моем тесте из 13 случаев он сохранил 100% содержимого таблиц во всех вариантах. По структуре — зависит от формы: простые, широкие, беззаголовочные таблицы и таблицы с пустыми ячейками выходят как чистые GFM-grid таблицы, но rowspan и colspan идут рваными (а rowspan может тихо сдвинуть данные в неправильный столбец), вложенные таблицы расплющиваются в мусорные строки, а символ pipe внутри ячеек не экранируется. Плоский табличный формат Markdown просто не умеет выражать объединения и вложенность.
Достаточно ли MarkItDown быстр для больших документов?
На больших файлах он не падает, но ресурсы нужно планировать по типу документа. PDF на 492 страницы занял около 3,2 минуты (примерно 0,39 с на страницу), потому что он делает покадровое распознавание структуры формы, и упирается в CPU. Таблица на 50 000 строк обработалась примерно за минуту, но использовала +374 МБ RAM, потому что конвертер строит одну большую Markdown-строку в памяти. Для больших PDF закладывайте минуты CPU; для больших таблиц — сотни мегабайт RAM.
Попробуйте Thunderbit для извлечения веб-данных Get Started Free
