markdownify zrównał się z markitdown pod względem liczby wygenerowanych wierszy tabeli, przy 1,8 MiB

Na czterech przykładowych plikach HTML współdzielonych z markitdown, markdownify wygenerował dokładnie taką samą liczbę wierszy tabeli Markdown według naszego licznika — 36 do 36 — i odzyskał wszystkie 16 sprawdzanych ciągów treści. Jego wynik 21 062 tokenów był nominalnie najniższy, choć pierwsze trzy konwertery różniły się od siebie zaledwie o 1,3%. Biblioteka instaluje się do 1,8 MiB, ma licencję MIT i w chwili zrzutu miała 2 235 gwiazdek na GitHubie.

To najmniej omawiana biblioteka w tej kategorii i, patrząc na te liczby, ta, po którą sięgnąłbym jako pierwszą.

Czym jest markdownify

markdownify to konwerter HTML do Markdown napisany w Pythonie i oparty na BeautifulSoup. Cała architektura sprowadza się do tego: parsowanie przez BeautifulSoup, przejście po drzewie DOM i generowanie Markdown. Testowana wersja: 1.2.3, licencja MIT, 2 235 gwiazdek, 42 otwarte zgłoszenia, ostatnie wydanie 2026-06-30 — projekt aktywnie utrzymywany, 44 wydania.

Oficjalne źródło: oficjalne repozytorium python-markdownify.

API jest jedno:

from markdownify import markdownify
md = markdownify(html)

Jeśli chcesz nadpisać sposób obsługi elementów, dostępna jest też forma klasowa (MarkdownConverter), a także sensowny zestaw opcji — styl nagłówków, znaki wypunktowania, wykrywanie języka w kodzie, usuwanie elementów. Ale w praktyce najczęściej używa się jednowierszowego wywołania i ono po prostu działa.

pip install markdownify pobiera 5 pakietów i 1,8 MiB, a zimny import trwa 0,046 s — najszybciej spośród trzech testowanych konwerterów. Zależności to głównie BeautifulSoup i jego standardowi towarzysze, które wiele projektów Pythona i tak już ma, więc koszt marginalny bywa bliski zeru.

Jak wyglądał pomiar

Uruchomiłem go na czterech plikach HTML, których inny zestaw w tej bazie użył już przy markitdown, wraz z jego wcześniej zarejestrowanymi ciągami kontrolnymi — 16 dokładnych ciągów z treści strony sprawdzanych pod kątem zachowania, plus testy boilerplate dotyczące „chrome” strony. Piąty plik, Nothing but tables, to osobny test mocno nastawiony na tabele i został wyłączony z poniższego zestawienia czterech plików.

fourway-scores.json. Cztery pliki, tokeny liczone przez o200k_base, wiersze tabel liczone jedną regułą dla wszystkich czterech — w tym ponowne zliczenie zapisanego wyniku markitdown, który dokładnie zgadzał się z opublikowaną wartością.

Wyróżniają się trzy rzeczy.

Równa się markitdown pod względem liczby wygenerowanych wierszy tabeli. Po 36 wierszy na czterech wspólnych plikach, liczonych tą samą heurystyką. To nie dowodzi identyczności komórka po komórce; oznacza tylko, że oba wyniki ujawniły temu licznikowi tę samą liczbę rozpoznawalnych wierszy tabeli Markdown.

Ma najniższą liczbę tokenów. 21 062, minimalnie poniżej 21 176 w html2text i 21 336 w markitdown, oraz o 19,7% mniej niż turndown z 26 236. Pierwsze trzy wyniki są oddalone od siebie o nie więcej niż 1,3%, więc nazwałbym to raczej remisem niż wygraną; istotna różnica jest względem turndown.

Wszystkie kontrolne fragmenty treści przetrwały. Wszystkie 16. Tak samo było w pozostałych trzech narzędziach — zachowanie treści nie jest tu źródłem różnic.

Tabela, z którą radzi sobie najlepiej

Plik z danymi o hokeju to miejsce, w którym konwertery się rozchodzą. markdownify:

| Team Name | Year | Wins | Losses | OT Losses | Win % | ... |
| --- | --- | --- | --- | --- | --- | --- |
| Boston Bruins | 1990 | 44 | 24 |  | 0.55 | ... |

Standardowy GFM z pionowymi kreskami na początku i końcu, wierszem separatora i — zwróć uwagę na pustą komórkę między 24 a 0.55 — zachowuje pustą komórkę zamiast ją pomijać. Brzmi jak detal i nim nie jest: konwerter, który usuwa puste komórki, przesuwa wszystkie kolejne wartości do złej kolumny, a mimo to wynik nadal wygląda jak poprawna tabela.

