MarkItDown często wrzuca się do jednego worka z web scraperami — i to jest mylne skojarzenie. Nie ma tam żadnego crawlera, silnika JavaScript ani mechanizmu, który pobiera URL i czyści stronę z niepotrzebnych elementów. Jego zadanie jest inne: bierze dane, które już masz — PDF-a, dokument Word, arkusz kalkulacyjny, prezentację — i zamienia je na Markdown, który potrafi odczytać model językowy.
Przez kilka tygodni uruchamiałem Microsoft MarkItDown na zestawie prawdziwych dokumentów na jednym Macu, oceniając każdą tabelę względem manifestu przygotowanego przed testem i mierząc czas każdej konwersji. Krótko mówiąc: na czystych danych działa szybko i wiernie, w pakiecie ukrywa 73 MB środowiska uczenia maszynowego, którego nikt nie zamawiał, a tabele psują się w sposób, który przechodzi test „czy tekst przetrwał?”, ale oblewa test „czy dane są w odpowiedniej kolumnie?”. Poniżej pełny obraz wraz z liczbami.
Czym właściwie jest MarkItDown
MarkItDown to narzędzie w Pythonie stworzone przez Microsoft, które konwertuje pliki i dokumenty Office do Markdown zoptymalizowanego pod LLM-y. Wskazujesz mu PDF, .docx, .xlsx, .pptx, obraz, plik HTML albo kilka innych formatów, a ono zwraca Markdown. Można z niego korzystać na trzy sposoby: przez CLI (markitdown file.pdf -o out.md albo przez stdin), przez API Pythona (MarkItDown().convert(...)) oraz opcjonalnie przez serwer MCP do workflow agentowych.
Najważniejsze jest jednak to, czego to narzędzie nie robi — i właśnie dlatego, że README tego nie obiecuje, a testy to potwierdziły: nie crawluje, nie renderuje JS, nie podąża za linkami, nie obsługuje paginacji i nie wyciąga głównej treści w stylu narzędzi do czytelnego artykułu. To konwerter całych dokumentów. Dostarczasz bytes, a on je normalizuje. To właśnie ta różnica decyduje, czy to narzędzie pasuje do Twojego stacku, czy nie — dlatego będę do niej wracać.
Sam repozytorium robi wrażenie według githubowych wskaźników popularności — 165 282 gwiazdki i 11 790 forków w połowie lipca 2026 roku, licencja MIT, a najnowsze wydanie (v0.1.6) pojawiło się 2026-05-26. Tyle że ten wynik to raczej efekt ogólnego entuzjazmu wokół narzędzi dla LLM-ów i faktu, że repo należy do Microsoftu, niż sygnał dojrzałości samego silnika konwersji. Jest też 833 otwartych issue, a część z nich ma znaczenie jeszcze zanim zainstalujesz narzędzie — więcej o tym poniżej.
HTML do Markdown: szybko, kompletnie, z boilerplate’em w pakiecie
Ponieważ reszta mojej serii testów scraperów opiera się na tych samych czterech webowych fixture’ach, podałem MarkItDown identyczne lokalne pliki HTML — nie po to, by oceniać go jak scraper, ale żeby sprawdzić, jak dobra jest jego konwersja HTML do Markdown. Na dobrze opisanych stronach radzi sobie naprawdę dobrze.
Wszystkie cztery strony przeszły przez podstawową instalację bez dodatkowych zależności, a każdy test na treści głównej się udał. Artykuł Wikipedii o „Web scraping” (226 KB) został odtworzony z zachowaniem struktury nagłówków — jedno h1, siedem h2 i dwanaście h3, zgodnie z rzeczywistą strukturą sekcji — a 418 linków pozostało poprawnie zapisanych jako [tekst](url). Tabela statystyk hokejowych 26×9 na stronie Scrape This Site forms page została zamieniona w czystą tabelę GFM typu pipe, z 27 wierszami (nagłówek + separator + 26 wierszy danych), łącznie z pustymi komórkami. Czas też nie stanowił problemu: mediana wyniosła 48 ms dla małej strony z cytatami i 352 ms dla strony Wikipedii o rozmiarze 226 KB.
Jest jednak haczyk — i to bardziej decyzja projektowa niż błąd. MarkItDown nie usuwa boilerplate’u. Konwertuje cały <body>, więc elementy „site chrome” przechodzą razem z treścią, a ich udział rośnie wraz z ilością takich dodatków na stronie.
| Strona | Liczba znaków wyjściowych | Nagłówki (h1/h2/h3) | Linki | Linie interfejsu strony |
|---|---|---|---|---|
| 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) |
Na niemal pozbawionej elementów interfejsu stronie głównej Books tylko 0,6% linii wyjściowych to chrome. Na Wikipedii to już 12,4% — 42 z 338 niepustych linii to „jump to content”, „toggle the table of contents”, „22 languages”, „retrieved from”, stopki cookies i licencji. Te komunikaty konserwacyjne Wikipedii („This article needs additional citations”) również trafiają wiernie do dwukolumnowych tabel pipe, i stąd na stronie bez prawdziwej tabeli danych pojawia się dziewięć wierszy tabeli.
To nie jest błąd MarkItDown. To konwerter całych dokumentów, a nie ekstraktor czytelnej treści. Wierna konwersja HTML do Markdown to inne zadanie niż czyste wydobywanie artykułu. Trafilatura i narzędzia w stylu Firecrawl mają zwracać tylko główną treść; MarkItDown zwraca całą stronę. W środku _html_converter.py usuwa tylko <script> i <style>, a potem przekazuje cały body do biblioteki markdownify — bez żadnej heurystyki głównej treści. Jeśli chcesz sam artykuł, to jest zła warstwa.
Naturalne środowisko: PDF, DOCX, XLSX, PPTX
Dokumenty to właśnie to, do czego MarkItDown został stworzony. Przetestowałem go na prawdziwych publicznych plikach — artykule z arXiv z warstwą tekstową, białej księdze Bitcoina, zeskanowanym PDF-ie zawierającym wyłącznie obraz, wyrenderowanym tak, by nie miał żadnego tekstu, oraz plikach DOCX/XLSX/PPTX z własnego zestawu testowego MarkItDown (z losowymi UUID, żeby wykryć cichą utratę treści).
| Dokument | Wejście | Liczba znaków wyjściowych | Trafione testy | Mediana czasu | Uwagi |
|---|---|---|---|---|---|
| arXiv 1706.03762 (PDF z warstwą tekstową) | 2.2 MB | 40,174 | 7/7 | 3.7 s (warm) | tytuł, „Transformer”, „BLEU”, „References” obecne |
| Whitepaper Bitcoina (9 str. PDF) | 184 KB | 22,485 | 6/6 | 1.4 s | „Satoshi Nakamoto”, „proof-of-work”, „Conclusion” obecne |
| Skanowany PDF (bez warstwy tekstowej) | 89 KB | 0 | 0/4 | 15 ms | puste wyjście, brak błędu, brak OCR |
| DOCX (test.docx) | 136 KB | 4,651 | — | 70 ms | nagłówki + tabela GFM; UUID przechodzą bez strat |
| DOCX z równaniami | 15 KB | 240 | — | 101 ms | Office Math zachowany jako LaTeX |
| XLSX (test.xlsx) | 12 KB | 808 | — | 57 ms | każdy arkusz → ## SheetName + tabela GFM |
| PPTX (test.pptx) | 278 KB | 2,047 | — | 52 ms | znaczniki numerów slajdów, tabele, wykres → tabela |
W PDF-ach z warstwą tekstową trafność odczytu była świetna — 7 z 7 wcześniej zdefiniowanych testów w artykule arXiv „Attention Is All You Need”, 6 z 6 w whitepaperze Bitcoina — a żaden z plików Office nie zgubił ani jednego UUID, więc na własnych fixture’ach regresyjnych maintainerów nie było cichej utraty treści. Jest też miły, wąski sukces: ścieżka DOCX (przez mammoth) zachowuje równania Office Math jako LaTeX, zamieniając equations.docx w prawdziwe formuły $$...$$. Jeśli karmisz model językowy dokumentami Word z dużą ilością matematyki, to jest realna, choć bardzo konkretna przewaga, której nie udało mi się znaleźć opisanej gdzie indziej.
Dwa wyniki z tej części zasługują na osobne omówienie, bo to właśnie one najpewniej sprawią Ci kłopot.
Skanowany PDF, który znika
Jeśli podasz MarkItDown PDF-a będącego wyłącznie obrazem, bez warstwy tekstowej, dostaniesz pusty string. Zero znaków, bez wyjątku, bez ostrzeżenia — konwersja trwa około 15 ms, bo nie ma czego wyciągać. Ścieżka PDF w MarkItDown służy tylko do ekstrakcji tekstu (pod spodem działa pdfminer i pdfplumber), a OCR nie jest częścią ani podstawowej instalacji, ani żadnego dodatku pip.
To ważne przy przetwarzaniu wsadowym. Programista wrzucający folder PDF-ów, z których część to skany, dostaje dla tych plików po cichu puste wyniki, bez żadnego sygnału, że coś zostało pominięte. Sprawdziłem, czy fixture nie jest uszkodzony, uruchamiając bezpośrednio extract_text z pdfminera — wynik był zerowy, bez obciętych znaków, bez warstwy tekstowej, potwierdzone. Czyli puste wyjście to rzeczywiste zachowanie MarkItDown na prawdziwym skanie. To odtwarza długo otwartą lukę w fallbacku OCR (#1268), śledzoną upstream od dłuższego czasu. Oficjalna ścieżka to opcjonalny backend Azure Document Intelligence albo plugin; żaden z nich nie znajduje się w instalacji domyślnej.
PDF-y wychodzą jako płaski tekst, nie struktura
W obu testowanych PDF-ach z warstwą tekstową MarkItDown nie wygenerował ani jednego znacznika nagłówka Markdown. PDF nie zawiera semantycznych tagów nagłówków, a MarkItDown nie wyciąga ich z wielkości fontu, więc każda linia trafia na poziom body. Trafność tekstu jest wysoka; struktura jest płaska.
To nie tylko mój wynik. Publiczne benchmarki zewnętrzne oceniają hierarchię nagłówków PDF w MarkItDown na około 0,0, a wierność tabel na mniej więcej 0,27, czyli znacznie poniżej 0,88 osiąganego przez Docling z TableFormer (zob. porównanie MarkItDown vs Docling vs Marker oraz benchmark READoc). Moje testy odtwarzają te wyniki, co wzmacnia wiarygodność danych — moje liczby zgadzają się z zewnętrznym źródłem. Ten sam zestaw benchmarków pokazuje też kompromis: MarkItDown działa około 100× szybciej niż Docling, co zgadza się z moimi pomiarami w sekundach, a nie minutach, dla dokumentów, które narzędzia modelowe analizujące układ strony obrabiają przez dłuższy czas. Wniosek: MarkItDown daje czysty, szybki tekst z PDF-a, ale nie daje struktury PDF-a. Jeśli nagłówki i tabele muszą przetrwać, właściwą warstwą jest narzędzie oparte na modelu układu, takie jak Docling lub Marker.
Tabele: treść zawsze przechodzi, struktura już niekoniecznie
Tabele to miejsce, w którym „czy tekst przetrwał?” i „czy dane da się użyć?” zaczynają oznaczać dwie różne rzeczy, więc zbudowałem macierz 13 przypadków — jedna <table> na przypadek, każdy oceniany względem manifestu napisanego przed uruchomieniem — żeby dokładnie zobaczyć, które kształty się utrzymują, a które się psują.
Najważniejszy wniosek: MarkItDown nigdy nie zgubił zawartości tabel. We wszystkich 13 przypadkach zachował 100% wcześniej zdefiniowanych tokenów. Ale wierność strukturalna rozbiła się na trzy kategorie. Siedem z trzynastu dało poprawną siatkę GFM (zwykła, z colspan w nagłówku, szeroka na 24 kolumny, bez nagłówka, z pustymi komórkami, blok w komórce i arabska z kierunkiem RTL). Cztery wyszły krzywo, bo Markdown nie ma pojęcia o komórkach rozciągniętych — więc rowspan, colspan i uszkodzone źródła generują krótkie wiersze. A dwa przypadki były po prostu zepsute.
Te dwa błędy warto nazwać wprost. Zagnieżdżona tabela (<table> wewnątrz <td>) zostaje spłaszczona inline, a jej własne pionowe kreski i wiersz separatora lądują w komórce nadrzędnej, tworząc śmieciowy wiersz „14-kolumnowy”. Z kolei dosłowny znak | w komórce nie jest escapowany — tekst a | b staje się dwiema kolumnami, a x || y trzema — więc dwukolumnowa tabela może zwrócić wiersze z dwiema, trzema i czterema kolumnami, a każdy parser Markdown odczyta błędne granice. Co ciekawe, gwiazdki i backticki w komórce są escapowane; po prostu pionowe kreski nie. Przyczyna jest taka, że ścieżka HTML w MarkItDown korzysta z domyślnej obsługi tabel w markdownify, a jego własna klasa potomna nadpisuje linki, obrazy i nagłówki, ale nie komórki tabel. Ten sam problem z escapowaniem pipe’ów jest otwartym issue dla konwertera CSV (#2019), choć ta poprawka nie dotyczy ścieżki HTML, którą tutaj testowałem.
Najbardziej podstępny wynik — ten, który szczególnie chciałbym pokazać inżynierowi danych — dotyczy rowspan. Przypadek t03 nie tylko wychodzi krzywo; on po cichu rozjeżdża dane. Etykieta z rowspan=2 („Fruit”) pojawia się tylko raz, a wiersz pod nią staje się krótkim dwukolumnowym wierszem (| Banana | 8 |), więc „Banana” trafia pod kolumnę Group zamiast Item. Wszystkie tokeny są obecne. Naiwny konsument, który „po prostu czyta drugą kolumnę”, dostanie złą wartość. To właśnie ten typ błędu, który przechodzi test zachowania tekstu, a cicho psuje zbiór danych.
Samo ograniczenie dotyczące spanów jest znanym, śledzonym ograniczeniem projektowym (#1211, #1248) — płaska siatka GFM po prostu nie potrafi reprezentować spanów ani zagnieżdżeń, więc konwerter wymienia strukturę na pełność treści. Są też dobre zachowania: tabele bez nagłówka dostają syntetyczny pusty wiersz nagłówka (żaden rekord nie zostaje po cichu awansowany do nagłówka), puste komórki są zachowane, a <caption> przechodzi jako linia tekstu nad tabelą.
Instalacja i start: koszt, o którym „lekki util” nie uprzedza
Nic nie zaskoczyło mnie tu bardziej — i właśnie tutaj określenie „lekki Python utility” cicho obiecuje zbyt wiele.
Po pierwsze, nie uruchamiaj pip install 'markitdown[all]'. Na Pythonie 3.14 ta komenda po cichu cofa się do markitdown 0.0.2 — wydania sprzed dwóch lat — co odtworzyłem na czystym venv. Przy przypięciu wersji widać, dlaczego: pip install 'markitdown[all]==0.1.6' kończy się błędem, ponieważ dodatkowy pakiet [all] przypina youtube-transcript-api~=1.0.0, a na obecnym PyPI wszystkie buildy z tego zakresu wymagają Pythona <3.14, podczas gdy jedyne buildy zgodne z 3.14 wypadają poza to przypięcie. Resolver cofa się więc aż do ostatniego wydania, którego zależności da się spełnić. To zgadza się z otwartym issue upstream (#2179). Rozwiązanie jest proste: przypnij wersję i instaluj dodatki osobno: pip install 'markitdown==0.1.6', a potem pip install 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'. Każdy z tych pakietów rozwiązuje się poprawnie; tylko połączony zestaw [all] zawiera wadliwe przypięcie. (Ta pułapka zależy od wersji Pythona — na Pythonie 3.13 lub starszym ograniczenie może nie zadziałać, więc [all] może rozwiązać się inaczej.)
Po drugie, rozmiar. Podstawowa instalacja zajmuje 161 MB (puste venv 13 MB + 148 MB). Z tego onnxruntime (73 MB) i numpy (34 MB) razem dają 107 MB — czyli 66% całego podstawowego śladu — i oba trafiają tam przez jedną twardą zależność: magika, detektor typu pliku od Google oparty na ML. Czyli konwerter tekstu dostaje w bazowej instalacji 73 MB runtime’u ONNX, zanim dołożysz choćby jeden dodatek dokumentowy. Po dodaniu dodatków związanych z dokumentami środowisko rośnie do 310 MB. To i tak znacznie lżejsze niż stack z headless browserem, ale jeśli spodziewałeś się mikronarzędzia typu „pip install i gotowe”, warto wiedzieć, że ONNX runtime jedzie w komplecie.
Po trzecie — i to jedyny wynik z całego pakietu, który przechodzi każdy test nowości, jaki wykonałem — nawet po czystej instalacji import markitdown kosztuje około 3,35 sekundy na tej maszynie. Prawie cały koszt pojawia się przy imporcie: markitdown._markitdown eagerly importuje cały rejestr konwerterów (łączny koszt 2,56 s, czyli 76% całości), co wciąga pandas (594 ms, przez konwerter XLSX), python-pptx (427 ms), magika (354 ms) i requests (270 ms) — niezależnie od tego, czy w ogóle konwertujesz te formaty. W długotrwałej usłudze ten koszt się amortyzuje i przestaje mieć znaczenie. W CLI albo przy cold starcie w serverless to realny podatek per proces, którego etykieta „lekki util” nie sugeruje. (Uczciwe zastrzeżenie: to pojedynczy profilowany przebieg, traktowany jako jedna obserwacja, a nie rozkład z wielu testów.)
Skala: nie crashuje, ale dla PDF-ów zaplanuj CPU, a dla arkuszy pamięć
Przepchnąłem przez niego cztery duże przypadki, każdy w osobnym procesie, żeby pamięć szczytowa nie była zanieczyszczona wcześniejszym uruchomieniem. Nic się nie wysypało. Profil kosztów jest jednak mocno nierówny.
| Temat | Wejście | Liczba znaków wyjściowych | Mediana czasu | Szczytowy wzrost RSS |
|---|---|---|---|---|
| NIST SP 800-53r5 (PDF 492 strony) | 5.9 MB | 1,625,365 | 192.5 s | +40 MB |
| XLSX 50 000 wierszy × 8 kol. | 2.1 MB | 3,722,955 | 62.1 s | +374 MB |
| arXiv 1706.03762 (~15-stronicowy PDF) | 2.2 MB | 40,174 | 12.6 s | +25 MB |
| XLSX 200 wierszy × 64 kol. | 46 KB | 120,129 | 2.9 s | +22 MB |
492-stronicowy PDF NIST zajął medianę 192,5 sekundy — około 3,2 minuty, czyli 0,39 s/stronę — ponieważ pdfplumber uruchamia wykrywanie układu formularzy oparte na pozycjach słów na każdej stronie. Szczytowy RSS zatrzymał się na +40 MB, więc to problem CPU, nie pamięci. Nawet 15-stronicowy PDF z arXiv zajął 12,6 sekundy w osobnym, izolowanym procesie, czyli około 3,4× dłużej niż te same dane pokazane „na ciepło” w moim zestawie dokumentów. Ta różnica to koszt zimnego procesu i potwierdza, że głównym czynnikiem jest praca wykonywana per strona, a nie sam rozmiar pliku. Jeśli chcesz jedną przenośną liczbę dla tego PDF-a, użyj izolowanych 12,6 s.
Ścieżka arkuszy kalkulacyjnych ma odwrotny bottleneck. XLSX o wielkości 2,1 MB i 50 000 wierszy wystrzelił do +374 MB szczytowego RSS (oraz 3,7 miliona znaków wyjścia), bo konwerter ładuje cały arkusz i buduje jeden ogromny string Markdown w pamięci. W praktyce oznacza to prostą zasadę: dla dużych PDF-ów licz CPU w minutach; dla dużych arkuszy licz pamięć w setkach MB. To są wyniki z jednej maszyny na macOS arm64 i Pythonie 3.14, więc konkretne wartości per strona i per wiersz są zależne od platformy — ale ogólny kształt (PDF jest wolny i CPU-bound, XLSX pożera pamięć, nic się nie crashuje) przenosi się bardzo dobrze.
Gdzie pasuje Thunderbit — a gdzie nie
Wypróbuj Thunderbit do ekstrakcji danych z sieci
To porównanie łatwo byłoby wyolbrzymić, więc wyznaczę granicę ostrożnie. MarkItDown i Thunderbit rozwiązują sąsiednie problemy, ale nie ten sam.
MarkItDown konwertuje pliki, które już masz. Thunderbit najpierw pobiera stronę. Punkt /distill w Thunderbit zamienia aktywną stronę WWW w czysty Markdown gotowy dla LLM-ów — obsługując renderowanie JS, antyboty i dynamiczną treść, z którymi MarkItDown nie ma jak sobie poradzić — a endpoint /extract zwraca dopasowany do schematu uporządkowany JSON, nie tylko surowy Markdown. Dla developerów jest to dostępne przez API (POST /distill / POST /extract), serwer MCP i CLI (npx @thunderbit/thunderbit-cli) działające na jednym silniku AI — tym samym, który stoi za rozszerzeniem z ponad 100 000 użytkowników.
Nakładanie się jest więc tylko w jednym punkcie — oba narzędzia mogą generować „LLM-ready Markdown” — ale domena wejściowa jest inna: Thunderbit distill działa na URL-u z otwartego internetu, a MarkItDown na lokalnym pliku. Nie są zamiennikami jeden do jednego i nie będę udawać, że są. Realistyczny stack używa obu: pobierasz i crawl’ujesz web przez Thunderbit (albo usługę w stylu Firecrawl), a następnie normalizujesz lokalne dokumenty, które też posiadasz — PDF-y, prezentacje i arkusze — za pomocą MarkItDown. Jedno obsługuje sieć; drugie obsługuje szafkę z plikami.
Plusy i minusy
Mocne strony
- Pełne odzyskiwanie treści z czystego HTML (4/4 strony), z wiernie zachowaną hierarchią nagłówków i linkami
- Wysoka trafność tekstu z PDF/DOCX (arXiv 7/7 testów, Bitcoin 6/6) i brak cichej utraty treści na własnych fixture’ach Office
- Równania Office Math zachowane jako LaTeX — realny, niszowy plus
- Nie wysypał się na żadnym testowanym obiekcie, aż do 492-stronicowego PDF-a i XLSX z 50 tys. wierszy
- Prosty w użyciu: CLI,
convert(), stdin piping i opcjonalny serwer MCP - Licencja MIT, aktywnie utrzymywany przez Microsoft, responsywny tracker issue
Słabe strony
- Zachowuje boilerplate — na Wikipedii nawet do 12,4% linii to chrome; to nie jest extractor artykułów
- Tabele psują się przy spanach, zagnieżdżeniach i pionowych kreskach w komórkach (2/13 zepsute, 4/13 krzywe), a rowspan może po cichu przesunąć dane do złej kolumny
- Skanowane PDF-y / obrazy bez warstwy tekstowej zwracają puste wyjście bez OCR i bez błędu
- Wyjście PDF ma zerową strukturę nagłówków (zgodnie z publicznymi benchmarkami)
- Podstawowa instalacja waży 161 MB i ciągnie 73 MB runtime’u ONNX; ~3,35 s zimnego importu
- Dodatkowy pakiet
[all]na Pythonie 3.14 po cichu cofa instalację do 0.0.2 sprzed dwóch lat
Dla kogo to jest, a dla kogo nie
Sięgnij po MarkItDown, jeśli chcesz ujednolicić dużą paczkę lokalnych dokumentów — Word, Excel, PowerPoint, PDF-y z warstwą tekstową — do Markdown w pipeline dla LLM-a i bardziej zależy Ci na kompletności tekstu niż na zachowaniu struktury. Jako ostatni etap wsadowego przetwarzania, który podaje modelowi czysty tekst, działa szybko, wiernie i za darmo.
Pomiń go albo połącz z innym narzędziem, jeśli Twoje zadanie wygląda inaczej: potrzebujesz tylko głównego artykułu ze strony WWW (użyj narzędzia do czytelnej treści albo czegoś w stylu Firecrawl); potrzebujesz, by nagłówki i tabele z PDF-a przetrwały w nienaruszonej formie (to obszar Docling albo Marker); albo Twoje wejścia zawierają zeskanowane dokumenty wymagające OCR (potrzebny będzie backend Azure albo zupełnie inne narzędzie). A jeśli szukałeś scrapera — czyli czegoś, co pobiera strony i je crawluje — to to nie jest to.
Wstępna ocena, którą zrobiłem na rubryce przypominającej scraper, daje MarkItDown 60/100, ale ten niski wynik to efekt oceniania konwertera według testów dla crawlera. Na własnym polu jego wyniki w zachowaniu tekstu są wysokie; słabsze punkty są strukturalne (tabele, nagłówki PDF) i związane z pakowaniem (waga, import, pułapka [all]), a nie z jakością tekstu. Jeśli oceniasz go za to, czym jest — konwerter plików do Markdown — to dostajesz solidne, dobrze utrzymane narzędzie z kilkoma ostrymi krawędziami, o których warto wiedzieć, zanim włączysz je do produkcji.
Najczęściej zadawane pytania
Czy MarkItDown to web scraper?
Nie. Nie ma crawlera, renderowania JavaScript, podążania za linkami ani paginacji. Konwertuje pliki i dokumenty, które już masz — PDF, DOCX, XLSX, PPTX, obrazy, HTML — do Markdown. Jeśli potrzebujesz pobierać i crawlować strony internetowe na żywo, potrzebujesz narzędzia do scrapingu, takiego jak Thunderbit albo Firecrawl; MarkItDown to krok wykonywany później, gdy już pobrane lub lokalne pliki trzeba zamienić na czysty Markdown.
Dlaczego pip install markitdown[all] instaluje starą wersję?
Na Pythonie 3.14 dodatek [all] przypina youtube-transcript-api~=1.0.0, a każda wersja z tego zakresu wymaga Pythona starszego niż 3.14. Resolver nie jest w stanie spełnić tego ograniczenia, więc po cichu cofa się do markitdown 0.0.2, wydania sprzed dwóch lat. Rozwiązanie: przypnij wersję i instaluj dodatki osobno: pip install 'markitdown==0.1.6', a potem dodaj 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'. Jest to śledzone jako issue #2179.
Czy MarkItDown robi OCR na zeskanowanych PDF-ach?
Nie w domyślnej instalacji. Jego ścieżka PDF służy tylko do ekstrakcji tekstu, więc PDF będący samym obrazem i bez warstwy tekstowej zwraca pusty string — bez błędu, bez ostrzeżenia. OCR wymaga opcjonalnego backendu Azure Document Intelligence albo pluginu, z których żaden nie jest dostępny domyślnie. To długo śledzona luka (issue #1268).
Jak MarkItDown radzi sobie z tabelami?
Pod względem treści bardzo dobrze — w moim teście 13 przypadków zachował 100% zawartości tabel w każdym z nich. Strukturalnie zależy to od kształtu: proste, szerokie, beznagłówkowe i z pustymi komórkami tabele wychodzą jako czyste siatki GFM, ale rowspan i colspan robią się nierówne (a rowspan może po cichu przesunąć dane do złej kolumny), zagnieżdżone tabele spłaszczają się do śmieciowych wierszy, a dosłowne znaki pipe w komórkach nie są escapowane. Płaski format tabel w Markdown po prostu nie potrafi reprezentować spanów ani zagnieżdżeń.
Czy MarkItDown jest wystarczająco szybki dla dużych dokumentów?
Nie crashuje na dużych plikach, ale trzeba planować zasoby zależnie od typu pliku. PDF o długości 492 stron zajął około 3,2 minuty (mniej więcej 0,39 s/stronę), bo robi detekcję układu na każdej stronie i jest CPU-bound. Arkusz z 50 000 wierszy skończył się po około minucie, ale zużył dodatkowe 374 MB RAM, ponieważ buduje jeden duży string Markdown w pamięci. Dla dużych PDF-ów planuj minuty CPU; dla dużych arkuszy planuj setki MB pamięci.
Wypróbuj Thunderbit do ekstrakcji danych z sieci Get Started Free
