Darmowy konwerter online MMD do RST

Projekty korzystające z Sphinx, Docutils lub innego systemu dokumentacji opartego na reStructuredText wymagają pliku .rst zamiast źródła MultiMarkdown. Konwersja zachowuje nagłówki, listy, łącza, bloki kodu i inne obsługiwane elementy struktury w edytowalnym formacie zwykłego tekstu.

Czym jest format MMD

MMD zazwyczaj oznacza MultiMarkdown — rozszerzony format Markdown przechowywany jako plik zwykłego tekstu .mmd. Dodaje on do standardowego Markdown takie funkcje jak metadane, tabele, przypisy, cytowania, listy definicji i odwołania wzajemne.

Pliki MultiMarkdown są tworzone przez narzędzia wiersza poleceń MultiMarkdown oraz edytory Markdown obsługujące składnię MultiMarkdown. Można je znaleźć w projektach pisarskich, repozytoriach dokumentacji technicznej oraz plikach źródłowych przygotowanych do konwersji na HTML, PDF lub inne formaty dokumentów.

Czym jest format RST

RST, czyli reStructuredText, to strukturalny format znaczników zwykłego tekstu używany przez Docutils, Sphinx, dokumentację Python oraz generatory dokumentacji. Jawne znaczniki sekcji, dyrektywy, role, etykiety i listy pól sprawiają, że nadaje się on do dużych projektów dokumentacyjnych i automatycznych kompilacji.

RST jest przydatny, gdy system docelowy oczekuje plików kończących się rozszerzeniem .rst, szczególnie w projekcie Sphinx. Obsługuje także objaśnienia, dyrektywy API, odwołania wewnętrzne, tabele, dosłowne bloki kodu i pola metadanych, chociaż niektóre funkcje MultiMarkdown mogą wymagać ręcznego dostosowania po konwersji.

Jak faktycznie przekonwertować MMD na RST

Korzystanie z Pandoc

Pandoc to najbardziej praktyczna opcja desktopowa lub wiersza poleceń do przeprowadzenia konwersji strukturalnej. Zainstaluj aktualną wersję Pandoc, otwórz terminal w folderze zawierającym plik źródłowy i uruchom:

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

Czytnik markdown_mmd informuje Pandoc, aby interpretował źródło jako MultiMarkdown, natomiast rst wybiera reStructuredText jako format wyjściowy. Zastąp input.mmd i output.rst rzeczywistymi nazwami plików.

W przypadku dokumentu korzystającego ze standardowej składni Markdown, a nie rozszerzeń właściwych dla MultiMarkdown, ta alternatywa jest zwykle wystarczająca:

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

Otwórz wynikowy plik w edytorze tekstu, sprawdź wygenerowane podkreślenia sekcji i dyrektywy, a następnie zbuduj go za pomocą Sphinx lub Docutils. W projekcie Sphinx umieść output.rst w katalogu źródłowym dokumentacji i uruchom standardowe polecenie kompilacji projektu.

Korzystanie z konwertera online

Plik można bezpłatnie przekonwertować w witrynie 101convert.com bez instalowania oprogramowania: wybierz plik MMD, wybierz RST jako format wyjściowy, rozpocznij konwersję i pobierz wygenerowany plik .rst.

Ograniczenia jakości i zgodności

• Metadane MultiMarkdown mogą zostać przekonwertowane na składnię listy pól RST, zwykłe akapity lub komentarze dokumentu, zależnie od pola i wersji Pandoc; ręcznie sprawdź tytuł, autora, datę oraz inne metadane.
• Nagłówki, wyróżnienia, łącza, obrazy, listy numerowane, ogrodzone bloki kodu i wiele tabel zazwyczaj konwertują się poprawnie, ale RST wymaga unikatowych stylów podkreśleń sekcji i bardziej rygorystycznego wcięcia.
• Cytowania MultiMarkdown, transkluzja, specjalne atrybuty i niestandardowe rozszerzenia mogą nie mieć bezpośrednich odpowiedników w RST. Pandoc może zachować nieobsługiwany materiał jako surowy tekst, ale nie odtworzy funkcji, których nie implementuje RST lub docelowy generator.
• Po konwersji sprawdź ścieżki obrazów, cele łączy, kotwice, przypisy i znaki wymagające znaków ucieczki. Sphinx może wymagać jawnych etykiet, takich jak .. _label:, oraz dyrektyw, takich jak .. code-block:: python, w przypadku funkcji, które w źródle MMD były niejawne.