Markdowni probleemid ei anna endast tavaliselt kirjutamise hetkel märku. Dokument võib tekstiredaktoris süütu välja näha ja ikkagi avalduda katkise pealkirjastruktuuri, tühja lingi, sildita pildi või koodiplokiga, mis kaotab docs'i kopeerimisel keelekonteksti. Seetõttu ei tähenda "see renderdub" sama, mis "see on valmis".
Kõige tavalisem viga on käsitleda Markdowni ülevaatust ühe ülesandena. Tegelikult on see kaks seotud kontrolli. Esiteks pead nägema renderdatud tulemust. Teiseks pead leidma struktuurivead, mida renderdatud tulemus võib peita. Eelvaade vastab visuaalsele küsimusele. Valideerimine vastab toimetuslikule küsimusele.
Just seda paari on Converty Markdowni valideerija mõeldud tegema. See annab live GitHub-flavored Markdowni eelvaate ja märgib praktilised probleemid, nagu pealkirjatasemete hüpped, mitu H1-pealkirja, puuduv pildi alt-tekst, tühjad lingid ja märgistamata koodiplokid. Väärtus pole selles, et Markdown muutuks järsku keeruliseks. Väärtus on selles, et lühike ülevaatus püüab kinni vead, mida on tüütu avastada pärast dokumendi liikumist reposse, CMS-i või tootesse.
Alusta eelvaatest, sest vormindusvigu on lihtsam näha kui ette kujutada
Markdown on lihtne seni, kuni see jõuab teise rendererisse kui see, mida sa ette kujutasid. Tabel, mis tundus puhtas tekstis ilmne, muutub loetamatuks, sest veerud olid ebaühtlased. Pesastatud loend jääb oodatust lamedamaks. Koodiplokk muutub lõiguks, sest fence oli vigane. Tsitaadiplokk neelab järgmise jaotise, sest vahed olid valed.
Need pole teoreetilised probleemid. Just sellised vead lipsavad läbi, kui ainus kontroll on toore Markdowni lugemine. Renderdatud eelvaade sulgeb selle lõhe kiiresti. Sa lõpetad arvamise, milline lõplik dokument välja näeb, ja vaatad tegelikku kuju.
See loeb veel rohkem siis, kui dokument sisaldab segasisu. Release note'id, changelog'i kirjed, README jaotised, migratsioonijuhised ja abikeskuse mustandid ühendavad sageli proosat, pealkirju, koodi, loendeid, tabeleid ja linke. Mida mitmekesisem dokument on, seda vähem usaldusväärne on ainult puhtas tekstis ülelibisemine.
Valideerimine on oluline, sest mõned avaldamisvead on eelvaates nähtamatud
Eelvaade võib endiselt vastuvõetav välja näha, kuigi dokument on struktuurilt nõrk. Klassikaline näide on pealkirjade järjekord. Leht, kus H1-le järgneb H3, võib renderduda kenasti, kuid struktuur on skannimiseks raskem ning ligipääsetavuse ja hilisema taaskasutuse jaoks hapram. Tühjad lingid on sarnased. Kui nähtav tekst näib normaalne, ei pruugi juhuslik ülevaataja märgata, et sihtkoht puudub või on vigane.
Sama kehtib piltide ja koodiplokkide kohta. Alt-tekstita pilt võib eelvaates ilmuda, kuid sisu on vähem ligipääsetav ja vähem teisaldatav. Keelemärgistuseta koodiplokk võib näida loetav, kuid kaotab süntaksikonteksti täpselt seal, kus lugejad ootavad koodi kõige lihtsamat mõistmist.
Converty hoiab need kontrollid meelega kitsana. Eesmärk pole muuta Markdowni raskeks lint-süsteemiks. Eesmärk on tuua nähtavale probleemid, mis kõige sagedamini lõhuvad kirjutamise, ülevaatuse ja avaldamise vahelisi üleandmisi.
Realistlik töövoog release note'ide või docs'i uuenduste jaoks
Oletame, et valmistad ette tooteuuenduse release note'i kirjet. Kirjutasid teksti märkmerakenduses, kopeerisid terminalist koodinäite, lisasid ekraanitõmmise ja linkisid uuele teekonnale. Toores Markdownis tundub kõik mõistlik, kuid dokumendil on mitu võimalust vaikselt ebaõnnestuda.
Praktiline ülevaatusvoog on lühike:
- Kleebi mustand Markdowni valideerijasse.
- Loe renderdatud eelvaadet lõppkasutaja, mitte autori pilguga.
- Kontrolli valideerimiskokkuvõttest struktuurilisi hoiatusi.
- Paranda hoiatused, mis mõjutavad loetavust, ligipääsetavust või avaldamiskindlust.
- Kopeeri puhastatud Markdown tagasi reposse, CMS-i või docs'i süsteemi.
See järjestus on kasulik, sest eraldab visuaalse ülevaatuse struktuursest ülevaatusest ilma sind kahte eri tööriista sundimata. Sa ei vaja täielikku docs build'i, et kinnitada, kas allikas sisaldab juba pealkirjahüpet, tühja linki või märgistamata koodiplokki.
Raw HTML on koht, kus ettevaatus ja praktilisus peavad kohtuma
Markdowni ülevaatuse keerulisem osa on raw HTML. Paljud pärisdokumendid sisaldavad väikseid sisseehitatud HTML-katkeid, eriti kui sisu liigub CMS-toimetajate, docs-süsteemide ja Git-põhiste töövoogude vahel. Probleem on selles, et raw HTML-i hooletu eelvaatamine võib muutuda omaette riskiks, kui renderer on liiga usaldav.
Seetõttu on puhastatud HTML-i käsitlemine oluline. Convertys toetab Markdowni eelvaade puhastatud raw HTML-i, mitte ei käsitle iga sisseehitatud märgendit automaatselt turvalisena. See annab realistlikuma renderduspinna ilma nõudmata, et usaldaksid iga kleebitud fragmenti pimesi.
Siin muutub asjakohaseks ka privaatsusarutelu artiklist Kas veebikonverterid on tööfailide jaoks turvalised? Mida kontrollida enne kleepimist või üleslaadimist. Markdowni mustandid sobivad sageli brauseripõhiseks töövooks, kuid tööriist peaks töö kitsana hoidma. Eelvaata dokumenti, püüa vead kinni ja liigu edasi. Valideerija ei peaks muutuma sinu sisuhalduskihiks.
Mida hoiatusloend kõige paremini kinni püüab
Kõige kasulikumad Markdowni hoiatused on need, mis seostuvad otseselt avaldamisvigadega, mitte abstraktsete stiilivaidlustega.
Pealkirjastruktuur on üks neist. Kui dokument jätab tasemeid vahele või dubleerib põhipealkirja, tunnevad lugejad seda isegi siis, kui nad probleemi nime ei tea. Linkide kvaliteet on teine. Katkised või tühjad lingid jõuavad üllatavalt kaugele tootmisse. Alt-tekstita pildid ja selge märgistuseta koodiplokid on sarnased: kiirustades on neid lihtne maha magada ja pärast avaldamist lihtne kahetseda.
Seetõttu tasub hoiatusloendit lugeda avaldamise kontrollnimekirjana, mitte hindamissüsteemina. Mõte pole saavutada ideoloogilist täiuslikkust. Mõte on eemaldada vead, mis kõige tõenäolisemalt kahjustavad selgust, ligipääsetavust ja usaldust.
Millal brauserikontrollist piisab ja millal mitte
Brauserivalideerija on kõige tugevam enne seda, kui raskemad süsteemid üle võtavad. See sobib mustandi ülevaatuseks, dokumentatsiooni puhastamiseks, changelog'i toimetamiseks, CMS-i ettevalmistuseks ja sisukvaliteedi kontrolliks enne commit'i või kleepimist. See aitab siis, kui tahad kiiret tagasisidet ilma täit build'i käivitamata või ootamata, kuni ülevaataja hiljem ilmsed probleemid leiab.
See ei asenda keskkonnaspetsiifilist renderdust, kui lõplik pind kasutab oma Markdowni reegleid. Kui docs-platvorm teisendab kohandatud komponente, lisab stiile või rakendab tootespetsiifilist renderduskäitumist, pead lõplikku pinda ikkagi testima. Brauseripass tuleb enne seda. See ei tühista seda.
See kompromiss on sama, mida Converty teeb laiemas tööriistakomplektis, mida kirjeldab Tutvustame Convertyt. Toode sobib kõige paremini hõõrdumise eemaldamiseks peamise töövoo ümber olevatest väikestest töödest. See ei teeskle olevat täielik avaldamissüsteem.
Püüa ilmsed probleemid kinni enne, kui need muutuvad kellegi teise probleemiks
Odavaim Markdowni viga on see, mille leiad enne, kui sisu sinu käest ära liigub. Live-eelvaade näitab, kas dokument loeb nii, nagu kavatsesid. Fookustatud hoiatuspass ütleb, kas struktuur on piisavalt tugev järgmise üleandmise üleelamiseks. Koos katavad need kaks kontrolli enamiku tööst, mida enne avaldamist päriselt vajad.
Ava Markdowni valideerija, kui tahad otsest tööriista, kasuta korduma kippuvaid küsimusi saidiüleste töövooootuste jaoks ja hoia Kas veebikonverterid on tööfailide jaoks turvalised? Mida kontrollida enne kleepimist või üleslaadimist lähedal, kui järgmine otsus puudutab vähem Markdowni ja rohkem seda, millal brauseriutiliit üldse sobib.