turndown na tym samym wejściu wyrzuca każdą wartość jako osobny akapit, bez żadnej struktury kolumn. html2text tworzy poprawną tabelę w innym stylu, bez zewnętrznych pionowych kresek.

Jeśli Markdown ma trafić do modelu, to właśnie te kreski i zachowana pusta komórka pozwalają odpowiedzieć „ile meczów przegrał Boston?”, zamiast zgadywać.

Dwie rzeczy, które usuwa, a turndown nie

Dokładność tabel to widoczna różnica. Ta druga jest ważniejsza i nikt o niej nie wspomina.

markdownify usuwa zawartość <script> i <style>. turndown nie. Liczone po znacznikach, które występują wyłącznie wewnątrz tych elementów, wyjście markdownify na wszystkich plikach ma zero znaczników skryptu i zero znaczników stylu; turndown ma ich 10 i 84. W pliku z Wikipedii to różnica między 59 561 znakami a 74 939 — i osiem linii wbudowanej konfiguracji JavaScript i CSS MediaWiki odpowiada za 14 644 znaki, czyli 95% tej różnicy (script-style-stripping.json).

Dla wszystkiego, co zasila model, to najdroższy element całego porównania: blob konfiguracji JavaScript zużywa tokeny i nie niesie żadnej informacji. markdownify usuwa go bez proszenia. html2text też.

Dla pojedynczych plików markdownify i html2text zgadzają się dokładnie tam, gdzie tabela jest prosta, i różnią tam, gdzie już nie jest:

markdownify generuje więcej rozpoznanych wierszy w obu testach diagnostycznych. W szczególności na Wikipedii zachowuje dziewięć wierszy, podczas gdy html2text według tego licznika zatrzymuje pięć. To dobra wskazówka, by przed wyborem sprawdzić reprezentatywne tabele zagnieżdżone i nieregularne, ale nie dowód, że każda wygenerowana komórka jest semantycznie poprawna.

Instalacja i licencja na tle alternatyw

Oficjalne źródło: markdownify na PyPI.

install-and-import.json oraz metadata-snapshot.json. Każda biblioteka została zainstalowana we własnym pustym środowisku.

html2text zajmuje na dysku dziewięć razy mniej miejsca i ma licencję GPL-3.0-or-later. W produkcie dystrybuowanym dalej traktowałbym to jako punkt kontrolny dla osoby odpowiedzialnej za licencjonowanie; ten artykuł nie jest poradą prawną. markdownify ma MIT, co zwykle jest bardziej liberalne, ale nadal wymaga standardowego przeglądu zgodności.

Te 1,8 MiB są też w pewnym sensie umowne, jeśli Twój projekt już korzysta z BeautifulSoup, a robi to wiele projektów Pythona związanych ze scrapingiem — w takim przypadku markdownify jest prawie darmowy.

Tempo wydawnicze markdownify jest najlepsze z tej trójki: 44 wydania i aktualizacja sześć tygodni przed testem, podczas gdy html2text miało ostatnie wydanie w kwietniu 2025.

Co właściwie daje pojedyncza linia Pythona

Cała biblioteka to markdownify(html), i warto jasno powiedzieć, co to wywołanie robi za Ciebie, bo trzy z tych decyzji są dokładnie tym, na czym opiera się to porównanie.

Parsuje przez BeautifulSoup, usuwa <script> i <style> bez pytania oraz generuje tabele w stylu GFM z pionowymi kreskami po bokach i zachowanymi pustymi komórkami. Sam „rodowód” parsera nie gwarantuje zachowania przy błędnym HTML, więc to pytanie zostało zmierzone osobno poniżej.

Żadna z tych rzeczy nie jest opcją, którą ustawiasz. Tak działa domyślna konfiguracja. A w kategorii, w której domyślne działanie turndown zachowuje JavaScript, a domyślne html2text zawija linie do 78 znaków, biblioteka, której zachowanie po wyjęciu z pudełka nie wymaga poprawek, ma samodzielną wartość.

Opcje są, jeśli ich potrzebujesz — heading_style, bullets, code_language, strip i convert do list dozwolonych i zakazanych elementów oraz MarkdownConverter do nadpisywania zachowania per element. Wszystko, co zmierzono tutaj, nie używało żadnej z nich.

Pamięć i wpływ uszkodzonego HTML

