Online Markdownin esikatselu ja paikallinen dokumenttirakenne vastaavat erilaisiin kysymyksiin. Online-esikatselussa kysytään: "Toimiiko tämä Markdown selkeästi yleisessä esikatselussa ja onko ilmeisiä kirjoitusongelmia?" Paikallinen docs-versio kysyy: "Toimiiko tämä sisältö todellisessa dokumentaatiojärjestelmässämme?"
Molemmat ovat hyödyllisiä. Virhe on pyytää yhtä kerrosta tekemään toisen kerroksen työ. Convertyn Markdown Validator on nopea varhainen tarkistus. Paikallinen dokumenttiversiosi on viimeinen ympäristötarkistus, kun alustakohtaisella renderöinnillä on merkitystä.
Käytä online-esikatselua nopeaan luonnostarkistukseen
Markdownin online-esikatselu on hyödyllinen, kun sisältö on vielä liikkeessä. README-osio, julkaisutiedote, muutoslokimerkintä tai tukiasiakirja voidaan tarkistaa ennen kuin siitä tulee vetopyyntö tai dokumenttien koontiversio.
Esikatselu auttaa saamaan kiinni:
- rikkinäiset pöydät
- Otsikkorakenneongelmat
- puuttuu vaihtoehtoinen teksti
- tyhjät linkit
- merkitsemättömät koodiaidat
- raaka-HTML, joka vaatii tarkistuksen
Tämä on vaihe, jossa nopea palaute on tärkeämpää kuin täydellinen ympäristön tarkkuus.
Käytä paikallista docs-koontiversiota lopulliseen renderöintiin
Paikallinen dokumenttiversio on oikea kerros, kun lopullisella alustalla on mukautettu toiminta. Monet asiakirjajärjestelmät muuttavat Markdownia komponenttien, reitityksen, syntaksin korostuksen, mukautettujen huomiotekstien tai kehyskohtaisen tyylin avulla.
Vain paikallinen koontiversio voi näyttää, toimiiko sisältö kyseisessä ympäristössä. Jos sivulla käytetään mukautettuja komponentteja, tuotuja katkelmia tai tuotekohtaista hahmonnusta, selaimen esikatselun tulee olla ensimmäinen, ei viimeinen.
Paras työnkulku käyttää molempia
Käytä online-esikatselua lähteen puhdistamiseen. Käytä paikallista koontiversiota määränpään vahvistamiseen.
Tämä järjestys säästää aikaa, koska paikallinen koontiversio ei enää havaitse perusmarkdown-virheitä. Se voi keskittyä alustakohtaiseen käyttäytymiseen, jonka se voi ainutlaatuisesti testata.
Käytännön varhaisen tarkastelun työnkulkua varten on artikkeli Kuinka esikatsella GitHub-Flavored Markdown ennen kuin sitoudut. Katso tuote- ja asiakirjojen vaihdot artikkelista Kuinka tuote- ja dokumenttitiimit voivat tarkistaa merkinnän muotoilua menettämättä.
Avaa Markdown Validator, kun tarvitset nopean online-esikatselukerroksen, ennen kuin siirrät saman sisällön paikalliseen dokumenttikoontiversioon tai lopulliseen julkaisun esikatseluun.
