Konwerter HTML na Markdown

Konwerter HTML na Markdown – czysta składnia .md z kodu HTML

Markdown to lżejszy format niż HTML – idealny do README, dokumentacji i CMS. Zamiana HTML na Markdown ręcznie jest żmudna. Narzędzie parsuje drzewo DOM i tłumaczy elementy HTML na odpowiadającą im składnię Markdown (CommonMark lub GitHub Flavored Markdown).

Od drzewa DOM do pliku .md – jak działa konwersja

Konwersja nie polega na podmianie znaczników wyrażeniami regularnymi. Narzędzie najpierw parsuje wejście zgodnie z algorytmem parsera HTML5 i buduje drzewo DOM – również wtedy, gdy kod jest niekompletny, ma brakujące zamknięcia albo znaczniki w nietypowej kolejności. Dopiero na gotowym drzewie pracują reguły tłumaczące, dzięki czemu wynik nie zależy od formatowania źródła, takich jak wcięcia czy podział na wiersze.

Przejście po drzewie jest rekurencyjne, od korzenia w dół. Dla każdego węzła elementowego sprawdzany jest jego typ i kontekst, w jakim występuje: inaczej traktowany jest element li wewnątrz listy punktowanej, a inaczej wewnątrz numerowanej; akapit wewnątrz komórki tabeli nie zamienia się na zwykły akapit, bo tabela w GFM wymaga tekstu jednowierszowego. Węzły tekstowe są czyszczone: ciągi spacji i tabulatorów redukowane do pojedynczej spacji, a znaki o znaczeniu składniowym – gwiazdki, podkreślenia, nawiasy kwadratowe, krzyżyki i kreski pionowe – poprzedzane backslashem, żeby renderer nie odczytał ich jako formatowania.

Na końcu wynik składany jest w jeden dokument. Bloki rozdzielane są pustymi liniami, bo Markdown wymaga wolnej linii przed nagłówkiem, listą czy blokiem kodu, aby rozpoznać je jako osobne elementy. Listy dostają wcięcia zgodne z poziomem zagnieżdżenia, a wybrany standard wyjścia decyduje o szczegółach: CommonMark nie zna tabel ani list zadań, GFM obsługuje jedno i drugie i dlatego jest trybem domyślnym, a MDX dodatkowo przepuszcza fragmenty JSX bez zamiany na zwykły tekst.

Przykład: fragment dokumentacji z HTML do Markdown

1. Wejście: wklejasz fragment kodu: <h2>Instalacja</h2><p>Uruchom polecenie <code>npm install</code> i sprawdź <a href='https://webp.pl'>dokumentację</a>.</p><ul><li>Node.js 18+</li><li><strong>npm</strong></li></ul><pre><code class='language-bash'>npm run build</code></pre>
2. Parsowanie: narzędzie buduje drzewo, w którym korzeń zawiera nagłówek h2, akapit p, listę ul z dwoma elementami li oraz blok pre z elementem code. Klasa na elemencie code informuje parser, że to blok kodu w języku bash, a nie zwykły akapit.
3. Nagłówek i akapit: h2 zamienia się na ## Instalacja. W akapicie element code daje fragment w backtickach, a link zamienia się na [dokumentację](https://webp.pl). Kropka kończąca zdanie zostaje w tekście akapitu.
4. Lista: typ listy decyduje o znaczniku, więc każdy element li staje się pozycją zaczynającą się od myślnika, a pogrubienie w drugim punkcie daje **npm**. Wynik to dwie linie: - Node.js 18+ oraz - **npm**.
5. Blok kodu: pre z elementem code i klasą języka zamienia się w ogrodzenie z nazwą języka, następnie wiersz polecenia i zamykające ogrodzenie. Gdyby klasa nie wskazywała języka, powstałoby ogrodzenie bez nazwy i bez podświetlania składni na GitHubie.
6. Sklejenie i zapis: między blokami wstawiane są puste linie, a całość zapisywana jest jako plik .md. Po wklejeniu do README nagłówek, akapit z linkiem, lista i blok kodu renderują się tak samo jak w oryginalnym HTML.

Przypadki brzegowe konwersji HTML na Markdown

Jak korzystać z konwertera, żeby wynik był gotowy do publikacji

• Wklejaj jeden spójny fragment – zamiast całego dokumentu z sekcją head lepiej podać treść artykułu albo pojedynczy blok. Elementy takie jak style, skrypty i metadane i tak nie mają odpowiednika w Markdown, a jedynie zwiększają szum przed konwersją.
• Dopasuj tryb wyjścia do odbiorcy – GFM wybierz wtedy, gdy plik ma trafić na GitHuba albo do README, CommonMark gdy dokument ma być neutralny, a MDX gdy w treści świadomie zostawiasz komponenty JSX.
• Pilnuj pustych linii po konwersji – nagłówek, lista i blok kodu muszą być oddzielone pustą linią od sąsiednich akapitów. Jeśli edytor je usunął, dopisz je ręcznie, bo inaczej renderer scali bloki w jeden akapit.
• Sprawdź bloki kodu źródłowo – nazwa języka bierze się z klasy na elemencie code. Gdy w kodzie HTML jej nie było, blok wyjdzie bez podświetlania i trzeba dopisać język po otwierającym ogrodzeniu.
• Przejrzyj wynik przed commitem – konwersja jest deterministyczna, ale to nie znaczy, że zawsze idealna. Najszybciej wyłapiesz problemy, wklejając gotowy plik do podglądu Markdown i porównując go z oryginalną stroną.

Czego konwersja HTML na Markdown nie uwzględnia

• Scalone komórki tabel – rowspan i colspan nie mają odpowiednika w tabelach GFM. Takie komórki są powielane albo pomijane, więc przed konwersją warto rozbić skomplikowaną tabelę na prostszą, jednowierszową siatkę.
• Elementy interaktywne – pola formularzy, listy rozwijane, przyciski i inne kontrolki nie mają składni w Markdown. Zostaną pominięte albo zamienione na tekst, więc formularza nie da się przenieść tą drogą.
• Atrybuty dostępności – role, aria-label i podobne atrybuty znikają razem z całym HTML-em. Jeśli dokument ma pozostać dostępny, opis elementu trzeba przenieść do zwykłego tekstu albo do opisu obrazu.
• Treść w komponentach webowych – to, co trafia do cienia drzewa albo jest wstawiane przez skrypt po stronie przeglądarki, nie istnieje w kodzie źródłowym, więc konwerter nie ma czego odczytać i wynik będzie niepełny.

Najczęstsze pytania

Powiązane narzędzia: konwerter Markdown na HTML, walidator HTML i ekstraktor tekstu z PDF.