Convertitore online gratuito da MMD a RST

I progetti che utilizzano Sphinx, Docutils o un altro sistema di documentazione basato su reStructuredText richiedono un file .rst anziché il sorgente MultiMarkdown. La conversione mantiene titoli, elenchi, link, blocchi di codice e altre strutture supportate in un formato di testo normale modificabile.

Cos'è il formato MMD

MMD indica solitamente MultiMarkdown, un formato Markdown esteso memorizzato come file di testo normale .mmd. Aggiunge a Markdown standard funzionalità come metadati, tabelle, note a piè di pagina, citazioni, elenchi di definizioni e riferimenti incrociati.

I file MultiMarkdown vengono creati dagli strumenti da riga di comando MultiMarkdown e dagli editor Markdown che supportano la sintassi MultiMarkdown. È possibile trovarli in progetti di scrittura, repository di documentazione tecnica e file sorgente preparati per la conversione in HTML, PDF o altri formati di documento.

Cos'è il formato RST

RST, o reStructuredText, è un formato di markup strutturato in testo normale utilizzato da Docutils, Sphinx, dalla documentazione Python e dai generatori di documentazione. I relativi marcatori espliciti di sezione, direttive, ruoli, etichette ed elenchi di campi lo rendono adatto a grandi progetti di documentazione e build automatizzate.

RST è utile quando il sistema di destinazione prevede file con estensione .rst, soprattutto in un progetto Sphinx. Supporta inoltre admonition, direttive API, riferimenti interni, tabelle, blocchi di codice letterale e campi di metadati, sebbene alcune funzionalità di MultiMarkdown richiedano modifiche manuali dopo la conversione.

Come convertire effettivamente MMD in RST

Utilizzo di Pandoc

Pandoc è l'opzione desktop o da riga di comando più pratica per una conversione strutturata. Installa una versione aggiornata di Pandoc, apri un terminale nella cartella contenente il file sorgente ed esegui:

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

Il reader markdown_mmd indica a Pandoc di interpretare il sorgente come MultiMarkdown, mentre rst seleziona l'output reStructuredText. Sostituisci input.mmd e output.rst con i nomi effettivi dei file.

Per un documento che utilizza la sintassi Markdown standard anziché le estensioni specifiche di MultiMarkdown, questa alternativa è solitamente sufficiente:

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

Apri il file risultante in un editor di testo, controlla le sottolineature delle sezioni e le direttive generate, quindi esegui la build con Sphinx o Docutils. In un progetto Sphinx, inserisci output.rst nella directory dei sorgenti della documentazione ed esegui il normale comando di build del progetto.

Utilizzo del convertitore online

Puoi convertire gratuitamente il file sul sito web 101convert.com senza installare software: seleziona il file MMD, scegli RST come formato di output, avvia la conversione e scarica il file .rst generato.

Limitazioni relative a qualità e compatibilità

• I metadati MultiMarkdown possono diventare sintassi RST per gli elenchi di campi, paragrafi normali o commenti del documento, a seconda del campo e della versione di Pandoc; verifica manualmente titolo, autore, data e gli altri metadati.
• Titoli, enfasi, link, immagini, elenchi numerati, blocchi di codice delimitati e molte tabelle vengono generalmente convertiti correttamente, ma RST richiede stili di sottolineatura delle sezioni univoci e un'indentazione più rigorosa.
• Le citazioni MultiMarkdown, la transclusion, gli attributi speciali e le estensioni personalizzate potrebbero non avere un equivalente diretto in RST. Pandoc può conservare il materiale non supportato come testo non elaborato, ma non può riprodurre comportamenti che RST o il builder di destinazione non implementano.
• Controlla i percorsi delle immagini, le destinazioni dei link, le ancore, le note a piè di pagina e l'escaping dopo la conversione. Sphinx potrebbe richiedere etichette esplicite come .. _label: e direttive come .. code-block:: python per funzionalità che nel sorgente MMD erano implicite.