Markdown-virheet on halvempaa korjata ennen kuin ne tulevat arkistoon. Kun README-päivitys, muutoslokimerkintä tai asiakirjojen muistiinpano on tehty, tarkistuskeskustelu siirtyy usein itse sisällöstä pieniin renderöintiongelmiin: taulukko rikki, otsikon taso hyppäsi, linkin otsikko on tyhjä tai koodiaita menettää kielensä.
A GitHub-flavored Markdown preview gives you a fast check before that happens. Se ei korvaa lopullista tarkistusta kohdejärjestelmässä, mutta se havaitsee ongelmat, jotka on helpoin ohittaa kirjoittaessa nopeasti. Convertyn Markdown Validator yhdistää live-esikatselun tarkennettuihin varoituksiin yleisistä kirjoitusongelmista.
Miksi GitHub-makuinen Markdown tarvitsee oman esikatselupassin
GitHub-makuinen Markdown sisältää käytännöllisen syntaksin, johon monet tekniset tiimit luottavat, mukaan lukien taulukot, tehtäväluettelot, koodiaidat, linkit ja upotettu HTML-käsittely. Pelkkä tekstieditori voi auttaa sinua kirjoittamaan sisällön, mutta se ei välttämättä näytä, kuinka nämä elementit hahmonnetaan.
Sillä on merkitystä, koska Markdown-asiakirjan visuaalinen muoto vaikuttaa tarkasteluun. Taulukko, joka näyttää tasaisesti lähteessä, voi silti hahmontaa huonosti. Otsikkohierarkia, joka tuntuu itsestään selvältä kirjoittamisen aikana, voi muuttua hämmentäväksi muuntamisen jälkeen. Koodiaita ilman kielitarraa voi vaikeuttaa esimerkkien skannausta.
Esikatselun tarkoitus ei ole hioa jokaista lausetta. Sen tarkoitus on varmistaa, että dokumentti toimii luettavana Markdown-sivuna ennen kuin se siirtyy seuraavaan workflow'hun.
Käytännöllinen pre-commit Markdown -työnkulku
Käytä selaimen esikatselua, kun asiakirjaa on edelleen helppo muuttaa.
- Avaa Markdown Validator.
- Liitä README-osio, asiakirjojen päivitys, muutoslokimerkintä tai julkaisutiedote.
- Tarkista hahmonnetun esikatselun asettelu yllätyksiä.
- Lue varoitusluettelo otsikoiden hyppyistä, päällekkäisestä H1-käytöstä, puuttuvasta kuvan vaihtoehtoisesta tekstistä, tyhjistä linkeistä ja merkitsemättömistä koodiaidoista.
- Korjaa lähdedokumentti ennen sen sitomista tai liittämistä lopulliseen järjestelmään.
Tämä työnkulku on tarkoituksella lyhyt. Et siirrä asiakirjoja uuteen luontialustaan. Annat Markdownille yhden kohdistetun tarkastuspassin, ennen kuin arkistosta tulee tarkistuspinta.
Mitä esikatselu voi saada aikaisin
A useful Markdown preview should help with the mistakes that slow reviews down:
- taulukot, jotka eivät lue puhtaasti
- otsikot, jotka ohittavat tasoja
- useita H1-otsikoita yhdessä asiakirjassa
- linkkejä ilman hyödyllisiä tarroja
- kuvat ilman vaihtoehtoista tekstiä
- koodiaidat ilman kielitarroja
- raaka-HTML, jota tulee käsitellä huolellisesti
Nämä tarkistukset ovat erityisen hyödyllisiä tekniselle sisällölle, koska pienet rakenneongelmat voivat vaikeuttaa esimerkkien luottamista.
Kun selaimen esikatselu ei riitä
Selaimen esikatselu on varhainen tarkistus, ei lopullinen totuuden lähde jokaiselle asiakirja-alustalle. Jos lopullinen kohde käyttää mukautettuja komponentteja, erityisiä Markdown-laajennuksia tai tuotekohtaista hahmonnusta, sinun on silti tarkistettava sivu kyseisessä ympäristössä.
Se raja on tärkeä. Converty is useful before the heavier system takes over. Se antaa kirjoittajille, kehittäjille ja arvioijille nopean tavan havaita tavalliset Markdown-ongelmat odottamatta dokumenttien koontiversiota tai vetopyynnön tarkistusta.
Laajempia sisällön laadunvarmistusohjeita löytyy artikkelista How to Catch Down Issues Before Publishing. Jatka tiimien vaihdoissa kohdasta Kuinka tuote- ja dokumenttitiimit voivat tarkistaa merkinnät muotoilua menettämättä.
Avaa Markdown Validator ennen Markdownin committaamista, kun haluat esikatselun ja varoitukset yhteen paikkaan.
