5 - There is a package installer at pandoc's [download page].
7 - For PDF output, you'll also need to install LaTeX.
8 We recommend [MiKTeX](http://miktex.org/).
10 - If you'd prefer, you can extract the pandoc and pandoc-citeproc
11 executables from the MSI and copy them directly to any directory,
12 without running the installer. Here is an example showing how to
13 extract the executables from the pandoc-1.19.1 installer and copy
14 them to `C:\Utils\Console\`:
16 mkdir "%TEMP%\pandoc\"
17 start /wait msiexec.exe /a pandoc-1.19.1-windows.msi /qn targetdir="%TEMP%\pandoc\"
18 copy /y "%TEMP%\pandoc\pandoc.exe" C:\Utils\Console\
19 copy /y "%TEMP%\pandoc\pandoc-citeproc.exe" C:\Utils\Console\
20 rmdir /s /q "%TEMP%\pandoc\"
24 - There is a package installer at pandoc's [download page].
25 If you later want to uninstall the package, you can do so
26 by downloading [this script][uninstaller]
27 and running it with `perl uninstall-pandoc.pl`.
29 - It is possible to extract the pandoc and pandoc-citeproc
30 executables from the macOS pkg file, if you'd rather not run
31 the installer. To do this (for the version 1.19.1 package):
35 xar -x ../pandoc-2.0-macOS.pkg
36 cat pandoc.pkg/Payload | gunzip -dc | cpio -i
37 # executables are now in ./usr/bin/, man pages in ./usr/share/man
39 - You can also install pandoc using
40 [homebrew](http://brew.sh): `brew install pandoc`.
42 - For PDF output, you'll also need LaTeX. Because a full [MacTeX]
43 installation takes more than a gigabyte of disk space, we recommend
44 installing [BasicTeX](http://www.tug.org/mactex/morepackages.html)
45 (64M) and using the `tlmgr` tool to install additional packages
46 as needed. If you get errors warning of fonts not found, try
48 tlmgr install collection-fontsrecommended
52 - First, try your package manager.
53 Pandoc is in the [Debian], [Ubuntu], [Slackware],
54 [Arch], [Fedora], [NiXOS], [openSUSE], and [gentoo] repositories.
55 Note, however, that versions in the repositories are often
58 - We provide a binary package for amd64 architecture on
59 the download page. This provides both pandoc and
60 pandoc-citeproc. The executables are statically linked and
61 have no dynamic dependencies. Both a tarball and a deb
62 installer are provided.
66 where `$DEB` is the path to the downloaded deb, will
67 install the `pandoc` and `pandoc-citeproc` executables
70 Note: because it is statically linked, the pandoc
71 binary from this package cannot use lua filters that
72 require external lua modules written in C.
74 - If you use an RPM-based distro, you may be
75 able to install the deb from our download page
78 ar p $DEB data.tar.gz | sudo tar xvz --strip-components 2 -C /usr/local
80 - If you'd rather install pandoc in your home directory, say
81 in `$HOME/.local`, then you can unzip the tarball or
82 extract the files manually from the deb:
84 ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $HOME/.local/
86 where, again, `$DEB` is the path to the downloaded deb.
88 - If the version in your repository is too old and you cannot
89 use the deb we provide, you can install from source, using the
90 instructions below under [Compiling from source].
91 Note that most distros have the Haskell platform in their
92 package repositories. For example, on Debian/Ubuntu,
93 you can install it with `apt-get install haskell-platform`.
95 - For PDF output, you'll need LaTeX. We recommend installing
96 [TeX Live](http://www.tug.org/texlive/) via your package
97 manager. (On Debian/Ubuntu, `apt-get install texlive`.)
101 - Pandoc is in the [NetBSD] and [FreeBSD ports] repositories.
103## Compiling from source
105If for some reason a binary package is not available for your
106platform, or if you want to hack on pandoc or use a non-released
107version, you can install from source.
109### Getting the pandoc source code
111Source tarballs can be found at
112<https://hackage.haskell.org/package/pandoc>. For example, to
113fetch the source for version 1.17.0.3:
115 wget https://hackage.haskell.org/package/pandoc-1.17.0.3/pandoc-1.17.0.3.tar.gz
116 tar xvzf pandoc-1.17.0.3.tar.gz
119Or you can fetch the development code by cloning the repository:
121 git clone https://github.com/jgm/pandoc
124Note: there may be times when the development code is broken
125or depends on other libraries which must be installed
126separately. Unless you really know what you're doing, install
127the last released version.
129### Quick stack method
131The easiest way to build pandoc from source is to use [stack]:
1352. Change to the pandoc source directory and issue the following commands:
140 `stack setup` will automatically download the ghc compiler
141 if you don't have it. `stack install` will install the
142 `pandoc` executable into `~/.local/bin`, which you should
143 add to your `PATH`. This process will take a while, and
144 will consume a considerable amount of disk space.
146### Quick cabal method
1481. Install the [Haskell platform]. This will give you [GHC] and
149 the [cabal-install] build tool. Note that pandoc requires
1522. Update your package database:
1563. Use `cabal` to install pandoc and its dependencies:
158 cabal install pandoc --enable-tests
160 This procedure will install the released version of pandoc,
161 which will be downloaded automatically from HackageDB.
163 If you want to install a modified or development version
164 of pandoc instead, switch to the source directory and do
165 as above, but without the 'pandoc':
1694. Make sure the `$CABALDIR/bin` directory is in your path. You should
170 now be able to run `pandoc`:
174 [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
1765. If you want to process citations with pandoc, you will also need to
177 install a separate package, `pandoc-citeproc`. This can be installed
180 cabal install pandoc-citeproc
182 By default `pandoc-citeproc` uses the "i;unicode-casemap" method
183 to sort bibliography entries (RFC 5051). If you would like to
184 use the locale-sensitive unicode collation algorithm instead,
185 specify the `unicode_collation` flag:
187 cabal install pandoc-citeproc -funicode_collation
189 Note that this requires the `text-icu` library, which in turn
190 depends on the C library `icu4c`. Installation directions
191 vary by platform. Here is how it might work on macOS with homebrew:
194 cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
195 --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
196 -funicode_collation text-icu pandoc-citeproc
1986. The `pandoc.1` man page will be installed automatically. cabal shows
199 you where it is installed: you may need to set your `MANPATH`
200 accordingly. If `MANUAL.txt` has been modified, the man page can be
201 rebuilt: `make man/pandoc.1`.
203 The `pandoc-citeproc.1` man page will also be installed automatically.
206### Custom cabal method
208This is a step-by-step procedure that offers maximal control
209over the build and installation. Most users should use the
210quick install, but this information may be of use to packagers.
211For more details, see the [Cabal User's Guide]. These instructions
212assume that the pandoc source directory is your working directory.
2141. Install dependencies: in addition to the [Haskell platform],
215 you will need a number of additional libraries. You can install
219 cabal install --only-dependencies
223 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
224 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
225 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
226 --mandir=DIR --flags=FLAGSPEC --enable-tests
228 All of the options have sensible defaults that can be overridden
231 `FLAGSPEC` is a list of Cabal configuration flags, optionally
232 preceded by a `-` (to force the flag to `false`), and separated
233 by spaces. Pandoc's flags include:
235 - `embed_data_files`: embed all data files into the binary (default no).
236 This is helpful if you want to create a relocatable binary.
238 - `https`: enable support for downloading resources over https
239 (using the `http-client` and `http-client-tls` libraries).
2464. Build API documentation:
248 cabal haddock --html-location=URL --hyperlink-source
252 cabal copy --destdir=PATH
254 The default destdir is `/`.
2566. Register pandoc as a GHC package:
260 Package managers may want to use the `--gen-script` option to
261 generate a script that can be run to register the package at
264### Creating a relocatable binary
266It is possible to compile pandoc such that the data files
267pandoc uses are embedded in the binary. The resulting binary
268can be run from any directory and is completely self-contained.
269With cabal, add `-fembed_data_files` to the `cabal configure`
270or `cabal install` commands.
272With stack, use `--flag pandoc:embed_data_files`.
278Pandoc comes with an automated test suite.
279To run with cabal, `cabal test`; to run with stack, `stack
282To run particular tests (pattern-matching on their names), use
285 cabal test --test-options='-p markdown'
289 stack test --test-arguments='-p markdown'
291It is often helpful to add `-j4` (run tests in parallel)
292and `--hide-successes` (don't clutter output with successes)
293to the test arguments as well.
295If you add a new feature to pandoc, please add tests as well, following
296the pattern of the existing tests. The test suite code is in
297`test/test-pandoc.hs`. If you are adding a new reader or writer, it is
298probably easiest to add some data files to the `test` directory, and
299modify `test/Tests/Old.hs`. Otherwise, it is better to modify the module
300under the `test/Tests` hierarchy corresponding to the pandoc module you
303### Running benchmarks
305To build and run the benchmarks:
307 cabal configure --enable-benchmarks && cabal build
314To use a smaller sample size so the benchmarks run faster:
316 cabal bench --benchmark-options='-s 20'
318To run just the markdown benchmarks:
320 cabal bench --benchmark-options='markdown'
323[Arch]: https://www.archlinux.org/packages/community/x86_64/pandoc/
324[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
325[Debian]: http://packages.debian.org/lenny/pandoc
326[Fedora]: https://apps.fedoraproject.org/packages/pandoc
327[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/
328[GHC]: http://www.haskell.org/ghc/
329[GPL]: http://www.gnu.org/copyleft/gpl.html
330[Haskell platform]: http://hackage.haskell.org/platform/
331[MacPorts]: http://trac.macports.org/browser/trunk/dports/textproc/pandoc/Portfile
332[MacTeX]: https://tug.org/mactex/
333[NetBSD]: http://pkgsrc.se/wip/pandoc
334[NixOS]: http://nixos.org/nixos/
335[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver=
336[Ubuntu]: http://www.ubuntu.com
337[download page]: https://github.com/jgm/pandoc/releases/latest
338[gentoo]: http://packages.gentoo.org/package/app-text/pandoc
339[haskell repository]: https://wiki.archlinux.org/index.php/Haskell_Package_Guidelines#.5Bhaskell.5D
340[openSUSE]: https://software.opensuse.org/package/pandoc
341[source tarball]: http://hackage.haskell.org/package/pandoc
342[stack]: http://docs.haskellstack.org/en/stable/install_and_upgrade.html
343[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
344[uninstaller]: https://raw.githubusercontent.com/jgm/pandoc/master/macos/uninstall-pandoc.pl
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