Converting to RST¶
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:
- Multi-line titles need to be converted to single line
- Standalone “**” characters
***bolded***should be**bolded**- Mangled tables
Previewing edits¶
Web-based¶
rst.ninjs.org has an excellent RST previewing tool that highlights RST errors with line numbers.