Converting to RST

RST format is used for documentation. Other file formats can be converted to RST with pandoc.

Caution

Always check the output text after conversion. For the most common errors, see section Fixing the converted document.

Installing pandoc

Pandoc is a powerful document-transformation utility. We’ll use it to do simple conversions, but it is capable of much more. Visit the pandoc website for installation instructions for your platform.

Converting

Using a terminal, navigate to the directory containing the documents you wish to convert. Next, issue the following command for each file you’d like to convert:

pandoc -s --toc -f <from format> -t rst myfile.<from format>

-s tells pandoc to produce a standalone document

--toc tells pandoc to produce a table of contents (optional)

-t tells pandoc to produce reStructuredText output

-f tells pandoc the input format. It should be one of the following:

Format

Description

commonmark

Markdown variant

docbook

XML-based markup

docx

Microsoft Word

epub

Ebook format

haddock

Doc format produced by tool used on Haskell code

html

HTML

json

JSON pandoc AST

latex

Older typesetting syntax

markdown

Simple formatting syntax meant to produce HTML

markdown_github

Github flavored markdown

markdown_mmd

Multi-markdown flavored markdown

markdown_phpextra

PHP flavored markdown

markdown_strict

Markdown with no added pandoc features

mediawiki

Popular wiki language

native

Pandoc native Haskell

odt

Open document text (used by LibreOffice)

opml

Outline processor markup language

org

Org mode for Emacs

rst

reStructuredText

t2t

Wiki-like formatting syntax

textile

A formatting syntax similar to RST and markdown

twiki

Popular wiki formatting syntax

Fixing the converted document

How much you’ll need to fix the converted document depends on which file format you’re converting from. Here are a couple of things to watch out for:

  1. Multi-line titles need to be converted to single line

  2. Standalone “**” characters

  3. ***bolded*** should be **bolded**

  4. Mangled tables

Previewing edits

Web-based

Online Sphinx editor is a RST previewing tool.