1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
11 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 <http://pandoc.org/installing.html>`_ for installation instructions for your platform.
16 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:
18 :code:`pandoc -s --toc -f <from format> -t rst myfile.<from format>`
20 :code:`-s` tells pandoc to produce a standalone document
22 :code:`--toc` tells pandoc to produce a table of contents (optional)
24 :code:`-t` tells pandoc to produce reStructuredText output
26 :code:`-f` tells pandoc the input format. It should be one of the following:
28 +--------------------+---------------------------------------------------------------+
29 | Format | Description |
30 +====================+===============================================================+
31 |commonmark | Markdown variant |
32 +--------------------+---------------------------------------------------------------+
33 |docbook | XML-based markup |
34 +--------------------+---------------------------------------------------------------+
35 |docx | Microsoft Word |
36 +--------------------+---------------------------------------------------------------+
37 |epub | Ebook format |
38 +--------------------+---------------------------------------------------------------+
39 |haddock | Doc format produced by tool used on Haskell code |
40 +--------------------+---------------------------------------------------------------+
42 +--------------------+---------------------------------------------------------------+
43 |json | JSON pandoc AST |
44 +--------------------+---------------------------------------------------------------+
45 |latex | Older typesetting syntax |
46 +--------------------+---------------------------------------------------------------+
47 |markdown | Simple formatting syntax meant to produce HTML |
48 +--------------------+---------------------------------------------------------------+
49 |markdown_github | Github flavored markdown |
50 +--------------------+---------------------------------------------------------------+
51 |markdown_mmd | Multi-markdown flavored markdown |
52 +--------------------+---------------------------------------------------------------+
53 |markdown_phpextra | PHP flavored markdown |
54 +--------------------+---------------------------------------------------------------+
55 |markdown_strict | Markdown with no added pandoc features |
56 +--------------------+---------------------------------------------------------------+
57 |mediawiki | Popular wiki language |
58 +--------------------+---------------------------------------------------------------+
59 |native | Pandoc native Haskell |
60 +--------------------+---------------------------------------------------------------+
61 |odt | Open document text (used by LibreOffice) |
62 +--------------------+---------------------------------------------------------------+
63 |opml | Outline processor markup language |
64 +--------------------+---------------------------------------------------------------+
65 |org | Org mode for Emacs |
66 +--------------------+---------------------------------------------------------------+
67 |rst | reStructuredText |
68 +--------------------+---------------------------------------------------------------+
69 |t2t | Wiki-like formatting syntax |
70 +--------------------+---------------------------------------------------------------+
71 |textile | A formatting syntax similar to RST and markdown |
72 +--------------------+---------------------------------------------------------------+
73 |twiki | Popular wiki formatting syntax |
74 +--------------------+---------------------------------------------------------------+
76 Fixing the converted document
77 -----------------------------
79 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:
81 1. Multi-line titles need to be converted to single line
82 2. Standalone "**" characters
83 3. :code:`***bolded***` should be :code:`**bolded**`
92 `rst.ninjs.org <http://rst.ninjs.org>`_ has an excellent RST previewing tool that highlights RST errors with line numbers.