Online konvertor MMD do RST zdarma

Projekty používající Sphinx, Docutils nebo jiný dokumentační systém založený na reStructuredText vyžadují soubor .rst namísto zdroje MultiMarkdown. Převodem dokumentu se zachovají nadpisy, seznamy, odkazy, bloky kódu a další podporovaná struktura v upravitelném formátu prostého textu.

Co je formát MMD

MMD obvykle označuje MultiMarkdown, rozšířený formát Markdown uložený jako soubor prostého textu .mmd. Oproti standardnímu Markdownu přidává funkce, jako jsou metadata, tabulky, poznámky pod čarou, citace, definiční seznamy a křížové odkazy.

Soubory MultiMarkdown se vytvářejí pomocí nástrojů MultiMarkdown pro příkazový řádek a v editorech Markdownu, které podporují syntaxi MultiMarkdown. Můžete se s nimi setkat v projektech zaměřených na psaní, repozitářích technické dokumentace a zdrojových souborech připravených k převodu do formátů HTML, PDF nebo jiných formátů dokumentů.

Co je formát RST

RST, neboli reStructuredText, je strukturovaný značkovací formát prostého textu používaný nástroji Docutils, Sphinx, pro dokumentaci Pythonu a generátory dokumentace. Jeho explicitní značky sekcí, direktivy, role, štítky a seznamy polí se hodí pro rozsáhlé dokumentační projekty a automatizované sestavování.

RST je užitečný, když cílový systém očekává soubory s příponou .rst, zejména projekt Sphinx. Podporuje také upozornění, direktivy API, interní odkazy, tabulky, doslovné bloky kódu a pole metadat, ačkoli některé funkce MultiMarkdown vyžadují po převodu ruční úpravu.

Jak skutečně převést MMD na RST

Pomocí Pandoc

Pandoc je nejpraktičtější desktopová nebo příkazová volba pro strukturovaný převod. Nainstalujte aktuální verzi Pandoc, otevřete terminál ve složce obsahující zdrojový soubor a spusťte:

pandoc input.mmd -f markdown_mmd -t rst -o output.rst

Čtečka markdown_mmd říká nástroji Pandoc, aby zdroj interpretoval jako MultiMarkdown, zatímco rst vybírá výstup ve formátu reStructuredText. Nahraďte input.mmd a output.rst skutečnými názvy souborů.

U dokumentu, který používá standardní syntaxi Markdownu namísto rozšíření specifických pro MultiMarkdown, obvykle postačí tato alternativa:

pandoc input.mmd -f markdown -t rst -o output.rst

Otevřete výsledný soubor v textovém editoru, zkontrolujte vygenerované podtržení sekcí a direktivy a poté jej sestavte pomocí Sphinx nebo Docutils. V projektu Sphinx umístěte output.rst do zdrojového adresáře dokumentace a spusťte běžný příkaz pro sestavení projektu.

Pomocí online převodníku

Soubor můžete zdarma převést na webu 101convert.com bez instalace softwaru: vyberte soubor MMD, jako výstupní formát zvolte RST, spusťte převod a stáhněte vygenerovaný soubor .rst.

Omezení kvality a kompatibility

• Metadata MultiMarkdown se mohou v závislosti na poli a verzi Pandoc převést na syntaxi seznamu polí RST, běžné odstavce nebo komentáře dokumentu; ručně ověřte název, autora, datum a další metadata.
• Nadpisy, zvýraznění, odkazy, obrázky, číslované seznamy, bloky kódu v ohraničení a mnoho tabulek se obecně převádějí dobře, ale RST vyžaduje jedinečné styly podtržení sekcí a přísnější odsazení.
• Citace MultiMarkdown, vkládání obsahu, speciální atributy a vlastní rozšíření nemusí mít v RST přímý ekvivalent. Pandoc může nepodporovaný obsah zachovat jako nezpracovaný text, ale nedokáže reprodukovat chování, které RST nebo cílový nástroj pro sestavení neimplementuje.
• Po převodu zkontrolujte cesty k obrázkům, cíle odkazů, kotvy, poznámky pod čarou a escapování. Sphinx může u funkcí, které byly ve zdroji MMD implicitní, vyžadovat explicitní štítky, například .. _label:, a direktivy, například .. code-block:: python.