Chyby markdown je lacnejšie opraviť skôr, ako vstúpia do úložiska. Po potvrdení aktualizácie README, záznamu zmien alebo poznámky k dokumentu sa konverzácia o recenzii často presunie od samotného obsahu k malým problémom s vykresľovaním: tabuľka sa pokazila, úroveň nadpisu preskočila, štítok odkazu je prázdny alebo plot kódu stratil svoj jazyk.
Ukážka Markdown s príchuťou GitHub vám poskytuje rýchlu kontrolu, kým sa tak stane. Nenahrádza záverečnú recenziu v cieľovom systéme, ale zachytáva problémy, ktoré je najjednoduchšie prehliadnuť pri rýchlom písaní. Converty's Markdown Validator kombinuje živú ukážku so sústredenými upozorneniami na bežné problémy s tvorbou.
Prečo Markdown s príchuťou GitHub potrebuje svoj vlastný náhľad
Markdown s príchuťou GitHub obsahuje praktickú syntax, na ktorú sa spolieha mnoho technických tímov, vrátane tabuliek, zoznamov úloh, ohraničení kódu, odkazov a riadeného spracovania HTML. Editor obyčajného textu vám môže pomôcť napísať obsah, ale nemusí ukázať, ako sa tieto prvky vykreslia.
To je dôležité, pretože vizuálny tvar dokumentu Markdown ovplyvňuje kontrolu. Tabuľka, ktorá vyzerá v zdrojovom kóde zarovnaná, sa môže stále vykresľovať zle. Hierarchia nadpisov, ktorá je pri písaní zrejmá, sa po konverzii môže stať mätúcou. Kódový plot bez jazykového označenia môže sťažiť skenovanie príkladov.
Preview pass nie je o leštení každej vety. Ide o to, aby sa dokument pred ďalším pracovným postupom správal ako čitateľná stránka Markdown.
Praktický pracovný postup Markdown vopred
Použite náhľad prehliadača, kým sa dokument stále ľahko mení.
- Otvorte Overenie známok.
- Prilepte sekciu README, aktualizáciu dokumentov, záznam protokolu zmien alebo poznámku k vydaniu.
- Skontrolujte vykreslený náhľad, či neobsahuje prekvapenia rozloženia.
- Prečítajte si zoznam upozornení na skoky v nadpise, duplicitné použitie H1, chýbajúci alternatívny text obrázka, prázdne odkazy a neoznačené kódové ploty.
- Opravte zdrojový dokument pred jeho potvrdením alebo vložením do konečného systému.
Tento pracovný postup je zámerne krátky. Nepresúvate dokumenty na novú platformu na tvorbu obsahu. Dávate Markdown jeden cielený kontrolný priechod predtým, ako sa úložisko stane povrchom kontroly.
Čo môže ukážka zachytiť už skôr
Užitočný náhľad Markdown by mal pomôcť s chybami, ktoré spomaľujú recenzie:
- tabuľky, ktoré sa nečítajú čisto
- nadpisy, ktoré preskakujú úrovne
- viacero nadpisov H1 v jednom dokumente
- odkazy bez užitočných označení
- obrázky bez alternatívneho textu
- kódové ploty bez jazykových označení
- surové HTML, s ktorým by sa malo zaobchádzať opatrne
Tieto kontroly sú užitočné najmä pre technický obsah, pretože malé problémy so štruktúrou môžu sťažiť dôveryhodnosť príkladov.
Keď ukážka prehliadača nestačí
Ukážka prehliadača je skorá kontrola, nie konečný zdroj pravdy pre každú platformu dokumentov. Ak váš konečný cieľ používa vlastné komponenty, špeciálne rozšírenia Markdown alebo vykresľovanie špecifické pre produkt, musíte stránku v danom prostredí skontrolovať.
Tá hranica je dôležitá. Konverzia je užitočná skôr, ako prevezme ťažší systém. Poskytuje autorom, vývojárom a recenzentom rýchly spôsob, ako zachytiť bežné problémy Markdown bez čakania na zostavenie dokumentov alebo kontrolu žiadosti o stiahnutie.
Širšie pokyny na kontrolu kvality obsahu nájdete v časti Ako zachytiť problémy so znižovaním cien pred zverejnením. Pri odovzdávaní tímov pokračujte v časti Ako môžu tímy produktov a dokumentov kontrolovať Markdown bez straty formátovania.
Pred vykonaním Markdown otvorte Markdown Validator, keď chcete náhľad a upozornenia na jednom mieste.
