Online Markdown pregled i lokalni docs build odgovaraju na različita pitanja. Online pregled pita: "Renderira li se ovaj Markdown uredno u općem pregledu i postoje li očiti autorski problemi?" Lokalni docs build pita: "Radi li ovaj sadržaj unutar našeg stvarnog dokumentacijskog sustava?"
Oba sloja su korisna. Pogreška je očekivati da jedan sloj radi posao drugoga. Convertyjev validator Markdowna brz je rani check. Vaš lokalni docs build ostaje završna provjera okruženja kada je bitno renderiranje specifično za platformu.
Koristite online pregled za brzu provjeru skice
Online Markdown pregled koristan je dok se sadržaj još mijenja. README odjeljak, release note, changelog unos ili support dokument možete provjeriti prije nego što postane pull request ili docs build.
Pregled pomaže uhvatiti:
- tablice koje izgledaju slomljeno
- probleme u strukturi naslova
- nedostajući alt tekst
- prazne linkove
- code fenceove bez oznake jezika
- sirovi HTML koji treba pregled
To je faza u kojoj je brza povratna informacija važnija od potpune točnosti završnog okruženja.
Koristite lokalni docs build za završno renderiranje
Lokalni docs build pravi je sloj kada završna platforma ima prilagođeno ponašanje. Mnogi docs sustavi provlače Markdown kroz komponente, routing, syntax highlighting, prilagođene calloute ili styling specifičan za framework.
Samo lokalni build može pokazati radi li sadržaj u tom okruženju. Ako stranica koristi prilagođene komponente, uvezene snippetove ili renderiranje specifično za proizvod, pregled u pregledniku treba doći prije završne provjere, a ne umjesto nje.
Najbolji workflow koristi oba sloja
Koristite online pregled za čišćenje izvora. Koristite lokalni build za provjeru odredišta.
Taj redoslijed štedi vrijeme jer lokalni build više ne hvata osnovne Markdown pogreške. Može se usredotočiti na ponašanje specifično za platformu koje jedino on može testirati.
Za praktičan workflow rane provjere pročitajte Kako pregledati GitHub-Flavored Markdown prije commita. Za product i docs handoffe pročitajte Kako product i docs timovi mogu pregledati Markdown bez gubitka formatiranja.
Otvorite validator Markdowna kada trebate brz online sloj pregleda prije nego što isti sadržaj premjestite u lokalni docs build ili završni pregled prije objave.
