Mwongozo Kamili wa Kubadilisha Kodi ya HTML na Maandishi kuwa Markdown Safi
Katika mfumo wa kisasa wa wavuti na programu, HyperText Markup Language (HTML) inatumika kama msingi mkuu wa kuonyesha maudhui kwenye vivinjari. HTML inatumia muundo tata wa lebo za XML (kama <div>, <section>, <h1>, <p>, <span>, na <table>) pamoja na sifa za mtindo ili kufafanua muundo wa hati na muonekano wa picha. Ingawa HTML ni bora kwa kuonyesha muonekano wa kuvutia kwenye wavuti, urefu na ugumu wake wa kisintaksia unafanya iwe vigumu kutumika kwenye nyaraka za kiufundi, faili za README, na vidokezo vya waendelezaji. Tofauti na hiyo, Markdown imeibuka kama lugha ya muundo wa maandishi rahisi inayopendwa na waendelezaji, waandishi wa kiufundi, na timu za bidhaa. Markdown inatilia mkazo usomekaji mzuri, uumbaji mdogo, na ushirikiano rahisi na mifumo ya udhibiti wa matoleo kwa kutumia alama rahisi kama vile reli (#) kwa vichwa vya habari, nyota (*) kwa kutilia mkazo, na alama za backtick (`) kwa kodi.
Kubadilisha maudhui kutoka HTML hadi Markdown ni kazi ya kila siku katika uhandisi wa programu na uandishi wa kiufundi. Wakati wa kuhamisha nyaraka za zamani kutoka mifumo ya usimamizi wa maudhui (kama WordPress, Drupal, Joomla, au Confluence) hadi jenereta za kisasa za tovuti (kama Docusaurus, MkDocs, Astro Starlight, Hugo, au Jekyll), waandishi wanatakiwa kubadilisha maelfu ya vitalu vya HTML kuwa faili safi za Markdown. Vile vile, waendelezaji mara nyingi wanahitaji kunakili vipande vya kodi kutoka kurasa za wavuti au zana za kivinjari na kuzibadilisha kuwa Markdown kwa ajili ya masuala ya GitHub, maelezo ya pull request, au kanzi data za Notion. Kufanya ubadilishaji huu kwa mikono kunahitaji uhariri wa kuchosha: kuondoa lebo za HTML, kubadilisha orodha, na kupanga upya meza—mchakato unaotumia muda mwingi wa kiufundi na kusababisha makosa ya kisintaksia.
Kigeuzi cha HTML hadi Markdown cha Utiliome kinafanya mchakato huu uwe wa kiotomatiki kwa usahihi wa juu na unyumbulifu. Zana yetu inatekeleza kanuni ya uchanganuzi wa kisemantiki inayochunguza muundo wa HTML na kubadilisha kila kipengele kuwa sawa na Markdown inayotakiwa. Vipengele vya muundo wa juu kama vile <h1> hadi <h6> vinabadilishwa kuwa vichwa vya Markdown vya mtindo wa ATX (# hadi ######) au Setext. Lebo za muundo wa maandishi kama <strong>, <b>, <em>, <i>, <del>, na <s> zinatafsiriwa kuwa mtindo wa Markdown (koleza, mshazari, na katiza). Viungo (<a>) na picha (<img>) vinabadilishwa kuwa mtindo wa kawaida wa Markdown (Maandishi ya Kiungo na ), huku zikihifadhi URL kamili na za uwiano.
Kushughulikia maudhui tata kama vile orodha, meza, na vitalu vya kodi ni mahali ambapo Utiliome inafanya vyema zaidi. Orodha zisizo na mpangilio (<ul>) na zilizopangwa (<ol>) zilizo na vitu vya ndani (<li>) vinabadilishwa kuwa alama safi za Markdown au orodha zenye nambari zilizowekwa nafasi vizuri. Mfumo wa meza wa HTML (<table>, <thead>, <tbody>, <tr>, <th>, <td>) unachanganuliwa kuwa meza za GitHub-Flavored Markdown (GFM) zenye viashiria vya upangaji. Kodi zilizowekwa kwenye lebo za <pre><code> vinabadilishwa kuwa vitalu vya kodi vilivyo na lebo za lugha (k.m., class="language-typescript"). Zaidi ya hayo, lebo zisizo na maana ya kisemantiki (<div>, <span>, <article>, <section>) zinaondolewa na kuacha maandishi safi tu tayari kwa matumizi.