Szerszy kontekst testów obciążeniowych znajdziesz w porównaniu pamięci i źle sformatowanego HTML dla dziesięciu bibliotek.

Dwie rzeczy, które w każdej recenzji z tego zestawu pozostawały nieprzetestowane, zostały teraz zmierzone.

Szczytowe zużycie pamięci rezydentnej, przez /usr/bin/time -l, osobny świeży proces dla każdej komórki — dolna granica importu to koszt samej biblioteki po załadowaniu i bezczynności, a szczyty obejmują dokument.

memory-results.json. Bazowych wyników Pythona i Node nie da się bezpośrednio porównywać; interpreter jest obecny w obu przypadkach.

markdownify plasuje się pośrodku: 23,9 MiB dolnej granicy i 278,5 MiB dla dokumentu 10 MB. To 3,9× wynik html2text i około jedna dziesiąta turndown, co jest ceną za użycie BeautifulSoup pod spodem.

Uszkodzony HTML. Dwanaście dokumentów, z których każdy psuje dokładnie jedną rzecz — niezamknięte tagi, źle zagnieżdżone elementy inline, nieużyte cudzysłowy w atrybutach zawierających spacje, samotne tagi zamykające, brak <html>, zduplikowane atrybuty, dokument urwany w środku taga, błędne encje, niezamknięty <script>, fałszywa deklaracja kodowania, komentarz zawierający znaczniki i 600 poziomów zagnieżdżenia — oraz dwa poprawne pliki kontrolne o dopasowanych rozmiarach, bo „nic nie zwrócił” ma sens tylko wtedy, gdy biblioteka milczy także na czystym dokumencie o tej samej wielkości.

markdownify zgłosił wyjątek w 1 z 14 przypadków i nie zwrócił nic w 0, odzyskując 30/33 sygnałów kontrolnych w uszkodzonych plikach (malformed-results.json). Jeden plik nie jest liczony do tego wyniku: zgodnie z HTML5 wszystko po niezamkniętym <script> jest zawartością skryptu, więc utrata tego fragmentu jest tam poprawna, a jego odzyskanie byłoby odchyleniem.

Zalety i wady

Zalety. Dokładność tabel równa markitdown, liczona tą samą regułą. Najniższa liczba tokenów z czterech. MIT. 1,8 MiB i bliski zeru koszt marginalny, jeśli BeautifulSoup już jest w drzewie zależności. Najszybszy zimny import: 0,046 s. Aktywnie wydawany. Zachowuje puste komórki tabel. Możliwość nadpisywania konwersji per element przez MarkdownConverter. Zwykłe wywołanie jednowierszowe jest właściwym wyborem.

Wady. Zależność od BeautifulSoup, więc jeśli już go nie masz, zajmuje dziewięć razy więcej miejsca niż html2text. 2 235 gwiazdek oznacza mniejszą społeczność niż turndown — mniej gotowych przykładów, gdy trafisz na coś nietypowego. Tylko Python, więc bezużyteczny w stacku Node. No i 42 otwarte zgłoszenia.

Kto powinien go używać, a kto nie

Zacznij od markdownify, jeśli masz zadanie w Pythonie podobne do tych plików testowych. Według tego licznika zrównał się z markitdown pod względem liczby wygenerowanych wierszy tabeli, należy do grupy o najniższej liczbie tokenów i ma licencję MIT. Jeśli i tak zależysz od BeautifulSoup, koszt marginalnej instalacji może być niewielki; sprawdź rzeczywisty przyrost zależności w swoim środowisku.

Rozważ html2text, jeśli budżet na zależności liczysz w setkach kilobajtów i odpowiada Ci kształt jego wyjścia dla Twoich stron. Przed wdrożeniem do dystrybucji zweryfikuj z osobą odpowiedzialną za licencje zgodność z GPL-3.0-or-later.

Rozważ markitdown, jeśli i tak konwertujesz PDF-y lub dokumenty Office. W tych testach HTML ich wynik miał tę samą liczbę wygenerowanych wierszy, ale szerszej równoważności jakości nie wykazano.

Pomiń go w Node, gdzie naturalnym wyborem jest turndown — razem z zainstalowanym turndown-plugin-gfm, bo podstawowy turndown nie generuje żadnych tabel.

Gdzie pasuje zarządzane API

markdownify konwertuje HTML, który już masz. Nie pobiera stron, nie renderuje JavaScriptu, nie radzi sobie z warstwą anty-bot — żadna z czterech bibliotek tego nie robi, a w wielu realnych przypadkach to właśnie ta trudniejsza połowa zadania.

