7Ask on [pandoc-discuss].
13Bug reports are welcome! Please report all bugs on pandoc's github
16Before you submit a bug report, search the [open issues] *and* [closed issues]
17to make sure the issue hasn't come up before. Also, check the [User's Guide] and
18[FAQs] for anything relevant.
20Make sure you can reproduce the bug with the [latest released
21version] of pandoc---or, even better, the development version,
22since the bug may have been fixed since the last release.
23[Nightly builds] are available, so you don't need to compile
24from source to test againt the development version.
25(To fetch a nightly, visit the link, click the topmost "Nightly"
26in the table, then choose your platform under "Artifacts." Note
27that you must be logged in with a GitHub account.)
29Your report should give detailed, *reproducible* instructions, including
31 * the pandoc version (check using `pandoc -v`)
32 * the exact command line used
33 * the exact input used
35 * the output you expected instead
37A small test case (just a few lines) is ideal. If your input is large,
38try to whittle it down to a *minimum working example*.
43A less than perfect conversion does not necessarily mean there's
44a bug in pandoc. Quoting from the MANUAL:
46> Because pandoc's intermediate representation of a document is less
47> expressive than many of the formats it converts between, one should
48> not expect perfect conversions between every format and every other.
49> Pandoc attempts to preserve the structural elements of a document, but
50> not formatting details such as margin size. And some document elements,
51> such as complex tables, may not fit into pandoc's simple document
52> model. While conversions from pandoc's Markdown to all formats aspire
53> to be perfect, conversions from formats more expressive than pandoc's
54> Markdown can be expected to be lossy.
56For example, both `docx` and `odt` formats can represent margin size, but
57because pandoc's internal document model does not contain a representation of
58margin size, this information will be lost on converting from docx
59to `odt`. (You can, however, customize margin size using `--reference-doc`.)
61So before submitting a bug report, consider whether it might be
62"out of scope." If it concerns a feature of documents that isn't
63representable in pandoc's Markdown, then it very likely is.
64(If in doubt, you can always ask on [pandoc-discuss].)
66Fixing bugs from the issue tracker
67----------------------------------
69Almost all the bugs on the issue tracker have one or more associated
70tags. These are used to indicate the *complexity* and *nature* of a
71bug. There is not yet a way to indicate priority. An up to date
72summary of issues can be found on [GitHub labels].
74* [good first issue] — The perfect starting point for new contributors. The
75 issue is generic and can be resolved without deep knowledge of the code
77* [enhancement] — A feature which would be desirable. We recommend
78 you discuss any proposed enhancement on pandoc-discuss before
80* [bug] — A problem which needs to be fixed.
81* [complexity:low] — The fix should only be a couple of lines.
82* [complexity:high] — The fix might require structural changes or in depth
83 knowledge of the code base.
84* [new:reader] — A request to add a new input format.
85* [new:writer] — A request to add a new output format.
86* [docs] — A discrepancy, or ambiguity in the documentation.
87* [status:in-progress] — Someone is actively working on or planning to work on the
89* [status:more-discussion-needed] — It is unclear what the correct approach
90 to solving the ticket is. Before starting on tickets such as this it
91 would be advisable to post on the ticket.
92* [status:more-info-needed] — We require more information from a user before
93 we can classify a report properly.
95Issues related to a specific format are tagged accordingly, e.g. feature request
96or bug reports related to Markdown are labelled with [format:markdown].
98Have an idea for a new feature?
99-------------------------------
101First, search [pandoc-discuss] and the issue tracker (both [open issues] *and*
102[closed issues]) to make sure that the idea has not been discussed before.
104Explain the rationale for the feature you're requesting. Why would this
105feature be useful? Consider also any possible drawbacks, including backwards
106compatibility, new library dependencies, and performance issues.
108It is best to discuss a potential new feature on [pandoc-discuss]
109before opening an issue.
111Patches and pull requests
112-------------------------
114Patches and pull requests are welcome. Before you put time into a nontrivial
115patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
116for a new feature (rather than fixing a bug).
118Please follow these guidelines:
1201. Each patch (commit) should make a single logical change (fix a bug, add
121 a feature, clean up some code, add documentation). Everything
122 related to that change should be included (including tests and
123 documentation), and nothing unrelated should be included.
1252. The first line of the commit message should be a short description
126 of the whole commit (ideally <= 50 characters). Then there should
127 be a blank line, followed by a more detailed description of the
1303. Follow the stylistic conventions you find in the existing
131 pandoc code. Use spaces, not tabs, and wrap code to 80 columns.
132 Always include type signatures for top-level functions.
133 Consider installing [EditorConfig], this will help you to follow the
134 coding style prevalent in pandoc.
1364. Your code should compile without warnings (`-Wall` clean).
1385. Run the tests to make sure your code does not introduce new bugs.
139 (See below under [Tests](#tests).) All tests should pass.
1416. It is a good idea to add test cases for the bug you are fixing. (See
142 below under [Tests](#tests).) If you are adding a new writer or reader,
143 you must include tests.
1457. If you are adding a new feature, include updates to `MANUAL.txt`.
1478. All code must be released under the general license governing pandoc
1509. It is better not to introduce new dependencies. Dependencies on
151 external C libraries should especially be avoided.
15310. We aim for compatibility with ghc versions from 8.0 to the
154 latest release. All pull requests and commits are tested
155 automatically on CircleCI.
160Tests can be run as follows:
162 cabal install --only-dependencies --enable-tests
163 cabal configure --enable-tests
167or, if you're using [stack],
172The test program is `test/test-pandoc.hs`.
174To run particular tests (pattern-matching on their names), use
177 cabal install pandoc --enable-tests
178 cabal test --test-options='-p markdown'
182 stack test --test-arguments='-p markdown'
184It is often helpful to add `-j4` (run tests in parallel)
185and `--hide-successes` (don't clutter output with successes)
186to the test arguments as well.
188If you add a new feature to pandoc, please add tests as well, following
189the pattern of the existing tests. The test suite code is in
190`test/test-pandoc.hs`. If you are adding a new reader or writer, it is
191probably easiest to add some data files to the `test` directory, and
192modify `test/Tests/Old.hs`. Otherwise, it is better to modify the module
193under the `test/Tests` hierarchy corresponding to the pandoc module you
194are changing. Alternatively, you may add a "command test" to
195the `/test/command/` hierarchy, following the pattern of the tests there.
196These test files should have a meaningful name, which can include the issue
197number and/or the feature that's being tested. For example, `5474-tables.md`
198refers to both issue and feature.
200You can rebuild the golden tests in `tests/` by passing
201`--accept` to the test script. (If you're using stack, `stack
202test --test-arguments "--accept"`; or `make TESTARGS=--accept`).
203Then check the changed golden files for accuracy, and
204commit the changes. For docx or pptx tests, open the files in Word
205or Powerpoint to ensure that they weren't corrupted and that
206they had the expected result, and mention the Word/Powerpoint
207version and OS in your commit comment.
212To run benchmarks with cabal:
214 cabal configure --enable-benchmarks
222You can also build `weigh-pandoc` (`stack build pandoc:weigh-pandoc`)
223to get some statistics on memory usage. (Eventually this should
224be incorporated into the benchmark suite.)
229With a recent version of cabal, you can do `cabal repl` and get
230a ghci REPL for working with pandoc. With [stack], use
233We recommend using the following `.ghci` file (which can be
234placed in the source directory):
237 :set -XTypeSynonymInstances
238 :set -XScopedTypeVariables
239 :set -XOverloadedStrings
244To diagnose a performance issue with parsing, first try using
245the `--trace` option. This will give you a record of when block
246parsers succeed, so you can spot backtracking issues.
248To use the GHC profiler with cabal:
251 cabal install --enable-library-profiling --enable-executable-profiling
252 pandoc +RTS -p -RTS [file]...
258 stack install --profile
259 pandoc +RTS -p -RTS [file]...
265The default templates live in `data/templates`, which is a git
266subtree linked to <https://github.com/jgm/pandoc-templates.git>.
267The purpose of maintaining a separate repository is to allow
268people to maintain variant templates as a fork.
270You can modify the templates and submit patches without worrying
271much about this: when these patches are merged, we will
272push them to the main templates repository by doing
274 git subtree push --prefix=data/templates templates master
276where `templates` is a remote pointing to the templates
282Pandoc has a publicly accessible git repository on
283github: <http://github.com/jgm/pandoc>. To get a local copy of the source:
285 git clone https://github.com/jgm/pandoc.git
287The source for the main pandoc program is `pandoc.hs`. The source for
288the pandoc library is in `src/`, the source for the tests is in
289`test/`, and the source for the benchmarks is in `benchmark/`.
291The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
292`Text.Pandoc.Generic` are in a separate library `pandoc-types`. The code can
293be found in <http://github.com/jgm/pandoc-types>.
295To build pandoc, you will need a working installation of the
298The library is structured as follows:
300 - `Text.Pandoc` is a top-level module that exports what is needed
301 by most users of the library. Any patches that add new readers
302 or writers will need to make changes here, too.
303 - `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
304 used for representing a pandoc document.
305 - `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
306 building pandoc documents programmatically.
307 - `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
308 you to promote functions that operate on parts of pandoc documents
309 to functions that operate on whole pandoc documents, walking the
311 - `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
313 - `Text.Pandoc.Biblio` is a utility module for formatting citations
315 - `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
316 cabal flag is used. It is generated from `src/Text/Pandoc/Data.hsb` using
317 the preprocessor [hsb2hs].
318 - `Text.Pandoc.Highlighting` contains the interface to the
319 skylighting library, which is used for code syntax highlighting.
320 - `Text.Pandoc.ImageSize` is a utility module containing functions for
321 calculating image sizes from the contents of image files.
322 - `Text.Pandoc.MIME` contains functions for associating MIME types
324 - `Text.Pandoc.Options` defines reader and writer options.
325 - `Text.Pandoc.PDF` contains functions for producing a PDF from a
327 - `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
328 - `Text.Pandoc.Pretty` is a pretty-printing library specialized to
330 - `Text.Pandoc.SelfContained` contains functions for making an HTML
331 file "self-contained," by importing remotely linked images, CSS,
332 and JavaScript and turning them into `data:` URLs.
333 - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
334 - `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
335 - `Text.Pandoc.Slides` contains functions for splitting a markdown document
336 into slides, using the conventions described in the MANUAL.
337 - `Text.Pandoc.Templates` defines pandoc's templating system.
338 - `Text.Pandoc.UTF8` contains functions for converting text to and from
339 UTF8 bytestrings (strict and lazy).
340 - `Text.Pandoc.Asciify` contains functions to derive ascii versions of
341 identifiers that use accented characters.
342 - `Text.Pandoc.UUID` contains functions for generating UUIDs.
343 - `Text.Pandoc.XML` contains functions for formatting XML.
348If you've written a useful pandoc [lua filter](lua-filters.html),
349you may want to consider submitting a pull request to the
350[lua-filters repository](https://github.com/pandoc/lua-filters).
352[open issues]: https://github.com/jgm/pandoc/issues
353[closed issues]: https://github.com/jgm/pandoc/issues?q=is%3Aissue+is%3Aclosed
354[latest released version]: https://github.com/jgm/pandoc/releases/latest
355[Nightly builds]: https://github.com/jgm/pandoc/actions?query=workflow%3ANightly
356[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
357[issue tracker]: https://github.com/jgm/pandoc/issues
358[User's Guide]: http://pandoc.org/MANUAL.html
359[FAQs]: http://pandoc.org/faqs.html
360[EditorConfig]: http://editorconfig.org/
361[Haskell platform]: http://www.haskell.org/platform/
362[hsb2hs]: http://hackage.haskell.org/package/hsb2hs
363[GitHub labels]: https://github.com/jgm/pandoc/labels
364[good first issue]:https://github.com/jgm/pandoc/labels/good%20first%20issue
365[enhancement]: https://github.com/jgm/pandoc/labels/enhancement
366[bug]: https://github.com/jgm/pandoc/labels/bug
367[complexity:low]: https://github.com/jgm/pandoc/labels/complexity:low
368[complexity:high]: https://github.com/jgm/pandoc/labels/complexity:high
369[docs]: https://github.com/jgm/pandoc/labels/docs
370[format:markdown]: https://github.com/jgm/pandoc/labels/format:markdown
371[new:reader]: https://github.com/jgm/pandoc/labels/new:reader
372[new:writer]: https://github.com/jgm/pandoc/labels/new:writer
373[status:in-progress]: https://github.com/jgm/pandoc/labels/status:in-progress
374[status:more-discussion-needed]: https://github.com/jgm/pandoc/labels/status:more-discussion-needed
375[status:more-info-needed]: https://github.com/jgm/pandoc/labels/status:more-info-needed
376[stack]: https://github.com/commercialhaskell/stack
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