3These instructions explain how to install pandoc from source.
4Binary packages or ports of pandoc are available for freebsd
5and several linux distributions, so check your package manager.
6There are also binary installers for Windows and Mac OS X.
8If you are installing the development version from github, see also:
9https://github.com/jgm/pandoc/wiki/Installing-the-development-version-of-pandoc
11Please note that pandoc only supports [GHC] versions 7.8 and
12above. The easiest way to get GHC is by installing the [Haskell platform]
17Source tarballs can be found at
18<https://hackage.haskell.org/package/pandoc>. The tarball
19for a particular version `VERSION` can be found at
21 https://hackage.haskell.org/package/pandoc-VERSION/pandoc-VERSION.tar.gz
23**Do not use the automatically generated tarball that can be
24downloaded from pandoc's GitHub releases page.** It does not
25include some essential template files, which come from a GitHub
28If you want the latest development code, you can fetch it
29by cloning the repository:
31 git clone https://github.com/jgm/pandoc
33 git submodule update --init # to fetch the templates
35Note: there may be times when the development code is broken
36or depends on other libraries which must be installed
37separately. Unless you really know what you're doing, install
38the last released version.
40Quick install with stack
41------------------------
431. Install [stack](http://docs.haskellstack.org/en/stable/install_and_upgrade.html).
452. If you used git to get the pandoc source (as opposed to unpacking
46 a release tarball), do
48 git submodule update --init
503. In the pandoc source directory,
54 You may be prompted to run `stack setup`, which will automatically
55 download the ghc compiler if needed.
58Quick install with cabal
59------------------------
611. Install the [Haskell platform]. This will give you [GHC] and
62 the [cabal-install] build tool.
642. Update your package database:
683. Use `cabal` to install pandoc and its dependencies:
72 This procedure will install the released version of pandoc,
73 which will be downloaded automatically from HackageDB.
75 If this step fails, and you are using an older version
76 of the Haskell Platform, e.g. on Debian stable, you may need to
77 upgrade your version of cabal:
79 cabal install cabal-install
80 ~/.cabal/bin/cabal update
81 ~/.cabal/bin/cabal install pandoc
83 If you want to install a modified or development version
84 of pandoc instead, switch to the source directory and do
85 as above, but without the 'pandoc':
89 Note: If you obtained the source from the git repository (rather
90 than a release tarball), you'll need to do
92 git submodule update --init
94 to fetch the contents of `data/templates` before `cabal install`.
964. Make sure the `$CABALDIR/bin` directory is in your path. You should
97 now be able to run `pandoc`:
101 [Not sure where `$CABALDIR` is?](http://www.haskell.org/haskellwiki/Cabal-Install#The_cabal-install_configuration_file)
1035. If you want to process citations with pandoc, you will also need to
104 install a separate package, `pandoc-citeproc`. This can be installed
107 cabal install pandoc-citeproc
109 By default `pandoc-citeproc` uses the "i;unicode-casemap" method
110 to sort bibliography entries (RFC 5051). If you would like to
111 use the locale-sensitive unicode collation algorithm instead,
112 specify the `unicode_collation` flag:
114 cabal install pandoc-citeproc -funicode_collation
116 Note that this requires the `text-icu` library, which in turn
117 depends on the C library `icu4c`. Installation directions
118 vary by platform. Here is how it might work on OSX with homebrew:
121 cabal install --extra-lib-dirs=/usr/local/Cellar/icu4c/51.1/lib \
122 --extra-include-dirs=/usr/local/Cellar/icu4c/51.1/include \
123 -funicode_collation text-icu pandoc-citeproc
125The `pandoc.1` man page will be installed automatically. cabal shows
126you where it is installed: you may need to set your `MANPATH`
127accordingly. If `MANUAL.txt` has been modified, the man page can be
128rebuilt: `make man/pandoc.1`.
130The `pandoc-citeproc.1` man page will also be installed automatically.
132[GHC]: http://www.haskell.org/ghc/
133[Haskell platform]: http://hackage.haskell.org/platform/
134[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall
139This is a step-by-step procedure that offers maximal control
140over the build and installation. Most users should use the
141quick install, but this information may be of use to packagers.
142For more details, see the [Cabal User's Guide]. These instructions
143assume that the pandoc source directory is your working directory.
1451. Install dependencies: in addition to the [Haskell platform],
146 you will need a number of additional libraries. You can install
150 cabal install --only-dependencies
154 cabal configure --prefix=DIR --bindir=DIR --libdir=DIR \
155 --datadir=DIR --libsubdir=DIR --datasubdir=DIR --docdir=DIR \
156 --htmldir=DIR --program-prefix=PREFIX --program-suffix=SUFFIX \
157 --mandir=DIR --flags=FLAGSPEC
159 All of the options have sensible defaults that can be overridden
162 `FLAGSPEC` is a list of Cabal configuration flags, optionally
163 preceded by a `-` (to force the flag to `false`), and separated
164 by spaces. Pandoc's flags include:
166 - `embed_data_files`: embed all data files into the binary (default no).
167 This is helpful if you want to create a relocatable binary.
168 Note: if this option is selected, you need to install the
169 `hsb2hs` preprocessor: `cabal install hsb2hs` (version 0.3.1 or
172 - `https`: enable support for downloading resources over https
173 (using the `http-client` and `http-client-tls` libraries).
1794. Build API documentation:
181 cabal haddock --html-location=URL --hyperlink-source
185 cabal copy --destdir=PATH
187 The default destdir is `/`.
1896. Register pandoc as a GHC package:
193 Package managers may want to use the `--gen-script` option to
194 generate a script that can be run to register the package at
197Creating a relocatable binary
198-----------------------------
200It is possible to compile pandoc such that the data files
201pandoc uses are embedded in the binary. The resulting binary
202can be run from any directory and is completely self-contained.
204 cabal install hsb2hs # a required build tool
205 cabal install --flags="embed_data_files" citeproc-hs
206 cabal configure --flags="embed_data_files"
209You can find the pandoc executable in `dist/build/pandoc`. Copy this wherever
212Or alternatively with `stack`:
214 stack install pandoc --flag pandoc:embed_data_files
216[zip-archive]: http://hackage.haskell.org/package/zip-archive
217[highlighting-kate]: http://hackage.haskell.org/package/highlighting-kate
218[blaze-html]: http://hackage.haskell.org/package/blaze-html
219[Cabal User's Guide]: http://www.haskell.org/cabal/release/latest/doc/users-guide/builders.html#setup-configure-paths
224Pandoc comes with an automated test suite integrated to cabal.
227 cabal configure --enable-tests && cabal build
233To run particular tests (pattern-matching on their names), use
236 cabal test --test-options='-t markdown'
238If you add a new feature to pandoc, please add tests as well, following
239the pattern of the existing tests. The test suite code is in
240`tests/test-pandoc.hs`. If you are adding a new reader or writer, it is
241probably easiest to add some data files to the `tests` directory, and
242modify `tests/Tests/Old.hs`. Otherwise, it is better to modify the module
243under the `tests/Tests` hierarchy corresponding to the pandoc module you
249To build the benchmarks:
251 cabal configure --enable-benchmarks && cabal build
253To run the benchmarks:
257To use a smaller sample size so the benchmarks run faster:
259 cabal bench --benchmark-options='-s 20'
261To run just the markdown benchmarks:
263 cabal bench --benchmark-options='markdown'
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