Markdown er nógu sveigjanlegt til að leyfa mikið og nógu einfalt til að fela mistök. Draft getur litið snyrtilega út í hráum texta en samt haft heading-stökk, tóma tengla, vantaðan alt text, code fence án tungumáls eða lista sem renderast öðruvísi en höfundurinn bjóst við.
Converty Markdown-staðfestirinn sameinar lifandi GitHub-flavored forskoðun og markvissar höfundaviðvaranir. Hann er ekki hugsaður sem þungt lint-kerfi. Hann er hraður pre-publish pass sem hjálpar þér að laga algeng vandamál áður en efnið fer í skjöl, CMS, changelog eða issue.
Forskoðun svarar ekki öllum spurningum
Það er nauðsynlegt að sjá renderaða útgáfu. Hún sýnir hvort headings, töflur, tilvitnanir, listar og code blocks birtast eins og þú bjóst við. En góð forskoðun er ekki nóg. Hún getur samt renderað efni sem er veikara en það ætti að vera.
Þess vegna skipta viðvaranir máli. Vantar alt texta? Er linkur tómur? Hoppar heading úr H2 í H4? Er code fence án tungumálsmerkingar? Þetta eru ekki alltaf parsing-villur, en þau eru útgáfugallar.
Hvað á að skoða fyrir birtingu?
Gagnlegur Markdown-pass er stuttur:
- Lestu renderaða forskoðun frá byrjun til enda.
- Athugaðu að heading-uppbygging sé rökrétt.
- Staðfestu að linkar hafi áfangastað og skýran anchor text.
- Bættu alt texta við myndir.
- Merktu code fence með tungumáli þegar það hjálpar lesandanum.
- Skoðaðu töflur og lista í renderuðu formi, ekki bara hráum texta.
Þessi atriði skipta sérstaklega máli þegar efnið fer á milli GitHub, CMS eða skjalaumhverfis.
Hrátt HTML þarf varúð
Markdown-draftar innihalda stundum HTML. Það getur verið viljandi, komið úr gömlum CMS-exporti eða verið fljótleg lausn. Forskoðun sem leyfir HTML þarf samt að hreinsa óörugga hluti eins og script og event handlera.
Þess vegna notar validatorinn hreinsaða forskoðun. Þú færð raunhæfara útlit án þess að treysta blindandi óyfirförnu markup.
Ef þú ert að meta hvort efnið eigi yfirleitt heima í vafratengdu tóli, skoðaðu Eru online-breytar öruggir fyrir vinnuskrár?.
Hvenær á að nota fulla docs build?
Markdown-staðfestirinn grípur algeng source-vandamál. Hann kemur ekki í stað lokaúttektar í raunverulegu útgáfuumhverfi. Ef docs kerfið þitt hefur sérstök components, MDX, macros eða eigin linkareglur þarftu enn að prófa þar.
Góða röðin er samt: lagaðu algengu höfundamistökin fyrst, farðu svo í destination-specific review. Hvernig skjalateymi staðfesta Markdown fyrir birtingu á GitHub eða í CMS fjallar um þá stærri docs-útgáfu.
Gerðu review áður en efnið dreifist
Auðveldast er að laga Markdown þegar það er enn ein skrá eða einn textareitur. Þegar það er komið í repository, CMS, þýðingarkerfi eða útgáfukeðju verður hver smávilla dýrari.
Opnaðu Markdown-staðfestinn, límdu inn draftið og lagaðu vandamálin á meðan efnið er enn hreyfanlegt. Fyrir launch-vinnu sem inniheldur líka slugga og favicon, skoðaðu Hvernig efnisteymi undirbúa slugga, Markdown og favicon fyrir nýja útgáfu.
