Dva zápisy jedného dokumentu
Markdown označuje nadpisy, zvýraznenie, zoznamy a odkazy krátkymi znakmi. HTML tieto štruktúry pomenúva prvkami ako h2, strong, ul a a. Spracovač Markdown najprv vyhodnocuje význam zápisu a až potom vytvára HTML; nenahrádza mechanicky každú hviezdičku či mriežku. Záleží na kontexte: mriežka na začiatku riadka môže začať nadpis, ale v obyčajnom texte má inú úlohu. HTML navyše pozná atribúty, vnáranie prvkov a pravidlá prehliadača, ktoré stručný Markdown nemusí vedieť vyjadriť.
Markdown zvoľte, ak sa má zdroj pohodlne upravovať v textovom editore. HTML použite tam, kde cieľ žiada presné prvky alebo chcete preveriť štruktúru prijatú prehliadačom. Najprv zistite, ktorú podobu Markdownu cieľ podporuje. MultiVerto spracúva zdokumentovanú podmnožinu: nadpisy, odseky, jednoduché zoznamy, zvýraznenie, odkazy a riadkový kód v oboch smeroch. Ohradené bloky kódu fungujú iba smerom do HTML. Niektoré nepodporované konštrukcie odmieta, iné zobrazí ako doslovný text.
Príklad prevodu a návratu
Napíšte dve mriežky a slovo Poznámky, vynechajte riadok a pridajte vetu **Hotový** návrh. Nástroj vytvorí prvok h2 s textom Poznámky a odsek, v ktorom prvok strong obklopí zvýraznené slovo. Prehliadač zobrazí nadpis a tučné písmo, zatiaľ čo zdrojové HTML zachová hranice jednotlivých prvkov. Vložený príklad obsahuje aj odkaz: jeho adresa sa uloží do atribútu href, nie ako viditeľná interpunkcia vo vete.
Podporované HTML potom vložte do opačného prevodníka. Prvok h2 dokáže vyjadriť mriežkami, strong dvojicami hviezdičiek a odkaz textom v hranatých zátvorkách s adresou. Výsledok môže na pohľad zostať rovnaký, aj keď sa zmenia medzery, zalomenia riadkov alebo presný zdrojový zápis. Porovnajte viditeľnú štruktúru a cieľ odkazu; nevyžadujte úplnú zhodu pôvodných a vrátených bajtov Markdownu.
- Markdown: ## Poznámky a **Hotový**
- HTML: prvky h2 a strong
- Markdown späť: overiť nadpis, zvýraznenie a odkaz
Prečo sa pri návrate strácajú detaily
HTML má štruktúry a atribúty bez jednoduchej obdoby v Markdowne. Štylizovaný span, tabuľka, vlastný dátový atribút alebo vnorené zoznamy sa nemusia dať bezpečne vrátiť; tento lokálny nástroj mnohé také prípady odmieta. Aj spracovače Markdownu sa odlišujú podporou tabuliek, úloh, citácií a vloženého HTML. MultiVerto viacero takých konštrukcií odmietne namiesto tichého vymyslenia výsledku. Úspešný malý príklad preto nepotvrdzuje správnosť ľubovoľne zložitého dokumentu.
Aj podporovaný obsah môže mať viac zápisov. Prvky strong aj b sa môžu vrátiť ako hviezdičky, takže pôvodný výber značky sa stratí. Prehliadač navyše vie opraviť neúplné HTML. Pred publikovaním prezrite vytvorené značky a výsledok zobrazte v cieľovom prostredí. Pôvodný súbor si ponechajte, aby ste nestratili atribúty, komentáre alebo rozhodnutia o rozložení, ktoré jednoduchší formát nedokáže zachovať.
Escapovanie je iná operácia
Zakódovať znak HTML na zobrazenie nie je to isté ako vytvoriť štruktúru HTML z Markdownu. Ak má čitateľ doslova vidieť <h2>Poznámky</h2>, uhlové zátvorky zapíšte ako entity alebo text vložte do dôveryhodného kódového kontextu. Ak chcete skutočný nadpis, vytvorte prvok h2. Nižšie prepojený nástroj na HTML entity mení reprezentáciu textu; prevodník Markdown vytvára prvky. Cudzí obsah považujte v oboch postupoch za nedôveryhodný.
Lokálny prevodník escapuje bežný text vo svojej podporovanej podmnožine. Pri systéme, ktorý publikuje ľubovoľné príspevky, však stále použite udržiavaný parser a vhodné čistenie, keď vstup môže obsahovať odkazy alebo značky. Overte pravidlá cieľa pre povolené adresy a prvky. Praktický postup je previesť krátky príklad, skontrolovať HTML, zobraziť ho a spätne previesť len podporovanú časť. Ak sa vlastnosť stratí, bohatší pôvodný formát ponechajte ako rozhodujúci zdroj.