Markdown-ongelmat ilmoittavat harvoin itsestään kirjoitushetkellä. Dokumentti voi näyttää harmittomalta tekstieditorissa ja silti julkaistuaan sisältää rikkoutuneen otsikkorakenteen, tyhjän linkin, nimeämättömän kuvan tai koodilohkon, joka menettää kielikontekstinsa. Siksi "se renderöityy" ei ole sama asia kuin "se on valmis".
Yleisin virhe on käsitellä Markdownin tarkistusta yhtenä tehtävänä. Se on oikeasti kaksi toisiinsa liittyvää tarkistusta. Ensin pitää nähdä renderöity tulos. Sen jälkeen pitää löytää rakenteelliset virheet, jotka renderöity tulos voi peittää.
Convertyn Markdown-tarkistin on tehty juuri tätä paria varten. Se antaa GitHub-tyylisen live-esikatselun ja merkitsee käytännön ongelmia, kuten otsikkohyppyjä, useita H1-otsikoita, puuttuvia kuvan alt-tekstejä, tyhjiä linkkejä ja kielimerkinnättömiä koodiaitoja.
Esikatsele ensin, koska muotoiluvirheet on helpompi nähdä kuin kuvitella
Markdown on yksinkertaista, kunnes se kulkee toisen renderöijän läpi kuin se, jota ajattelit. Taulukko, joka näytti selvältä raakatekstissä, voi muuttua lukukelvottomaksi. Sisäkkäinen lista voi litistyä. Koodilohko voi muuttua kappaleeksi, jos aitaus on väärä. Lainaus voi nielaista seuraavan osion, jos välistys on pielessä.
Nämä eivät ole teoreettisia ongelmia. Ne ovat juuri niitä virheitä, jotka menevät läpi, jos ainoa tarkistus on raakatekstin lukeminen. Renderöity esikatselu sulkee aukon nopeasti.
Validointi löytää virheitä, joita esikatselu ei paljasta
Hyvältä näyttävä sivu voi silti olla rakenteellisesti heikko. Otsikkotaso voi hypätä H2:sta H4:ään. Linkki voi olla tyhjä. Kuva voi puuttua alt-tekstistä. Koodilohko voi olla vailla kieltä, jolloin korostus ja myöhempi uudelleenkäyttö heikkenevät.
Siksi validointi täydentää esikatselua. Esikatselu vastaa visuaaliseen kysymykseen. Validointi vastaa toimitukselliseen ja ylläpidolliseen kysymykseen: selviääkö dokumentti seuraavasta handoffista?
Käytännön tarkistus ennen julkaisua
Nopea Markdown-työnkulku näyttää tältä:
- Avaa Markdown-tarkistin.
- Liitä julkaistava luonnos.
- Lue renderöity esikatselu kuten lukija.
- Korjaa varoitukset otsikoista, linkeistä, kuvista ja koodiaidoista.
- Kopioi puhdistettu versio repositorioon, CMS:ään tai dokumentaatioalustaan.
Tämä ei korvaa lopullista tarkistusta kohdejärjestelmässä. Se poistaa yleiset lähdevirheet ennen kuin kohdejärjestelmästä tulee ensimmäinen kunnollinen tarkistin.
Raw HTML tarvitsee varovaisuutta
Markdown-dokumenteissa on usein pieniä HTML-katkelmia. Ne voivat olla peräisin vanhasta CMS-viennistä, layoutin korjauksesta tai kiireisestä julkaisuhetkestä. Niitä ei pidä sivuuttaa, mutta niitä ei pidä myöskään luottaa sokeasti.
Sanitoitu esikatselu auttaa näkemään, miltä sekoitettu sisältö näyttää ilman, että jokainen HTML-pätkä saa rajattomasti valtaa. Jos dokumentti sisältää arkaluonteista sisäistä materiaalia, arvioi ensin, sopiiko se lainkaan selainpohjaiseen työkaluun. Tähän liittyy myös online-muuntimien turvallisuutta käsittelevä opas.
Tarkista Markdown silloin, kun sitä on vielä helppo muuttaa
Markdown-virheet ovat halpoja korjata ennen julkaisua ja ärsyttäviä korjata sen jälkeen, kun sisältö on jo repossa, CMS:ssä tai tuotepinnassa. Paras tarkistus on lyhyt, toistettava ja tarpeeksi varhainen.
Avaa Markdown-tarkistin, kun seuraava julkaisu tarvitsee nopean katselmoinnin, käytä usein kysyttyjä kysymyksiä yleisiin työnkulkuodotuksiin ja jatka artikkeliin Kuinka dokumentaatiotiimit validoivat Markdownin ennen julkaisua GitHubiin tai CMS:ään, kun kyseessä on laajempi docs-työnkulku.
