Linter Markdown z wytłumaczeniami po ludzku
Markdown wygląda na prosty, dopóki Twoje README, dokumentacja albo wpis na blogu nie zaczynają wyglądać niespójnie: różne znaczniki list (styl listy), białe znaki na końcu linii, nagłówki, które przeskakują poziom (poziomy nagłówków), bloki kodu z trzema backtickami bez tagu języka. Renderer i tak coś pokaże, ale efekt jest niechlujny, a szum w diffie ogromny.
To narzędzie odpala ten sam silnik co CLI `markdownlint` (markdownlint) na Twoim tekście. Dostajesz ponumerowaną listę problemów, każdy z kodem reguły (`MD009`, `MD040`...), krótkim opisem i podglądem poprawki tam, gdzie da się ją zrobić automatycznie. Klikasz w wiersz, textarea zjeżdża do tej linii.
Cztery presety pokrywają typowe wybory: Recommended (domyślny, rozsądny dla każdego projektu), GitHub (zgodny z GFM), Strict (80 kolumn szerokości plus zero duplikatów nagłówków), Custom rules (wszystko włączone). Włącz Fix mode, żeby zobaczyć posprzątany tekst i skopiować go jednym kliknięciem.
Jak używać
- Wklej swój Markdown w duże pole tekstowe po lewej. Domyślnie ładuje się mała próbka z celowymi błędami, żeby narzędzie miało co pokazać od razu.
- Wybierz preset u góry: Recommended dla prawie każdego projektu, GitHub kiedy plik wyląduje na GitHubie albo GitLabie, Strict dla dokumentacji technicznej z 80-kolumnowymi liniami i wszystkimi regułami, Custom rules żeby włączyć każde możliwe sprawdzenie.
- Kliknij "Run lint". Prawy panel wypełni się ponumerowaną listą problemów. Każdy pokazuje kod reguły (np. `MD040`), krótki opis, fragment kontekstu i plakietkę "auto-fix", jeśli markdownlint potrafi naprawić go automatycznie.
- Kliknij dowolny wiersz z problemem, żeby przeskoczyć do tej linii w textarea. Linia zostanie zaznaczona, więc możesz ją edytować od ręki. Przydaje się przy triagowaniu kilkudziesięciu problemów bez ręcznego skrolowania.
- Przełącz "Fix mode", żeby zamiast surowego inputu zobaczyć posprzątany output. Wszystkie auto-fixowalne problemy są zastosowane. Te strukturalne (styl nagłówków, tagi języka, błędy merytoryczne) poprawiasz ręcznie.
- Kliknij "Copy", żeby zgrabić surowy input albo posprzątany output (zależnie od Fix mode). To ten string, który wklejasz z powrotem do swojego README albo dokumentu.
- Przeczytaj FAQ poniżej, jeśli chcesz wiedzieć, co znaczy konkretna reguła albo który preset pasuje do konwencji Twojego zespołu. Każdy kod reguły linkuje do krótkiego wytłumaczenia po ludzku.
Kiedy się przydaje
Sześć konkretnych sytuacji, w których linter Markdown oszczędza realny czas:
- Sprawdzasz README przed pushem. Napisałeś 300 linii, w pierwszej połowie używałeś `-` na bullety, w drugiej `*`, trzy bloki kodu nie mają tagu języka, więc syntax highlighter na GitHubie renderuje je jako szare prostokąty. Lintujesz, naprawiasz, pushujesz.
- Stawiasz dokumentację (Astro, Hugo, Docusaurus, MkDocs). Generator pakuje każdą stronę w layout. Słaby Markdown daje rozjechane tabele, popsute kotwice linków i niespójną hierarchię w sidebarze. Linting przed dodaniem stron łapie to wszystko.
- Robisz code review PR-a kolegi. Wklejał Markdown z Notion, które uwielbia produkować białe znaki na końcu linii i inteligentne cudzysłowy. Lintujesz, wklejasz listę w komentarz PR-a, "tu jest 12 rzeczy do poprawy".
- Czyścisz tutorial przed publikacją na Medium albo dev.to. Obie platformy mają własne dziwactwa Markdownowe. Przepuszczenie tekstu przez Strict lokalnie eliminuje zgadywanie "co się gdzie wyrenderuje".
- Migrujesz z innej platformy. Wyeksportowałeś posty z WordPressa, Ghosta albo Substacka jako Markdown. Są pełne wpisanych w środek tagów HTML `<div>`, gołych URL-i, które powinny być auto-linkowane, i nagłówków zaczynających się od H2. Linter wyłapuje wszystkie.
- Ustawiasz pre-commit hook w CI. Te same reguły, których używasz tutaj, lądują w pliku konfiguracyjnym repo, dostajesz zielony check w CI i przyjazny komentarz na każdym PR, który je łamie.