Dva zápisy jednoho dokumentu
Markdown označuje nadpisy, zvýraznění, seznamy a odkazy krátkými znaky. HTML tyto struktury pojmenovává prvky jako h2, strong, ul a a. Zpracování Markdownu nejprve vyhodnotí význam zápisu a teprve potom vytvoří HTML; nejde o mechanickou výměnu každé hvězdičky nebo mřížky. Záleží na kontextu: mřížka na začátku řádku může začít nadpis, ale v obyčejném textu má jiný význam. HTML navíc zná atributy, vnořené prvky a pravidla prohlížeče, která stručný Markdown nemusí vyjádřit.
Markdown zvolte, pokud má zdroj zůstat čitelný v textovém editoru. HTML použijte tam, kde cílový systém vyžaduje přesné prvky nebo chcete zkontrolovat strukturu pro prohlížeč. Nejprve zjistěte, kterou variantu Markdownu cíl přijímá. MultiVerto zpracovává zdokumentovanou podmnožinu: nadpisy, odstavce, jednoduché seznamy, zvýraznění, odkazy a řádkový kód v obou směrech. Ohraničené bloky kódu fungují jen směrem do HTML. Některé nepodporované konstrukce odmítá, jiné zobrazí jako doslovný text.
Příklad převodu a návratu
Napište dvě mřížky a slovo Poznámky, vynechte řádek a přidejte větu **Hotový** návrh. Nástroj vytvoří prvek h2 s textem Poznámky a odstavec, v němž strong obklopí zvýrazněné slovo. Prohlížeč zobrazí nadpis a tučné písmo, zatímco zdrojové HTML zachová hranice prvků. Interaktivní příklad obsahuje i odkaz: jeho adresa je v atributu href, nikoli jako viditelná interpunkce ve větě.
Podporované HTML vložte do opačného převodníku. Prvek h2 může vyjádřit mřížkami, strong dvojicemi hvězdiček a odkaz textem v hranatých závorkách s adresou. Výsledek může na pohled zůstat stejný, i když se změní mezery, zalomení řádků nebo přesný zdrojový zápis. Porovnávejte viditelnou strukturu a cíl odkazu; nevyžadujte doslovnou shodu původních a vrácených bajtů Markdownu.
- Markdown: ## Poznámky a **Hotový**
- HTML: prvky h2 a strong
- Markdown zpět: ověřit nadpis, zvýraznění a odkaz
Proč se při návratu ztrácejí detaily
HTML má struktury a atributy bez jednoduché obdoby v Markdownu. Stylovaný span, tabulka, vlastní datový atribut nebo vnořené seznamy se nemusí dát bezpečně vrátit; tento místní nástroj řadu takových případů odmítá. Také zpracování Markdownu se liší podporou tabulek, úkolů, citací a vloženého HTML. MultiVerto více takových konstrukcí odmítne místo tichého vymyšlení výstupu. Úspěšný malý příklad proto neověřuje správnost libovolně složitého dokumentu.
I podporovaná struktura může mít více zápisů. Prvky strong i b se mohou vrátit jako hvězdičky, takže původní volba značky zmizí. Prohlížeč navíc dokáže opravit neúplné HTML. Před publikováním si prohlédněte vytvořené značky a výsledek zobrazte v cílovém prostředí. Původní soubor uchovejte kvůli atributům, komentářům nebo rozhodnutím o rozvržení, které jednodušší formát nedokáže zachovat.
Escapování je jiná operace
Zakódovat znak HTML pro zobrazení není totéž jako vytvořit strukturu HTML z Markdownu. Pokud má čtenář doslova vidět <h2>Poznámky</h2>, zapište úhlové závorky jako entity nebo text vložte do důvěryhodného kontextu kódu. Jestliže chcete skutečný nadpis, vytvořte prvek h2. Níže propojený nástroj pro HTML entity mění reprezentaci textu; převodník Markdown vytváří prvky. Cizí obsah považujte v obou směrech za nedůvěryhodný.
Místní převodník escapuje běžný text své podporované podmnožiny. Pro systém publikující libovolné příspěvky však stále použijte udržovaný parser a vhodné čištění, mohou-li vstupy obsahovat odkazy nebo značky. Prověřte pravidla cíle pro povolené adresy a prvky. Užitečný postup je převést krátký příklad, zkontrolovat HTML, zobrazit jej a zpět převést jen podporovanou část. Pokud se vlastnost ztratí, ponechte bohatší původní formát jako rozhodující zdroj.