Jak przekonwertować Markdown na PDF (bloki kodu i tabele nietknięte)

Markdown to miejsce, gdzie rzeczy się pisze — README, notatki ze spotkań, specyfikacje, dokumentacja. PDF to miejsce, gdzie rzeczy się wysyła: klientowi, który nie otworzy pliku .md, menedżerowi, który chce załącznika, na drukarkę. Między jednym a drugim jest jedna konwersja i nie powinieneś musieć instalować pandoca i dystrybucji LaTeX-a, żeby ją przejść.

Haczyk większości szybkich dróg polega na tym, że masakrują dokładnie te części, od których zależą dokumenty techniczne: bloki kodu zapadają się w krój proporcjonalny, tabele drukują się jako ściana znaków |, a zagnieżdżone listy się spłaszczają. Konwerter jest tu użyteczny tylko, jeśli kod i tabele przeżyją — i taką poprzeczkę trzyma ten poradnik.

Jak konwertować — krok po kroku

🔒 pdfty.com/en/tools/markdown-to-pdf

Co dokładnie się renderuje

Konwerter obsługuje standardowy Markdown plus rozszerzenia, które mają znaczenie w pisaniu technicznym:

• Nagłówki — hierarchia rozmiarów, z subtelnymi liniami pod H1 i H2
• Ogrodzone bloki kodu — monospace, jasnoszare tło, zachowane wcięcia, kolorowanie składni dla popularnych języków
• Kod w linii — znajome stylowanie szarego chipa
• Tabele — tabele z kreskami w stylu GitHuba stają się tabelami z obramowaniem i cieniowanym wierszem nagłówka
• Cytaty blokowe — lewa krawędź, przygaszony tekst
• Listy — numerowane, punktowane, zagnieżdżone
• Linki — pozostają klikalnymi linkami w PDF-ie
• Obrazy po URL-u — obrazy ![](https://…) są pobierane i osadzane

Strona jest składana w wygodnej szerokości czytania z hojnymi marginesami — bliżej „wewnętrznego dokumentu, który wygląda na skończony” niż surowego wydruku z przeglądarki.

Co się NIE renderuje

Sekcja szczerości. Markdown ma dialekty, a to narzędzie implementuje standardowy Markdown + tabele + ogrodzony kod, nie pełny smak GitHuba:

• Listy zadań (- [ ] todo) drukują się jako dosłowne nawiasy, nie checkboxy.
• Przekreślenie (~~tekst~~) nie jest konwertowane — tyldy zostają.
• Lokalne obrazy (![](./diagrams/arch.png)) nie mogą się pojawić: wgrywasz jeden plik, a serwer nie ma dostępu do plików leżących obok na twoim dysku. Hostuj obraz pod URL-em albo spodziewaj się luki.
• Bloki Mermaid / matematyka renderują się jako zwykłe bloki kodu, nie diagramy czy równania.
• Brak własnych motywów — jeden wbudowany arkusz stylów, bez wgrywania CSS.

Darmowe alternatywy lokalne

pandoc — kanoniczny konwerter: pandoc README.md -o readme.pdf. Znakomity wynik i nieskończenie konfigurowalny, ale wyjście PDF wymaga silnika LaTeX (często 1–4 GB instalacji). Warto, jeśli konwertujesz dokumenty co tydzień; absurd dla jednego README.

Rozszerzenia VS Code (np. „Markdown PDF”) — wygodne, jeśli i tak żyjesz w VS Code; jakość wyniku zależy od rozszerzenia i motywu.

Podgląd w przeglądarce + druk: wyrenderuj Markdown gdziekolwiek, gdzie się podgląda (wiele edytorów serwuje podgląd HTML), potem Ctrl/Cmd+P → Zapisz jako PDF. Darmowe i lokalne, ale dziedziczysz dziwactwa druku przeglądarki: nagłówki/stopki z URL-em, o ile ich nie wyłączysz, i podziały stron lądujące w środku bloku kodu.

macOS: brak wbudowanego renderera Markdownu — Podgląd i TextEdit traktują .md jak zwykły tekst, więc zobaczyłbyś surowe kratki i gwiazdki.

Praktyczne pułapki

• Podziały stron są automatyczne. Długie bloki kodu mogą rozdzielić się między stronami. Nie ma ręcznego znacznika podziału strony; silnik łamie tam, gdzie trzeba.
• Bardzo szerokie tabele i długie linie kodu są skalowane lub ucinane do szerokości treści — 200-znakowy wiersz tabeli nie zmieści się z wdziękiem na pionowej stronie. Skracaj linie, gdzie się da.
• Front matter (--- YAML na górze pliku) jest traktowany jako treść, nie ukrywany — usuń go przed konwersją, jeśli nie chcesz go w druku. (Blok --- na samej górze może też wyrenderować się jako pozioma linia plus tekst, zależnie od formatowania.)
• Skróty emoji jak :rocket: zostają dosłowne; prawdziwe wklejone znaki emoji zwykle się renderują.
• Sprawdź cele linków. Linki względne ([docs](./docs/setup.md)) przeżywają jako linki, ale po wydrukowaniu wskazują donikąd.

Gdy PDF już istnieje, działa zwykła skrzynka narzędziowa: ostempluj go Nagłówkiem i stopką dla liczników stron, połącz rozdziały narzędziem Połącz albo odchudź ten pełen obrazów Kompresją.

Częste pytania

Czy bloki kodu zachowują kolorowanie składni?

Tak — ogrodzone bloki ze wskazówką języka (```python) dostają kolorowanie; bez wskazówki są zwykłym monospace na szarości. Tak czy inaczej wcięcia są zachowane dokładnie.

Czy tabele naprawdę renderują się jako tabele?

Tak — tabele z kreskami (styl GitHuba) stają się tabelami z obramowaniem i cieniowanym wierszem nagłówka. Dwukropki wyrównania są respektowane przez parser.

Dlaczego w PDF-ie brakuje mojego obrazu?

Jest wskazany ścieżką lokalną. Wgrywasz jeden plik .md, więc ./images/x.png wskazuje donikąd. Użyj pełnego URL-a https:// albo konwertuj lokalnie pandokiem, gdzie ścieżki względne się rozwiązują.

Czy mogę przekonwertować README prosto z GitHuba?

Najpierw pobierz surowy plik .md, potem go wgraj. Odznaki i obrazy hostowane pod pełnymi URL-ami zwykle przechodzą; funkcje tylko GitHubowe (listy zadań, mermaid) nie — zobacz listę wyżej.

Czy mogę zmienić fonty, marginesy lub kolory?

Nie w tym narzędziu — dostarcza jeden celowo czysty arkusz stylów. Dla brandowanego designu idź przez HTML do PDF z własnym CSS-em.

Czy jest limit rozmiaru lub stron?

Darmowy plan: 20 MB na plik i 10 operacji dziennie — dla plików tekstowych to w praktyce brak limitu. PDF-y wynikowe powyżej 50 stron generują się bez problemu z jednego źródła Markdown.

Czy mój dokument jest prywatny?

Transfer przez HTTPS, a pliki są automatycznie usuwane w ciągu 1 godziny. Dla poufnych materiałów, których nie możesz wgrywać, lokalną drogą jest pandoc.

Czy mogę pójść w drugą stronę — PDF do Markdownu?

Nie bezpośrednio. Najbliżej jest Wyodrębnij tekst (zwykły tekst, bez formatowania) albo PDF do Word i sprzątanie od tego miejsca.