2title: Getting started with pandoc
6This document is for people who are unfamiliar with command line
7tools. Command-line experts can go straight to the [User's
8Guide](https://pandoc.org/MANUAL.html) or the pandoc man page.
10# Step 1: Install pandoc
12First, install pandoc, following the [instructions for
13your platform](https://pandoc.org/installing.html).
15# Step 2: Open a terminal
17Pandoc is a command-line tool. There is no graphic user interface.
18So, to use it, you'll need to open a terminal window:
20- On OS X, the Terminal application can be found in
21 `/Applications/Utilities`. Open a Finder window and go to
22 `Applications`, then `Utilities`. Then double click on
23 `Terminal`. (Or, click the spotlight icon in the upper right
24 hand corner of your screen and type `Terminal` -- you should
25 see `Terminal` under `Applications`.)
27- On Windows, you can use either the classic command prompt or the
28 more modern PowerShell terminal. If you use Windows in desktop
29 mode, run the `cmd` or `powershell` command from the Start menu.
30 If you use the Windows 8 start screen instead, simply type
31 `cmd` or `powershell`, and then run either the "Command
32 Prompt" or "Windows Powershell" application. If you are using
33 `cmd`, type `chcp 65001` before using pandoc, to set the
36- On Linux, there are many possible configurations, depending on
37 what desktop environment you're using:
39 * In Unity, use the search function on the `Dash`, and search
40 for `Terminal`. Or, use the keyboard shortcut `Ctrl-Alt-T`.
41 * In Gnome, go to `Applications`, then `Accessories`, and
42 select `Terminal`, or use `Ctrl-Alt-T`.
43 * In XFCE, go to `Applications`, then `System`, then `Terminal`,
45 * In KDE, go to `KMenu`, then `System`, then `Terminal Program (Konsole)`.
47You should now see a rectangle with a "prompt" (possibly just a symbol
48like `%`, but probably including more information, such as your
49username and directory), and a blinking cursor.
51Let's verify that pandoc is installed. Type
55and hit enter. You should see a message telling you which version
56of pandoc is installed, and giving you some additional information.
58# Step 3: Changing directories
60First, let's see where we are. Type
68on Windows, and hit enter. Your terminal should print your current
69working directory. (Guess what `pwd` stands for?) This should be your
72Let's navigate now to our `Documents` directory: type
76and hit enter. Now type
80(or `echo %cd%` on Windows)
81again. You should be in the `Documents` subdirectory of your home
82directory. To go back to your home directory, you could type
86The `..` means "one level up."
88Go back to your `Documents` directory if you're not there already.
89Let's try creating a subdirectory called `pandoc-test`:
93Now change to the `pandoc-test` directory:
97If the prompt doesn't tell you what directory you're in, you can
98confirm that you're there by doing
102(or `echo %cd%`) again.
104OK, that's all you need to know for now about using the terminal.
105But here's a secret that will save you a lot of typing. You can
106always type the up-arrow key to go back through your history
107of commands. So if you want to use a command you typed earlier,
108you don't need to type it again: just use up-arrow until it comes
109up. Try this. (You can use down-arrow as well, to go the other
110direction.) Once you have the command, you can also use the
111left and right arrows and the backspace/delete key to edit it.
113Most terminals also support tab completion of directories and
114filenames. To try this, let's first go back up to our `Documents`
123and hit the tab key instead of enter. Your terminal should fill
124in the rest (`test`), and then you can hit enter.
128 - `pwd` (or `echo %cd%` on Windows)
129 to see what the current working directory is.
130 - `cd foo` to change to the `foo` subdirectory of your working
132 - `cd ..` to move up to the parent of the working directory.
133 - `mkdir foo` to create a subdirectory called `foo` in the
135 - up-arrow to go back through your command history.
136 - tab to complete directories and file names.
138# Step 4: Using pandoc as a filter
144and hit enter. You should see the cursor just sitting there, waiting
145for you to type something. Type this:
152When you're finished (the cursor should be at the beginning of the line),
153type `Ctrl-D` on OS X or Linux, or `Ctrl-Z` followed
154by `Enter` on Windows. You should now see your text converted to HTML!
156 <p>Hello <em>pandoc</em>!</p>
162What just happened? When pandoc is invoked without specifying any
163input files, it operates as a "filter," taking input from the
164terminal and sending its output back to the terminal. You can use
165this feature to play around with pandoc.
167By default, input is interpreted as pandoc markdown, and output is
168HTML. But we can change that. Let's try converting *from* HTML
171 pandoc -f html -t markdown
175 <p>Hello <em>pandoc</em>!</p>
177and hit `Ctrl-D` (or `Ctrl-Z` followed by `Enter` on Windows).
182Now try converting something from markdown to LaTeX. What command
183do you think you should use?
185# Step 5: Text editor basics
187You'll probably want to use pandoc to convert a file, not to read
188text from the terminal. That's easy, but first we need to create
189a text file in our `pandoc-test` subdirectory.
191**Important:** To create a text file, you'll need to use a text
192editor, *not* a word processor like Microsoft Word. On Windows, you
193can use Notepad (in `Accessories`). On OS X, you can use
194`TextEdit` (in `Applications`). On Linux, different platforms come
195with different text editors: Gnome has `GEdit`, and KDE has `Kate`.
197Start up your text editor. Type the following:
205 This is a test of *pandoc*.
210Now save your file as `test1.md` in the directory
211`Documents/pandoc-test`.
213Note: If you use plain text a lot, you'll want a better editor than
214`Notepad` or `TextEdit`. You might want to look at
215[Sublime Text](https://www.sublimetext.com/) or (if you're willing
216to put in some time learning an unfamiliar interface)
217[Vim](https://www.vim.org) or [Emacs](https://www.gnu.org/software/emacs).
219# Step 6: Converting a file
221Go back to your terminal. We should still be in the
222`Documents/pandoc-test` directory. Verify that with `pwd`.
228(or `dir` if you're on Windows).
229This will list the files in the current directory. You should see
230the file you created, `test1.md`.
232To convert it to HTML, use this command:
234 pandoc test1.md -f markdown -t html -s -o test1.html
236The filename `test1.md` tells pandoc which file to convert.
237The `-s` option says to create a "standalone" file, with a header
238and footer, not just a fragment. And the `-o test1.html` says
239to put the output in the file `test1.html`. Note that we could
240have omitted `-f markdown` and `-t html`, since the default
241is to convert from markdown to HTML, but it doesn't hurt to
244Check that the file was created by typing `ls` again. You
245should see `test1.html`. Now open this in a browser. On OS X,
254You should see a browser window with your document.
256To create a LaTeX document, you just need to change the command
259 pandoc test1.md -f markdown -t latex -s -o test1.tex
261Try opening `test1.tex` in your text editor.
263Pandoc can often figure out the input and output formats from
264the filename extensions. So, you could have just used:
266 pandoc test1.md -s -o test1.tex
268Pandoc knows you're trying to create a LaTeX document, because of the
271Now try creating a Word document (with extension `docx`).
273If you want to create a PDF, you'll need to have LaTeX installed.
274(See [MacTeX](https://tug.org/mactex/) on OS X,
275[MiKTeX](https://miktex.org) on Windows, or install the texlive
276package on Linux.) Then do
278 pandoc test1.md -s -o test1.pdf
280# Step 7: Command-line options
282You now know the basics. Pandoc has a lot of options. At this point
283you can start to learn more about them by reading the
284[User's Guide](https://pandoc.org/MANUAL.html).
286Here's an example. The `--mathml` option causes pandoc to
287convert TeX math into MathML. Type
291then enter this text, followed by `Ctrl-D` (`Ctrl-Z` followed by
296Now try the same thing without `--mathml`. See the difference
299If you forget an option, or forget which formats are supported, you
304to get a list of all the supported options.
306On OS X or Linux systems, you can also do
310to get the pandoc manual page. All of this information is also
313If you get stuck, you can always ask questions on the
314[pandoc-discuss](https://groups.google.com/group/pandoc-discuss)
315mailing list. But be sure to check the [FAQs](https://pandoc.org/faqs.html) first,
316and search through the mailing list to see if your question has
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list