To samo porównanie pięciu konwerterów dla tych plików znajdziesz w pięciostronnym porównaniu HTML do Markdown.

Nasz własny stos deweloperski w Thunderbit rozwiązuje zadanie „upstream”: POST /distill pobiera adres URL i zwraca Markdown, a POST /extract zwraca JSON w określonym schemacie. Oba interfejsy są dostępne przez serwer MCP i CLI; cennik znajdziesz na stronie z cennikiem Thunderbit. Te hostowane endpointy nie były benchmarkowane względem lokalnych konwerterów, więc to różnica kategorii, a nie porównanie wydajności.

Uczciwie rzecz ujmując: jeśli masz HTML i chcesz Markdown, markdownify jest darmowy i robi to równie dobrze jak cokolwiek tutaj. Jeśli dopiero pobierasz strony albo potrzebujesz wierszy zamiast prozy, mówimy o innym zakupie.

Szerszy przegląd rynku znajdziesz w naszym zestawieniu API do web scrapingu oraz w opracowaniu o open-source scraperach dla rozwiązań self-hosted. Konwersja HTML do Markdown w Pythonie to praktyczny przewodnik.

Wypróbuj Thunderbit do ekstrakcji danych z sieci

Czy warto używać markdownify?

W Pythonie to mocny kandydat, jeśli Twoje wejścia przypominają te pliki testowe; sprawdź go na własnych tabelach i uszkodzonych stronach, zanim ustawisz go jako domyślny.

Zrównał się z markitdown pod względem liczby wygenerowanych wierszy tabeli, należy do grupy o najniższej liczbie tokenów, na tym teście importował się najszybciej i ma licencję MIT. Minusy: zużywał więcej pamięci niż html2text, działa tylko w Pythonie i zgłosił wyjątek na jednym uszkodzonym pliku. Rozmiar na dysku i licencja to dodatkowe kryteria wyboru, nie jedyne argumenty.

Uderza mnie liczba gwiazdek. turndown ma pięć razy większą uwagę społeczności, a mimo to, bez żadnych dodatków, poprawnie konwertuje zero tabel, z którymi markdownify radzi sobie dobrze. Popularność w tej kategorii nie nadąża za zmierzonym zachowaniem, i właśnie dlatego to porównanie było warte przeprowadzenia.

Wypróbuj Thunderbit do ekstrakcji danych z sieci Get Started Free

FAQ

Czy markdownify naprawdę dorównuje markitdown w HTML? Na tych czterech plikach wygenerowały po 36 rozpoznanych wierszy tabeli Markdown, odzyskały wszystkie 16 sprawdzanych ciągów i różniły się liczbą znaków o zaledwie 0,2%. To nie jest test zgodności komórka po komórce ani równoważności renderowania. markitdown obsługuje też PDF-y i formaty Office, więc to porównanie dotyczy wyłącznie zmierzonych wyników HTML.

Czy potrzebuje BeautifulSoup? Tak — to jego parser i duża część tych 1,8 MiB. Jeśli Twój projekt już używa BeautifulSoup, koszt marginalny markdownify jest niewielki. Jeśli nie, a miejsce na dysku naprawdę ma znaczenie, html2text zajmuje 0,2 MiB i ma jeden pakiet, kosztem licencji GPL-3.0-or-later.

Jak radzi sobie z pustymi komórkami tabel? Zachowuje je. W pliku z brakami danych wyjście trzyma pustą komórkę we właściwej pozycji, więc każda następna wartość pozostaje w swojej kolumnie. Konwerter, który pomija puste komórki, tworzy tabelę, która nadal wygląda poprawnie, ale każda wartość przesuwa się o jedną kolumnę w lewo — to gorsza awaria, bo nic jej nie sygnalizuje.

Czy użyć funkcji czy klasy? markdownify() dla typowego przypadku. MarkdownConverter, gdy trzeba nadpisać sposób konwersji konkretnego elementu — wszystko mierzone tutaj używało zwykłej funkcji z domyślnymi opcjami.

Czego tu nie testowano? Cztery wspólne pliki plus jeden test wyłącznie tabelowy nie stanowią reprezentatywnego korpusu. Osobny zestaw uszkodzonych plików obejmował 12 nazwanych typów błędów i dwa kontrolne przypadki, ale nie każdy możliwy rodzaj uszkodzonego HTML. Nie porównywano zagnieżdżonych list, list definicyjnych, przypisów, matematyki, round-tripów Markdown-to-HTML, zgodności tabel komórka po komórce ani wariantów konfiguracji. Nie porównywano też szybkości konwersji.