Błędy Markdown są tańsze do naprawienia, zanim trafią do repozytorium. Po zatwierdzeniu aktualizacji README, wpisu w dzienniku zmian lub notatki w dokumencie dyskusja często przenosi się z samej treści na drobne problemy z renderowaniem: uszkodzona tabela, przeskoczony poziom nagłówka, etykieta łącza jest pusta lub bariera kodu straciła swój język.
Podgląd Markdown w wersji GitHub pozwala szybko sprawdzić, zanim to nastąpi. Nie zastępuje końcowego przeglądu w systemie docelowym, ale wyłapuje problemy, które najłatwiej przeoczyć podczas szybkiego pisania. Markdown Validator firmy Converty łączy podgląd na żywo z ukierunkowanymi ostrzeżeniami dotyczącymi typowych problemów z tworzeniem.
Dlaczego Markdown w wersji GitHub potrzebuje własnej wersji zapoznawczej
Markdown w wersji GitHub zawiera praktyczną składnię, na której opiera się wiele zespołów technicznych, w tym tabele, listy zadań, ogrodzenia kodu, łącza i wbudowaną obsługę HTML. Edytor zwykłego tekstu może pomóc w napisaniu treści, ale może nie pokazać, jak te elementy będą renderowane.
Ma to znaczenie, ponieważ wizualny kształt dokumentu Markdown wpływa na recenzję. Tabela, która wygląda na wyrównaną w źródle, może nadal być słabo renderowana. Hierarchia nagłówków, która wydaje się oczywista podczas pisania, może stać się myląca po konwersji. Ogrodzenie kodu bez etykiety językowej może utrudnić skanowanie przykładów.
Przepustka podglądowa nie polega na dopracowaniu każdego zdania. Chodzi o to, aby dokument zachowywał się jak czytelna strona Markdown, zanim trafi do następnego przepływu pracy.
Praktyczny przepływ pracy przed zatwierdzeniem Markdown
Korzystaj z podglądu w przeglądarce, gdy dokument jest jeszcze łatwy do zmiany.
- Otwórz Weryfikator Markdown.
- Wklej sekcję README, aktualizację dokumentacji, wpis dziennika zmian lub informację o wersji.
- Przejrzyj renderowany podgląd pod kątem niespodzianek związanych z układem.
- Przeczytaj listę ostrzeżeń dotyczącą przeskoków nagłówków, zduplikowanego użycia H1, brakującego tekstu alternatywnego obrazu, pustych linków i nieoznaczonych barier w kodzie.
- Napraw dokument źródłowy przed zatwierdzeniem lub wklejeniem go do systemu końcowego.
Ten przepływ pracy jest celowo krótki. Nie przenosisz dokumentów na nową platformę do tworzenia. Dajesz Markdownowi jeden ukierunkowany przebieg inspekcji, zanim repozytorium stanie się powierzchnią recenzji.
Co podgląd może wykryć wcześniej
Przydatny podgląd Markdown powinien pomóc w wyeliminowaniu błędów spowalniających recenzje:
- tabele, które nie czytają czysto
- nagłówki pomijające poziomy
- wiele nagłówków H1 w jednym dokumencie
- linki bez przydatnych etykiet
- obrazy bez tekstu alternatywnego
- ogrodzenia kodowe bez etykiet językowych
- surowy kod HTML, który należy traktować ostrożnie
Kontrole te są szczególnie przydatne w przypadku treści technicznych, ponieważ drobne problemy ze strukturą mogą sprawić, że przykładom trudniej będzie zaufać.
Gdy podgląd w przeglądarce nie wystarczy
Podgląd w przeglądarce to wczesna kontrola, a nie ostateczne źródło informacji na temat każdej platformy dokumentów. Jeśli Twoje miejsce docelowe korzysta z niestandardowych komponentów, specjalnych rozszerzeń Markdown lub renderowania specyficznego dla produktu, nadal musisz sprawdzić stronę w tym środowisku.
Ta granica jest ważna. Konwersja jest przydatna, zanim cięższy system przejmie kontrolę. Daje autorom, programistom i recenzentom szybki sposób na wykrycie typowych problemów z Markdownem bez czekania na sprawdzenie kompilacji dokumentów lub żądania ściągnięcia.
Aby uzyskać szersze wskazówki dotyczące kontroli jakości treści, przeczytaj artykuł Jak wykryć problemy z przeceną przed publikacją. W przypadku przekazywania zespołów przejdź do artykułu Jak zespoły ds. produktów i dokumentów mogą przeglądać przeceny bez utraty formatowania.
Otwórz Weryfikator Markdown przed zatwierdzeniem Markdown, jeśli chcesz mieć podgląd i ostrzeżenia w jednym miejscu.
