git.iko.soy/typeable/pandoc
on master help sign in
Improve links and cross-references in README.
32964efAndrew Dunning
README+285−215
compare with master
unifiedsplit
@@ -12,25 +12,26 @@ Description
12
12
13Pandoc is a [Haskell] library for converting from one markup format to
13Pandoc is a [Haskell] library for converting from one markup format to
14another, and a command-line tool that uses this library. It can read
14another, and a command-line tool that uses this library. It can read
15−[Markdown], [CommonMark], and (subsets of) [Textile],
15+[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
16−[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
16+and (subsets of) [Textile], [reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
17−markup], [Haddock markup], [OPML], [Emacs Org-mode], [DocBook],
17+markup], [Haddock markup], [OPML], [Emacs Org mode], [DocBook],
18[txt2tags], [EPUB], [ODT] and [Word docx]; and it can write plain text,
18[txt2tags], [EPUB], [ODT] and [Word docx]; and it can write plain text,
19+[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
19−[Markdown], [reStructuredText], [XHTML], [HTML 5], [LaTeX] (including
20+[reStructuredText], [XHTML], [HTML5], [LaTeX] (including
20−[beamer] slide shows), [ConTeXt], [RTF], [OPML], [DocBook],
21+[`beamer`] slide shows), [ConTeXt], [RTF], [OPML], [DocBook],
21[OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki markup],
22[OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki markup],
22[DokuWiki markup], [Haddock markup], [EPUB] (v2 or v3),
23[DokuWiki markup], [Haddock markup], [EPUB] (v2 or v3),
23−[FictionBook2], [Textile], [groff man] pages, [Emacs Org-Mode],
24+[FictionBook2], [Textile], [groff man] pages, [Emacs Org mode],
24[AsciiDoc], [InDesign ICML], and [Slidy], [Slideous], [DZSlides],
25[AsciiDoc], [InDesign ICML], and [Slidy], [Slideous], [DZSlides],
25[reveal.js] or [S5] HTML slide shows. It can also produce [PDF] output
26[reveal.js] or [S5] HTML slide shows. It can also produce [PDF] output
26on systems where LaTeX is installed.
27on systems where LaTeX is installed.
27
28
28−Pandoc's enhanced version of markdown includes syntax for footnotes,
29+Pandoc's enhanced version of markdown includes syntax for [footnotes],
29−tables, flexible ordered lists, definition lists, fenced code blocks,
30+[tables], flexible [ordered lists], [definition lists], [fenced code blocks],
30−superscript, subscript, strikeout, title blocks, automatic tables of
31+[superscripts and subscripts], [strikeout], [metadata blocks], automatic tables of
31−contents, embedded LaTeX math, citations, and markdown inside HTML block
32+contents, [embedded LaTeX math][Math rendering in HTML], [citations], and [markdown inside HTML block
32−elements. (These enhancements, described below under
33+elements][Extension: `markdown_in_html_blocks`]. (These enhancements, described below under
33−[Pandoc's markdown](#pandocs-markdown), can be disabled using the
34+[Pandoc's markdown], can be disabled using the
34`markdown_strict` input or output format.)
35`markdown_strict` input or output format.)
35
36
36In contrast to most existing tools for converting markdown to HTML, which
37In contrast to most existing tools for converting markdown to HTML, which
@@ -50,6 +51,44 @@ model. While conversions from Pandoc's Markdown to all formats aspire
50to be perfect, conversions from formats more expressive than Pandoc's
51to be perfect, conversions from formats more expressive than Pandoc's
51Markdown can be expected to be lossy.
52Markdown can be expected to be lossy.
52
53
54+[markdown]: http://daringfireball.net/projects/markdown/
55+[CommonMark]: http://commonmark.org
56+[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
57+[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
58+[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
59+[S5]: http://meyerweb.com/eric/tools/s5/
60+[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
61+[Slideous]: http://goessner.net/articles/slideous/
62+[HTML]: http://www.w3.org/html/
63+[HTML5]: http://www.w3.org/TR/html5/
64+[XHTML]: http://www.w3.org/TR/xhtml1/
65+[LaTeX]: http://latex-project.org
66+[`beamer`]: https://ctan.org/pkg/beamer
67+[ConTeXt]: http://pragma-ade.nl
68+[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
69+[DocBook]: http://docbook.org
70+[txt2tags]: http://txt2tags.org
71+[EPUB]: http://idpf.org/epub
72+[OPML]: http://dev.opml.org/spec2.html
73+[OpenDocument]: http://opendocument.xml.org
74+[ODT]: http://en.wikipedia.org/wiki/OpenDocument
75+[Textile]: http://redcloth.org/textile
76+[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
77+[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
78+[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
79+[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
80+[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
81+[Haskell]: https://www.haskell.org
82+[GNU Texinfo]: http://www.gnu.org/software/texinfo/
83+[Emacs Org mode]: http://orgmode.org
84+[AsciiDoc]: http://www.methods.co.nz/asciidoc/
85+[DZSlides]: http://paulrouget.com/dzslides/
86+[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx
87+[PDF]: https://www.adobe.com/pdf/
88+[reveal.js]: http://lab.hakim.se/reveal-js/
89+[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
90+[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
91+
53Using `pandoc`
92Using `pandoc`
54--------------
93--------------
55
94
@@ -69,7 +108,7 @@ document, use the `-s` or `--standalone` flag:
69 pandoc -s -o output.html input.txt
108 pandoc -s -o output.html input.txt
70
109
71For more information on how standalone documents are produced, see
110For more information on how standalone documents are produced, see
72−[Templates](#templates), below.
111+[Templates], below.
73
112
74Instead of a file, an absolute URI may be given. In this case
113Instead of a file, an absolute URI may be given. In this case
75pandoc will fetch the content using HTTP:
114pandoc will fetch the content using HTTP:
@@ -88,7 +127,7 @@ markdown to LaTeX, you could type:
88
127
89 pandoc -f markdown -t latex hello.txt
128 pandoc -f markdown -t latex hello.txt
90
129
91−To convert `hello.html` from html to markdown:
130+To convert `hello.html` from HTML to markdown:
92
131
93 pandoc -f html -t markdown hello.html
132 pandoc -f html -t markdown hello.html
94
133
@@ -112,7 +151,7 @@ be assumed to be markdown unless explicitly specified.
112
151
113Pandoc uses the UTF-8 character encoding for both input and output.
152Pandoc uses the UTF-8 character encoding for both input and output.
114If your local character encoding is not UTF-8, you
153If your local character encoding is not UTF-8, you
115−should pipe input and output through `iconv`:
154+should pipe input and output through [`iconv`]:
116
155
117 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
156 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
118
157
@@ -121,6 +160,8 @@ RTF, OPML, DocBook, and Texinfo), information about
121the character encoding is included in the document header, which
160the character encoding is included in the document header, which
122will only be included if you use the `-s/--standalone` option.
161will only be included if you use the `-s/--standalone` option.
123
162
163+[`iconv`]: http://www.gnu.org/software/libiconv/
164+
124Creating a PDF
165Creating a PDF
125--------------
166--------------
126
167
@@ -130,13 +171,57 @@ Pandoc will use LaTeX to convert it to PDF:
130 pandoc test.txt -o test.pdf
171 pandoc test.txt -o test.pdf
131
172
132Production of a PDF requires that a LaTeX engine be installed (see
173Production of a PDF requires that a LaTeX engine be installed (see
133−`--latex-engine`, below), and assumes that the following LaTeX packages are
174+`--latex-engine`, below), and assumes that the following LaTeX packages
175+are available: [`amsfonts`], [`amsmath`], [`lm`],
134−available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the
176+[`ifxetex`], [`ifluatex`], [`eurosym`], [`listings`] (if the
135−`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`,
177+`--listings` option is used), [`fancyvrb`], [`longtable`],
136−`graphicx` and `grffile` (if the document contains images),
178+[`booktabs`], [`url`], [`graphicx`] and [`grffile`] (if the
137−`hyperref`, `ulem`, `babel` or `polyglossia` (if the `lang` variable is set),
179+document contains images), [`color`], [`hyperref`], [`ulem`],
180+[`geometry`] (with the `geometry` variable set), [`setspace`] (with
181+`linestretch`), and [`babel`] (with `lang`). The use of `xelatex` or
138−`fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra`
182+`lualatex` as the LaTeX engine requires [`fontspec`]; `xelatex` uses
139−and `xunicode` (if `xelatex` is used).
183+[`mathspec`], [`polyglossia`] (with `lang`), [`xecjk`], and
184+[`bidi`] (with the `dir` variable set). The [`upquote`] and
185+[`microtype`] packages are used if available, and [`csquotes`] will
186+be used for [smart punctuation] if added to the template. The
187+[`natbib`], [`biblatex`], [`bibtex`], and [`biber`] packages can
188+optionally be used for [citation rendering]. These are included with
189+all recent versions of [TeX Live].
190+
191+PDF output can be controlled using [variables for LaTeX].
192+
193+[`amsfonts`]: https://ctan.org/pkg/amsfonts
194+[`amsmath`]: https://ctan.org/pkg/amsmath
195+[`lm`]: https://ctan.org/pkg/lm
196+[`ifxetex`]: https://ctan.org/pkg/ifxetex
197+[`ifluatex`]: https://ctan.org/pkg/ifluatex
198+[`eurosym`]: https://ctan.org/pkg/eurosym
199+[`listings`]: https://ctan.org/pkg/listings
200+[`fancyvrb`]: https://ctan.org/pkg/fancyvrb
201+[`longtable`]: https://ctan.org/pkg/longtable
202+[`booktabs`]: https://ctan.org/pkg/booktabs
203+[`url`]: https://ctan.org/pkg/url
204+[`graphicx`]: https://ctan.org/pkg/graphicx
205+[`grffile`]: https://ctan.org/pkg/grffile
206+[`geometry`]: https://ctan.org/pkg/geometry
207+[`setspace`]: https://ctan.org/pkg/setspace
208+[`color`]: http://ctan.org/pkg/color
209+[`xecjk`]: https://ctan.org/pkg/xecjk
210+[`hyperref`]: https://ctan.org/pkg/hyperref
211+[`ulem`]: https://ctan.org/pkg/ulem
212+[`babel`]: https://ctan.org/pkg/babel
213+[`bidi`]: https://ctan.org/pkg/bidi
214+[`mathspec`]: https://ctan.org/pkg/mathspec
215+[`polyglossia`]: https://ctan.org/pkg/polyglossia
216+[`fontspec`]: https://ctan.org/pkg/fontspec
217+[`upquote`]: https://ctan.org/pkg/upquote
218+[`microtype`]: https://ctan.org/pkg/microtype
219+[`csquotes`]: https://ctan.org/pkg/csquotes
220+[`natbib`]: https://ctan.org/pkg/natbib
221+[`biblatex`]: https://ctan.org/pkg/biblatex
222+[`bibtex`]: https://ctan.org/pkg/bibtex
223+[`biber`]: https://ctan.org/pkg/biber
224+[TeX Live]: http://www.tug.org/texlive/
140
225
141`hsmarkdown`
226`hsmarkdown`
142------------
227------------
@@ -146,14 +231,10 @@ a symbolic link to the `pandoc` executable called `hsmarkdown`. When
146invoked under the name `hsmarkdown`, `pandoc` will behave as if
231invoked under the name `hsmarkdown`, `pandoc` will behave as if
147invoked with `-f markdown_strict --email-obfuscation=references`,
232invoked with `-f markdown_strict --email-obfuscation=references`,
148and all command-line options will be treated as regular arguments.
233and all command-line options will be treated as regular arguments.
149−However, this approach does not work under Cygwin, due to problems with
234+This approach does not work under [Cygwin], due to problems with
150its simulation of symbolic links.
235its simulation of symbolic links.
151
236
152−[Cygwin]: http://www.cygwin.com/
237+[Cygwin]: https://cygwin.com
153−[`iconv`]: http://www.gnu.org/software/libiconv/
154−[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network"
155−[TeX Live]: http://www.tug.org/texlive/
156−[MacTeX]: http://www.tug.org/mactex/
157
238
158Options
239Options
159=======
240=======
@@ -166,23 +247,23 @@ General options
166: Specify input format. *FORMAT* can be `native` (native Haskell),
247: Specify input format. *FORMAT* can be `native` (native Haskell),
167 `json` (JSON version of native AST), `markdown` (pandoc's
248 `json` (JSON version of native AST), `markdown` (pandoc's
168 extended markdown), `markdown_strict` (original unextended
249 extended markdown), `markdown_strict` (original unextended
169− markdown), `markdown_phpextra` (PHP Markdown Extra extended
250+ markdown), `markdown_phpextra` (PHP Markdown Extra),
170− markdown), `markdown_github` (github extended markdown),
251+ `markdown_github` (GitHub-Flavored Markdown),
171 `commonmark` (CommonMark markdown), `textile` (Textile), `rst`
252 `commonmark` (CommonMark markdown), `textile` (Textile), `rst`
172 (reStructuredText), `html` (HTML), `docbook` (DocBook), `t2t`
253 (reStructuredText), `html` (HTML), `docbook` (DocBook), `t2t`
173 (txt2tags), `docx` (docx), `odt` (ODT), `epub` (EPUB), `opml` (OPML),
254 (txt2tags), `docx` (docx), `odt` (ODT), `epub` (EPUB), `opml` (OPML),
174− `org` (Emacs Org-mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki
255+ `org` (Emacs Org mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki
175 markup), `haddock` (Haddock markup), or `latex` (LaTeX). If
256 markup), `haddock` (Haddock markup), or `latex` (LaTeX). If
176 `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`, the
257 `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`, the
177 input will be treated as literate Haskell source: see [Literate
258 input will be treated as literate Haskell source: see [Literate
178− Haskell support](#literate-haskell-support), below. Markdown
259+ Haskell support], below. Markdown
179 syntax extensions can be individually enabled or disabled by
260 syntax extensions can be individually enabled or disabled by
180 appending `+EXTENSION` or `-EXTENSION` to the format name. So, for
261 appending `+EXTENSION` or `-EXTENSION` to the format name. So, for
181 example, `markdown_strict+footnotes+definition_lists` is strict
262 example, `markdown_strict+footnotes+definition_lists` is strict
182 markdown with footnotes and definition lists enabled, and
263 markdown with footnotes and definition lists enabled, and
183 `markdown-pipe_tables+hard_line_breaks` is pandoc's markdown
264 `markdown-pipe_tables+hard_line_breaks` is pandoc's markdown
184 without pipe tables and with hard line breaks. See [Pandoc's
265 without pipe tables and with hard line breaks. See [Pandoc's
185− markdown](#pandocs-markdown), below, for a list of extensions and
266+ markdown], below, for a list of extensions and
186 their names.
267 their names.
187
268
188`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
269`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
@@ -191,12 +272,12 @@ General options
191 `json` (JSON version of native AST), `plain` (plain text),
272 `json` (JSON version of native AST), `plain` (plain text),
192 `markdown` (pandoc's extended markdown), `markdown_strict`
273 `markdown` (pandoc's extended markdown), `markdown_strict`
193 (original unextended markdown), `markdown_phpextra` (PHP Markdown
274 (original unextended markdown), `markdown_phpextra` (PHP Markdown
194− extra extended markdown), `markdown_github` (GitHub-flavored
275+ Extra), `markdown_github` (GitHub-Flavored
195− markdown), `commonmark` (CommonMark markdown), `rst`
276+ Markdown), `commonmark` (CommonMark markdown), `rst`
196− (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex`
277+ (reStructuredText), `html` (XHTML), `html5` (HTML5), `latex`
197 (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt),
278 (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt),
198 `man` (groff man), `mediawiki` (MediaWiki markup), `dokuwiki`
279 `man` (groff man), `mediawiki` (MediaWiki markup), `dokuwiki`
199− (DokuWiki markup), `textile` (Textile), `org` (Emacs Org-Mode),
280+ (DokuWiki markup), `textile` (Textile), `org` (Emacs Org mode),
200 `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook),
281 `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook),
201 `opendocument` (OpenDocument), `odt` (OpenOffice text document),
282 `opendocument` (OpenDocument), `odt` (OpenOffice text document),
202 `docx` (Word docx), `haddock` (Haddock markup), `rtf` (rich text
283 `docx` (Word docx), `haddock` (Haddock markup), `rtf` (rich text
@@ -207,13 +288,13 @@ General options
207 HTML5 + javascript slide show), `revealjs` (reveal.js HTML5 +
288 HTML5 + javascript slide show), `revealjs` (reveal.js HTML5 +
208 javascript slide show), `s5` (S5 HTML and javascript slide show),
289 javascript slide show), `s5` (S5 HTML and javascript slide show),
209 or the path of a custom lua writer (see [Custom
290 or the path of a custom lua writer (see [Custom
210− writers](#custom-writers), below). Note that `odt`, `epub`, and
291+ writers], below). Note that `odt`, `epub`, and
211 `epub3` output will not be directed to *stdout*; an output
292 `epub3` output will not be directed to *stdout*; an output
212 filename must be specified using the `-o/--output` option. If
293 filename must be specified using the `-o/--output` option. If
213 `+lhs` is appended to `markdown`, `rst`, `latex`, `beamer`,
294 `+lhs` is appended to `markdown`, `rst`, `latex`, `beamer`,
214 `html`, or `html5`, the output will be rendered as literate
295 `html`, or `html5`, the output will be rendered as literate
215 Haskell source: see [Literate Haskell
296 Haskell source: see [Literate Haskell
216− support](#literate-haskell-support), below. Markdown syntax
297+ support], below. Markdown syntax
217 extensions can be individually enabled or disabled by appending
298 extensions can be individually enabled or disabled by appending
218 `+EXTENSION` or `-EXTENSION` to the format name, as described
299 `+EXTENSION` or `-EXTENSION` to the format name, as described
219 above under `-f`.
300 above under `-f`.
@@ -334,12 +415,8 @@ Reader options
334 Filters may be written in any language. `Text.Pandoc.JSON`
415 Filters may be written in any language. `Text.Pandoc.JSON`
335 exports `toJSONFilter` to facilitate writing filters in Haskell.
416 exports `toJSONFilter` to facilitate writing filters in Haskell.
336 Those who would prefer to write filters in python can use the
417 Those who would prefer to write filters in python can use the
337− module `pandocfilters`, installable from PyPI. See
418+ module [`pandocfilters`], installable from PyPI. There are also
338− <http://github.com/jgm/pandocfilters> for the module and several
339− examples. There are also pandoc filter libraries in
419+ pandoc filter libraries in [PHP], [perl], and [javascript/node.js].
340− [PHP](https://github.com/vinai/pandocfilters-php),
341− [perl](https://metacpan.org/pod/Pandoc::Filter), and
342− [javascript/node.js](https://github.com/mvhenderson/pandoc-filter-node).
343
420
344 Note that the *EXECUTABLE* will be sought in the user's
421 Note that the *EXECUTABLE* will be sought in the user's
345 `PATH`, and not in the working directory, if no directory is
422 `PATH`, and not in the working directory, if no directory is
@@ -391,6 +468,11 @@ Reader options
391 references in the document so they point to the extracted files.
468 references in the document so they point to the extracted files.
392 This option only affects the docx and epub readers.
469 This option only affects the docx and epub readers.
393
470
471+[`pandocfilters`]: https://github.com/jgm/pandocfilters
472+[PHP]: https://github.com/vinai/pandocfilters-php
473+[perl]: https://metacpan.org/pod/Pandoc::Filter
474+[javascript/node.js]: https://github.com/mvhenderson/pandoc-filter-node
475+
394General writer options
476General writer options
395----------------------
477----------------------
396
478
@@ -404,7 +486,7 @@ General writer options
404`--template=`*FILE*
486`--template=`*FILE*
405
487
406: Use *FILE* as a custom template for the generated document. Implies
488: Use *FILE* as a custom template for the generated document. Implies
407− `--standalone`. See [Templates](#templates) below for a description
489+ `--standalone`. See [Templates], below, for a description
408 of template syntax. If no extension is specified, an extension
490 of template syntax. If no extension is specified, an extension
409 corresponding to the writer will be added, so that `--template=special`
491 corresponding to the writer will be added, so that `--template=special`
410 looks for `special.html` for HTML output. If the template is not
492 looks for `special.html` for HTML output. If the template is not
@@ -535,7 +617,7 @@ Options affecting specific writers
535
617
536`--atx-headers`
618`--atx-headers`
537
619
538−: Use ATX style headers in markdown and asciidoc output. The default is
620+: Use ATX-style headers in markdown and asciidoc output. The default is
539 to use setext-style headers for levels 1-2, and then ATX headers.
621 to use setext-style headers for levels 1-2, and then ATX headers.
540
622
541`--chapters`
623`--chapters`
@@ -577,7 +659,7 @@ Options affecting specific writers
577
659
578`--listings`
660`--listings`
579
661
580−: Use the `listings` package for LaTeX code blocks
662+: Use the [`listings`] package for LaTeX code blocks
581
663
582`-i`, `--incremental`
664`-i`, `--incremental`
583
665
@@ -592,14 +674,14 @@ Options affecting specific writers
592 slide show into sections; headers below this level create
674 slide show into sections; headers below this level create
593 subheads within a slide. The default is to set the slide level
675 subheads within a slide. The default is to set the slide level
594 based on the contents of the document; see
676 based on the contents of the document; see
595− [Structuring the slide show](#structuring-the-slide-show), below.
677+ [Structuring the slide show].
596
678
597`--section-divs`
679`--section-divs`
598
680
599: Wrap sections in `<div>` tags (or `<section>` tags in HTML5),
681: Wrap sections in `<div>` tags (or `<section>` tags in HTML5),
600 and attach identifiers to the enclosing `<div>` (or `<section>`)
682 and attach identifiers to the enclosing `<div>` (or `<section>`)
601 rather than the header itself. See
683 rather than the header itself. See
602− [Header identifiers](#header-identifiers), below.
684+ [Header identifiers], below.
603
685
604`--email-obfuscation=none`|`javascript`|`references`
686`--email-obfuscation=none`|`javascript`|`references`
605
687
@@ -674,8 +756,7 @@ Options affecting specific writers
674`--epub-metadata=`*FILE*
756`--epub-metadata=`*FILE*
675
757
676: Look in the specified XML file for metadata for the EPUB.
758: Look in the specified XML file for metadata for the EPUB.
677− The file should contain a series of Dublin Core elements,
759+ The file should contain a series of [Dublin Core elements].
678− as documented at <http://dublincore.org/documents/dces/>.
679 For example:
760 For example:
680
761
681 <dc:rights>Creative Commons</dc:rights>
762 <dc:rights>Creative Commons</dc:rights>
@@ -751,6 +832,9 @@ Options affecting specific writers
751 If used multiple times, the arguments are provided with spaces between
832 If used multiple times, the arguments are provided with spaces between
752 them. Note that no check for duplicate options is done.
833 them. Note that no check for duplicate options is done.
753
834
835+[Dublin Core elements]: http://dublincore.org/documents/dces/
836+[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime
837+
754Citation rendering
838Citation rendering
755------------------
839------------------
756
840
@@ -781,15 +865,15 @@ Citation rendering
781
865
782`--natbib`
866`--natbib`
783
867
784−: Use natbib for citations in LaTeX output. This option is not for use
868+: Use [`natbib`] for citations in LaTeX output. This option is not for use
785 with the `pandoc-citeproc` filter or with PDF output. It is intended for
869 with the `pandoc-citeproc` filter or with PDF output. It is intended for
786− use in producing a LaTeX file that can be processed with bibtex.
870+ use in producing a LaTeX file that can be processed with [`bibtex`].
787
871
788`--biblatex`
872`--biblatex`
789
873
790−: Use biblatex for citations in LaTeX output. This option is not for use
874+: Use [`biblatex`] for citations in LaTeX output. This option is not for use
791 with the `pandoc-citeproc` filter or with PDF output. It is intended for
875 with the `pandoc-citeproc` filter or with PDF output. It is intended for
792− use in producing a LaTeX file that can be processed with bibtex or biber.
876+ use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`].
793
877
794Math rendering in HTML
878Math rendering in HTML
795----------------------
879----------------------
@@ -806,7 +890,7 @@ Math rendering in HTML
806
890
807`--mathml`[`=`*URL*]
891`--mathml`[`=`*URL*]
808
892
809−: Convert TeX math to MathML (in `docbook` as well as `html` and `html5`).
893+: Convert TeX math to [MathML] (in `docbook` as well as `html` and `html5`).
810 In standalone `html` output, a small javascript (or a link to such a
894 In standalone `html` output, a small javascript (or a link to such a
811 script if a *URL* is supplied) will be inserted that allows the MathML to
895 script if a *URL* is supplied) will be inserted that allows the MathML to
812 be viewed on some browsers.
896 be viewed on some browsers.
@@ -856,6 +940,14 @@ Math rendering in HTML
856 not specified, a link to the KaTeX CDN will be inserted. Note that this
940 not specified, a link to the KaTeX CDN will be inserted. Note that this
857 option does not imply `--katex`.
941 option does not imply `--katex`.
858
942
943+[MathML]: http://www.w3.org/Math/
944+[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
945+[jsMath]: http://www.math.union.edu/~dpvc/jsmath/
946+[MathJax]: https://www.mathjax.org
947+[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/
948+[mimeTeX]: http://www.forkosh.com/mimetex.html
949+[KaTeX]: https://github.com/Khan/KaTeX
950+
859Options for wrapper scripts
951Options for wrapper scripts
860---------------------------
952---------------------------
861
953
@@ -881,13 +973,6 @@ Options for wrapper scripts
881
973
882 pandoc -o foo.html -s
974 pandoc -o foo.html -s
883
975
884−[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
885−[jsMath]: http://www.math.union.edu/~dpvc/jsmath/
886−[MathJax]: http://www.mathjax.org/
887−[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/
888−[mimeTeX]: http://www.forkosh.com/mimetex.html
889−[CSL]: http://CitationStyles.org
890−
891Templates
976Templates
892=========
977=========
893
978
@@ -907,7 +992,8 @@ customize the `default.latex` template.
907
992
908Templates contain *variables*, which allow for the inclusion of
993Templates contain *variables*, which allow for the inclusion of
909arbitrary information at any point in the file. Variables may be set
994arbitrary information at any point in the file. Variables may be set
910−within the document using YAML metadata. They may also be set at the
995+within the document using [YAML metadata blocks][Extension: `yaml_metadata_block`].
996+They may also be set at the
911command line using the `-V/--variable` option: variables set in this
997command line using the `-V/--variable` option: variables set in this
912way override metadata fields with the same name.
998way override metadata fields with the same name.
913
999
@@ -915,8 +1001,22 @@ Variables set by pandoc
915-----------------------
1001-----------------------
916
1002
917Some variables are set automatically by pandoc. These vary somewhat
1003Some variables are set automatically by pandoc. These vary somewhat
918−depending on the output format, but include metadata fields (such
1004+depending on the output format, but include metadata fields as well as the following:
919−as `title`, `author`, and `date`) as well as the following:
1005+
1006+`title`, `author`, `date`
1007+: allow identification of basic aspects of the document.
1008+ Included in PDF metadata through LaTeX.
1009+ These can be set through a [pandoc title block][Extension: `pandoc_title_block`],
1010+ which allows for multiple authors, or through a YAML metadata block:
1011+
1012+ ---
1013+ author:
1014+ - Aristotle
1015+ - Peter Abelard
1016+ ...
1017+
1018+`abstract`
1019+: allows for specification of document summary in LaTeX and Word docx
920
1020
921`header-includes`
1021`header-includes`
922: contents specified by `-H/--include-in-header` (may have multiple
1022: contents specified by `-H/--include-in-header` (may have multiple
@@ -963,14 +1063,17 @@ Language variables
963 override the base direction in some output formats.
1063 override the base direction in some output formats.
964 This may not always be necessary if the final renderer
1064 This may not always be necessary if the final renderer
965 (e.g. the browser, when generating HTML) supports the
1065 (e.g. the browser, when generating HTML) supports the
966− [Unicode Bidirectional Algorithm][uba-basics].
1066+ [Unicode Bidirectional Algorithm].
1067+
1068+ LaTeX and ConTeXt assume by default that all text is left-to-right.
1069+ Setting `dir: ltr` enables bidirectional text handling in a document
1070+ whose base direction is left-to-right but contains some right-to-left script.
967
1071
968 When using LaTeX for bidirectional documents, only the `xelatex` engine
1072 When using LaTeX for bidirectional documents, only the `xelatex` engine
969− is fully supported (see `--latex-engine`).
1073+ is fully supported (use `--latex-engine=xelatex`).
970− Setting the `dir` variable enables bidirectional text
1074+
971− handling in LaTeX and ConTeXt: set `dir: ltr` for
1075+[BCP 47]: https://tools.ietf.org/html/bcp47
972− documents that also contain some right-to-left script,
1076+[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics
973− even if the base direction is the default left-to-right.
974
1077
975Variables for slides
1078Variables for slides
976--------------------
1079--------------------
@@ -992,69 +1095,67 @@ Variables for slides
992: reveal.js or LaTeX beamer theme
1095: reveal.js or LaTeX beamer theme
993
1096
994`transition`
1097`transition`
995−: reveal.js transition
1098+: reveal.js transition: `cube`, `page`, `concave`, `zoom`, `linear`, `fade`, or `none`
1099+
1100+`center`
1101+: enables vertical centering of slides in reveal.js
1102+
1103+`maxScale`
1104+: bounds for smallest/largest possible content scale in reveal.js (default: 1.5)
1105+
1106+`slideNumber`
1107+: enables display of the page number of the current slide in reveal.js
1108+
1109+`colortheme`, `fonttheme`, `innertheme`, `outertheme`
1110+: themes for LaTeX [`beamer`] documents
996
1111
997Variables for LaTeX
1112Variables for LaTeX
998-------------------
1113-------------------
999
1114
1000`fontsize`
1115`fontsize`
1001−: font size (10pt, 11pt, 12pt) for LaTeX documents
1116+: font size (e.g. `10pt`, `12pt`) for LaTeX documents
1002
1117
1003`documentclass`
1118`documentclass`
1004−: document class for LaTeX documents, e.g. `article`, `report`, `book`
1119+: document class for LaTeX documents, e.g. [`article`], [`report`], [`book`], [`memoir`]
1005
1120
1006`classoption`
1121`classoption`
1007−: option for LaTeX documentclass, e.g. `oneside`; may be repeated
1122+: option for LaTeX document class, e.g. `oneside`; may be repeated
1008 for multiple options
1123 for multiple options
1009
1124
1010`geometry`
1125`geometry`
1011−: options for LaTeX `geometry` package, e.g. `margin=1in`;
1126+: option for LaTeX [`geometry`] package, e.g. `margin=1in`;
1012 may be repeated for multiple options
1127 may be repeated for multiple options
1013
1128
1014`linestretch`
1129`linestretch`
1015−: adjusts line spacing in LaTeX documents using the `setspace`
1130+: adjusts line spacing in LaTeX documents using the [`setspace`]
1016 package, e.g. `onehalfspacing`, `doublespacing`
1131 package, e.g. `onehalfspacing`, `doublespacing`
1017
1132
1018`fontfamily`
1133`fontfamily`
1019−: font package to use for LaTeX documents (with pdflatex):
1134+: font package for LaTeX documents (with `pdflatex`):
1020− TeX Live has `bookman` (Bookman), `utopia` or `fourier` (Utopia),
1135+ [TeX Live] includes many options, documented in the [LaTeX Font Catalogue].
1021− `fouriernc` (New Century Schoolbook), `times` or `txfonts` (Times),
1136+ The default is [Latin Modern][`lm`].
1022− `mathpazo` or `pxfonts` or `mathpple` (Palatino),
1023− `libertine` (Linux Libertine), `arev` (Arev Sans),
1024− and the default `lmodern`, among others.
1025
1137
1026`fontfamilyoptions`
1138`fontfamilyoptions`
1027−: options to use with `fontfamily` package: e.g. `osf,sc` with
1139+: options for package used as `fontfamily`: e.g. `osf,sc` with
1028− `fontfamily` set to `mathpazo` provides Palatino with old-style
1140+ `fontfamily` set to [`mathpazo`] provides Palatino with old-style
1029 figures and true small caps
1141 figures and true small caps
1030
1142
1031`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
1143`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
1032: fonts for LaTeX documents (works only with `xelatex` and
1144: fonts for LaTeX documents (works only with `xelatex` and
1033 `lualatex`): takes the name of any system font, using the
1145 `lualatex`): takes the name of any system font, using the
1034− `fontspec` package. Note that if `CJKmainfont` is used,
1146+ [`fontspec`] package. Note that if `CJKmainfont` is used,
1035− the `xeCJK` package must be available.
1147+ the [`xecjk`] package must be available.
1036
1148
1037`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
1149`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
1038: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
1150: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
1039 `CJKmainfont` in `xelatex` and `lualatex`. Allows for any choices
1151 `CJKmainfont` in `xelatex` and `lualatex`. Allows for any choices
1040− available through `fontspec`, such as the OpenType features
1152+ available through [`fontspec`], such as the OpenType features
1041 `Numbers=OldStyle,Numbers=Proportional`.
1153 `Numbers=OldStyle,Numbers=Proportional`.
1042
1154
1043−`colortheme`, `fonttheme`, `innertheme`, `outertheme`
1044−: themes for LaTeX beamer documents
1045−
1046−`linkcolor`
1155+`linkcolor`, `toccolor`, `urlcolor`, `citecolor`
1047−: color for internal links in LaTeX documents, e.g. `red`, `green`,
1156+: color for internal links, links in table of contents, external links,
1157+ and citation links in LaTeX documents, using options available through
1048− `magenta`, `cyan`, `blue`, `black`
1158+ [`color`] package, e.g. `red`, `green`, `magenta`, `cyan`, `blue`, `black`
1049−
1050−`toccolor`
1051−: color for links in table of contents in LaTeX documents
1052−
1053−`urlcolor`
1054−: color for external links in LaTeX documents
1055−
1056−`citecolor`
1057−: color for citation links in LaTeX documents
1058
1159
1059`links-as-notes`
1160`links-as-notes`
1060: causes links to be printed as footnotes in LaTeX documents
1161: causes links to be printed as footnotes in LaTeX documents
@@ -1080,6 +1181,13 @@ Variables for LaTeX
1080`biblio-style`
1181`biblio-style`
1081: bibliography style in LaTeX, when used with `--natbib`
1182: bibliography style in LaTeX, when used with `--natbib`
1082
1183
1184+[`article`]: https://ctan.org/pkg/article
1185+[`report`]: https://ctan.org/pkg/report
1186+[`book`]: https://ctan.org/pkg/book
1187+[`memoir`]: https://ctan.org/pkg/memoir
1188+[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/
1189+[`mathpazo`]: https://ctan.org/pkg/mathpazo
1190+
1083Variables for man pages
1191Variables for man pages
1084-----------------------
1192-----------------------
1085
1193
@@ -1138,10 +1246,11 @@ an object as its value. So, for example:
1138If you use custom templates, you may need to revise them as pandoc
1246If you use custom templates, you may need to revise them as pandoc
1139changes. We recommend tracking the changes in the default templates,
1247changes. We recommend tracking the changes in the default templates,
1140and modifying your custom templates accordingly. An easy way to do this
1248and modifying your custom templates accordingly. An easy way to do this
1141−is to fork the pandoc-templates repository
1249+is to fork the [pandoc-templates] repository and merge in changes after each
1142−(<http://github.com/jgm/pandoc-templates>) and merge in changes after each
1143pandoc release.
1250pandoc release.
1144
1251
1252+[pandoc-templates]: https://github.com/jgm/pandoc-templates
1253+
1145Pandoc's markdown
1254Pandoc's markdown
1146=================
1255=================
1147
1256
@@ -1194,7 +1303,7 @@ are ignored.
1194Headers
1303Headers
1195-------
1304-------
1196
1305
1197−There are two kinds of headers, Setext and atx.
1306+There are two kinds of headers: Setext and ATX.
1198
1307
1199### Setext-style headers ###
1308### Setext-style headers ###
1200
1309
@@ -1208,12 +1317,12 @@ A setext-style header is a line of text "underlined" with a row of `=` signs
1208 ------------------
1317 ------------------
1209
1318
1210The header text can contain inline formatting, such as emphasis (see
1319The header text can contain inline formatting, such as emphasis (see
1211−[Inline formatting](#inline-formatting), below).
1320+[Inline formatting], below).
1212
1321
1213
1322
1214−### Atx-style headers ###
1323+### ATX-style headers ###
1215
1324
1216−An Atx-style header consists of one to six `#` signs and a line of
1325+An ATX-style header consists of one to six `#` signs and a line of
1217text, optionally followed by any number of `#` signs. The number of
1326text, optionally followed by any number of `#` signs. The number of
1218`#` signs at the beginning of the line is the header level:
1327`#` signs at the beginning of the line is the header level:
1219
1328
@@ -1237,7 +1346,7 @@ wrapping). Consider, for example:
1237 #22, for example, and #5.
1346 #22, for example, and #5.
1238
1347
1239
1348
1240−### Header identifiers ###
1349+### Header identifiers
1241
1350
1242#### Extension: `header_attributes` ####
1351#### Extension: `header_attributes` ####
1243
1352
@@ -1429,7 +1538,7 @@ of the verbatim text, and is removed in the output.
1429Note: blank lines in the verbatim text need not begin with four spaces.
1538Note: blank lines in the verbatim text need not begin with four spaces.
1430
1539
1431
1540
1432−### Fenced code blocks ###
1541+### Fenced code blocks
1433
1542
1434#### Extension: `fenced_code_blocks` ####
1543#### Extension: `fenced_code_blocks` ####
1435
1544
@@ -1636,7 +1745,7 @@ pandoc interprets it that way.
1636 [markdown syntax guide]:
1745 [markdown syntax guide]:
1637 http://daringfireball.net/projects/markdown/syntax#list
1746 http://daringfireball.net/projects/markdown/syntax#list
1638
1747
1639−### Ordered lists ###
1748+### Ordered lists
1640
1749
1641Ordered lists work just like bulleted lists, except that the items
1750Ordered lists work just like bulleted lists, except that the items
1642begin with enumerators rather than bullets.
1751begin with enumerators rather than bullets.
@@ -1716,7 +1825,7 @@ If default list markers are desired, use `#.`:
1716 #. three
1825 #. three
1717
1826
1718
1827
1719−### Definition lists ###
1828+### Definition lists
1720
1829
1721#### Extension: `definition_lists` ####
1830#### Extension: `definition_lists` ####
1722
1831
@@ -1770,13 +1879,10 @@ definition:
1770Note that space between items in a definition list is required.
1879Note that space between items in a definition list is required.
1771(A variant that loosens this requirement, but disallows "lazy"
1880(A variant that loosens this requirement, but disallows "lazy"
1772hard wrapping, can be activated with `compact_definition_lists`: see
1881hard wrapping, can be activated with `compact_definition_lists`: see
1773−[Non-pandoc extensions](#non-pandoc-extensions), below.)
1882+[Non-pandoc extensions], below.)
1774
1883
1775[^3]: I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html).
1884[^3]: I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html).
1776
1885
1777−[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
1778−
1779−
1780### Numbered example lists ###
1886### Numbered example lists ###
1781
1887
1782#### Extension: `example_lists` ####
1888#### Extension: `example_lists` ####
@@ -2008,7 +2114,7 @@ arbitrary block elements (multiple paragraphs, code blocks, lists,
2008etc.). Alignments are not supported, nor are cells that span multiple
2114etc.). Alignments are not supported, nor are cells that span multiple
2009columns or rows. Grid tables can be created easily using [Emacs table mode].
2115columns or rows. Grid tables can be created easily using [Emacs table mode].
2010
2116
2011− [Emacs table mode]: http://table.sourceforge.net/
2117+[Emacs table mode]: http://table.sourceforge.net/
2012
2118
2013#### Extension: `pipe_tables` ####
2119#### Extension: `pipe_tables` ####
2014
2120
@@ -2022,7 +2128,7 @@ Pipe tables look like this:
2022
2128
2023 : Demonstration of pipe table syntax.
2129 : Demonstration of pipe table syntax.
2024
2130
2025−The syntax is [the same as in PHP markdown extra]. The beginning and
2131+The syntax is identical to [PHP Markdown Extra tables]. The beginning and
2026ending pipe characters are optional, but pipes are required between all
2132ending pipe characters are optional, but pipes are required between all
2027columns. The colons indicate column alignment as shown. The header
2133columns. The colons indicate column alignment as shown. The header
2028cannot be omitted. To simulate a headerless table, include a header
2134cannot be omitted. To simulate a headerless table, include a header
@@ -2044,9 +2150,6 @@ output, the cells produced by pipe tables will not wrap, since there
2044is no information available about relative widths. If you want content
2150is no information available about relative widths. If you want content
2045to wrap within cells, use multiline or grid tables.
2151to wrap within cells, use multiline or grid tables.
2046
2152
2047− [the same as in PHP markdown extra]:
2048− http://michelf.ca/projects/php-markdown/extra/#table
2049−
2050Note: Pandoc also recognizes pipe tables of the following
2153Note: Pandoc also recognizes pipe tables of the following
2051form, as can be produced by Emacs' orgtbl-mode:
2154form, as can be produced by Emacs' orgtbl-mode:
2052
2155
@@ -2059,10 +2162,12 @@ The difference is that `+` is used instead of `|`. Other orgtbl features
2059are not supported. In particular, to get non-default column alignment,
2162are not supported. In particular, to get non-default column alignment,
2060you'll need to add colons as above.
2163you'll need to add colons as above.
2061
2164
2165+[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table
2166+
2062Metadata blocks
2167Metadata blocks
2063---------------
2168---------------
2064
2169
2065−#### Extension: `pandoc_title_block` ####
2170+#### Extension: `pandoc_title_block`
2066
2171
2067If the file begins with a title block
2172If the file begins with a title block
2068
2173
@@ -2138,7 +2243,7 @@ will also have "Pandoc User Manuals" in the footer.
2138
2243
2139will also have "Version 4.0" in the header.
2244will also have "Version 4.0" in the header.
2140
2245
2141−#### Extension: `yaml_metadata_block` ####
2246+#### Extension: `yaml_metadata_block`
2142
2247
2143A YAML metadata block is a valid YAML object, delimited by a line of three
2248A YAML metadata block is a valid YAML object, delimited by a line of three
2144hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots
2249hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots
@@ -2257,8 +2362,8 @@ correct output, converting straight quotes to curly quotes, `---` to
2257em-dashes, `--` to en-dashes, and `...` to ellipses. Nonbreaking spaces
2362em-dashes, `--` to en-dashes, and `...` to ellipses. Nonbreaking spaces
2258are inserted after certain abbreviations, such as "Mr."
2363are inserted after certain abbreviations, such as "Mr."
2259
2364
2260−Note: if your LaTeX template uses the `csquotes` package, pandoc will
2365+Note: if your LaTeX template calls for the [`csquotes`] package, pandoc will
2261−detect automatically this and use `\enquote{...}` for quoted text.
2366+detect this automatically and use `\enquote{...}` for quoted text.
2262
2367
2263Inline formatting
2368Inline formatting
2264-----------------
2369-----------------
@@ -2289,7 +2394,7 @@ just part of a word, use `*`:
2289 feas*ible*, not feas*able*.
2394 feas*ible*, not feas*able*.
2290
2395
2291
2396
2292−### Strikeout ###
2397+### Strikeout
2293
2398
2294#### Extension: `strikeout` ####
2399#### Extension: `strikeout` ####
2295
2400
@@ -2299,7 +2404,7 @@ with `~~`. Thus, for example,
2299 This ~~is deleted text.~~
2404 This ~~is deleted text.~~
2300
2405
2301
2406
2302−### Superscripts and subscripts ###
2407+### Superscripts and subscripts
2303
2408
2304#### Extension: `superscript`, `subscript` ####
2409#### Extension: `superscript`, `subscript` ####
2305
2410
@@ -2342,7 +2447,7 @@ work in verbatim contexts:
2342#### Extension: `inline_code_attributes` ####
2447#### Extension: `inline_code_attributes` ####
2343
2448
2344Attributes can be attached to verbatim text, just as with
2449Attributes can be attached to verbatim text, just as with
2345−[fenced code blocks](#fenced-code-blocks):
2450+[fenced code blocks]:
2346
2451
2347 `<$>`{.haskell}
2452 `<$>`{.haskell}
2348
2453
@@ -2371,12 +2476,11 @@ them and they won't be treated as math delimiters.
2371TeX math will be printed in all output formats. How it is rendered
2476TeX math will be printed in all output formats. How it is rendered
2372depends on the output format:
2477depends on the output format:
2373
2478
2374−Markdown, LaTeX, Org-Mode, ConTeXt
2479+Markdown, LaTeX, Emacs Org mode, ConTeXt
2375 ~ It will appear verbatim between `$` characters.
2480 ~ It will appear verbatim between `$` characters.
2376
2481
2377reStructuredText
2482reStructuredText
2378− ~ It will be rendered using an interpreted text role `:math:`, as described
2483+ ~ It will be rendered using an [interpreted text role `:math:`].
2379− [here](http://docutils.sourceforge.net/docs/ref/rst/roles.html#math)
2380
2484
2381AsciiDoc
2485AsciiDoc
2382 ~ It will be rendered as `latexmath:[...]`.
2486 ~ It will be rendered as `latexmath:[...]`.
@@ -2397,8 +2501,8 @@ RTF, OpenDocument, ODT
2397 ~ It will be rendered, if possible, using unicode characters,
2501 ~ It will be rendered, if possible, using unicode characters,
2398 and will otherwise appear verbatim.
2502 and will otherwise appear verbatim.
2399
2503
2400−Docbook
2504+DocBook
2401− ~ If the `--mathml` flag is used, it will be rendered using mathml
2505+ ~ If the `--mathml` flag is used, it will be rendered using MathML
2402 in an `inlineequation` or `informalequation` tag. Otherwise it
2506 in an `inlineequation` or `informalequation` tag. Otherwise it
2403 will be rendered, if possible, using unicode characters.
2507 will be rendered, if possible, using unicode characters.
2404
2508
@@ -2440,7 +2544,7 @@ HTML, Slidy, DZSlides, S5, EPUB
2440 5. If the `--gladtex` option is used, TeX formulas will be enclosed
2544 5. If the `--gladtex` option is used, TeX formulas will be enclosed
2441 in `<eq>` tags in the HTML output. The resulting `htex` file may then
2545 in `<eq>` tags in the HTML output. The resulting `htex` file may then
2442 be processed by [gladTeX], which will produce image files for each
2546 be processed by [gladTeX], which will produce image files for each
2443− formula and an `html` file with links to these images. So, the
2547+ formula and an HTML file with links to these images. So, the
2444 procedure is:
2548 procedure is:
2445
2549
2446 pandoc -s --gladtex myfile.txt -o myfile.htex
2550 pandoc -s --gladtex myfile.txt -o myfile.htex
@@ -2458,6 +2562,8 @@ HTML, Slidy, DZSlides, S5, EPUB
2458 math) and put in `<span>` tags with class `math`.
2562 math) and put in `<span>` tags with class `math`.
2459 The [MathJax] script will be used to render it as formulas.
2563 The [MathJax] script will be used to render it as formulas.
2460
2564
2565+[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math
2566+
2461Raw HTML
2567Raw HTML
2462--------
2568--------
2463
2569
@@ -2473,7 +2579,7 @@ The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
2473DZSlides, EPUB, Markdown, and Textile output, and suppressed in other
2579DZSlides, EPUB, Markdown, and Textile output, and suppressed in other
2474formats.
2580formats.
2475
2581
2476−#### Extension: `markdown_in_html_blocks` ####
2582+#### Extension: `markdown_in_html_blocks`
2477
2583
2478Standard markdown allows you to include HTML "blocks": blocks
2584Standard markdown allows you to include HTML "blocks": blocks
2479of HTML between balanced tags that are separated from the surrounding text
2585of HTML between balanced tags that are separated from the surrounding text
@@ -2665,8 +2771,7 @@ be omitted entirely:
2665### Internal links ###
2771### Internal links ###
2666
2772
2667To link to another section of the same document, use the automatically
2773To link to another section of the same document, use the automatically
2668−generated identifier (see [Header identifiers](#header-identifiers),
2774+generated identifier (see [Header identifiers]). For example:
2669−below). For example:
2670
2775
2671 See the [Introduction](#introduction).
2776 See the [Introduction](#introduction).
2672
2777
@@ -2789,15 +2894,14 @@ The bibliography may have any of these formats:
2789 MODS .mods
2894 MODS .mods
2790 RIS .ris
2895 RIS .ris
2791
2896
2792−Note that `.bib` can generally be used with both BibTeX and BibLaTeX
2897+Note that `.bib` can be used with both BibTeX and BibLaTeX files;
2793−files, but you can use `.bibtex` to force BibTeX.
2898+use `.bibtex` to force BibTeX.
2794
2899
2795Note that `pandoc-citeproc --bib2json` and `pandoc-citeproc --bib2yaml`
2900Note that `pandoc-citeproc --bib2json` and `pandoc-citeproc --bib2yaml`
2796can produce `.json` and `.yaml` files from any of the supported formats.
2901can produce `.json` and `.yaml` files from any of the supported formats.
2797
2902
2798−In-field markup: In bibtex and biblatex databases, pandoc-citeproc parses
2903+In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc parses
2799−(a subset of) LaTeX markup; in CSL JSON databases, an HTML-like markup
2904+a subset of LaTeX markup; in CSL JSON databases, an [HTML-like markup][CSL markup specs];
2800−([specs](http://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields));
2801and in CSL YAML databases, pandoc markdown. `pandoc-citeproc -j` and `-y`
2905and in CSL YAML databases, pandoc markdown. `pandoc-citeproc -j` and `-y`
2802interconvert these markup formats as far as possible.
2906interconvert these markup formats as far as possible.
2803
2907
@@ -2835,13 +2939,11 @@ YAML-encoded references, for example:
2835(`pandoc-citeproc --bib2yaml` can produce these from a bibliography file in one
2939(`pandoc-citeproc --bib2yaml` can produce these from a bibliography file in one
2836of the supported formats.)
2940of the supported formats.)
2837
2941
2942+Citations and references can be formatted using any style supported by the
2943+[Citation Style Language], listed in the [Zotero Style Repository].
2944+These files are specified using the `--csl` option or the `csl` metadata field.
2838−By default, `pandoc-citeproc` will use the Chicago Manual of Style author-date
2945+By default, `pandoc-citeproc` will use the [Chicago Manual of Style] author-date
2839−format for citations and references. To use another style, you will need to
2946+format. The CSL project provides further information on [finding and editing styles].
2840−specify a [CSL] 1.0 style file in the `csl` metadata field. A repository of CSL
2841−styles can be found at <https://github.com/citation-style-language/styles>. See
2842−also <http://zotero.org/styles> for easy browsing. A primer on creating and
2843−modifying CSL styles can be found at
2844−<http://citationstyles.org/downloads/primer.html>.
2845
2947
2846Citations go inside square brackets and are separated by semicolons.
2948Citations go inside square brackets and are separated by semicolons.
2847Each citation must have a key, composed of '@' + the citation
2949Each citation must have a key, composed of '@' + the citation
@@ -2856,17 +2958,15 @@ characters (`:.#$%&-+?<>~/`). Here are some examples:
2856
2958
2857 Blah blah [@smith04; @doe99].
2959 Blah blah [@smith04; @doe99].
2858
2960
2859−`pandoc-citeproc` detects locator terms based on the [CSL locale files].
2961+`pandoc-citeproc` detects locator terms in the [CSL locale files].
2860Either abbreviated or unabbreviated forms are accepted. In the `en-US` locale,
2962Either abbreviated or unabbreviated forms are accepted. In the `en-US` locale,
2861locator terms include `book`, `bk.`; `chapter`, `chap.`; `column`, `col.`;
2963locator terms include `book`, `bk.`; `chapter`, `chap.`; `column`, `col.`;
2862−`figure`, `fig.`; `folio`, `f.`; `number`, `no.`; `line`, `l.`; `note`, `n.`;
2964+`figure`, `fig.`; `folio`, `fol.`; `number`, `no.`; `line`, `l.`; `note`, `n.`;
2863`opus`, `op.`; `page`, `p.`; `paragraph`, `para.`; `part`, `pt.`;
2965`opus`, `op.`; `page`, `p.`; `paragraph`, `para.`; `part`, `pt.`;
2864`section`, `sec.`; `sub verbo`, `s.v.`; `verse`, `v.`; `volume`, `vol.`
2966`section`, `sec.`; `sub verbo`, `s.v.`; `verse`, `v.`; `volume`, `vol.`
2865as well as the plural forms of all these. If no locator term is used,
2967as well as the plural forms of all these. If no locator term is used,
2866"page" is assumed.
2968"page" is assumed.
2867
2969
2868− [CSL locale files]: https://github.com/citation-style-language/locales
2869−
2870A minus sign (`-`) before the `@` will suppress mention of
2970A minus sign (`-`) before the `@` will suppress mention of
2871the author in the citation. This can be useful when the
2971the author in the citation. This can be useful when the
2872author is already mentioned in the text:
2972author is already mentioned in the text:
@@ -2906,12 +3006,19 @@ In this example, the document will contain a citation for `item3`
2906only, but the bibliography will contain entries for `item1`, `item2`, and
3006only, but the bibliography will contain entries for `item1`, `item2`, and
2907`item3`.
3007`item3`.
2908
3008
2909−For LaTeX or PDF output, you can also use NatBib or BibLaTeX
3009+For LaTeX or PDF output, you can also use [`natbib`] or [`biblatex`]
2910to render bibliography. In order to do so, specify bibliography files as
3010to render bibliography. In order to do so, specify bibliography files as
2911outlined above, and add `--natbib` or `--biblatex` argument to `pandoc`
3011outlined above, and add `--natbib` or `--biblatex` argument to `pandoc`
2912invocation. Bear in mind that bibliography files have to be in respective
3012invocation. Bear in mind that bibliography files have to be in respective
2913format (either BibTeX or BibLaTeX).
3013format (either BibTeX or BibLaTeX).
2914
3014
3015+[CSL markup specs]: http://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields
3016+[Chicago Manual of Style]: http://chicagomanualofstyle.org
3017+[Citation Style Language]: http://citationstyles.org
3018+[Zotero Style Repository]: https://www.zotero.org/styles
3019+[finding and editing styles]: http://citationstyles.org/styles/
3020+[CSL locale files]: https://github.com/citation-style-language/locales
3021+
2915Non-pandoc extensions
3022Non-pandoc extensions
2916---------------------
3023---------------------
2917
3024
@@ -2971,13 +3078,13 @@ See the MultiMarkdown documentation for details. If `pandoc_title_block` or
2971`yaml_metadata_block` is enabled, it will take precedence over
3078`yaml_metadata_block` is enabled, it will take precedence over
2972`mmd_title_block`.
3079`mmd_title_block`.
2973
3080
2974− [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
3081+[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
2975
3082
2976#### Extension: `abbreviations` ####
3083#### Extension: `abbreviations` ####
2977
3084
2978Parses PHP Markdown Extra abbreviation keys, like
3085Parses PHP Markdown Extra abbreviation keys, like
2979
3086
2980− *[HTML]: Hyper Text Markup Language
3087+ *[HTML]: Hypertext Markup Language
2981
3088
2982Note that the pandoc document model does not support
3089Note that the pandoc document model does not support
2983abbreviations, so if this extension is enabled, abbreviation keys are
3090abbreviations, so if this extension is enabled, abbreviation keys are
@@ -3008,7 +3115,7 @@ after the header but before any trailing `#`s in an ATX header).
3008#### Extension: `compact_definition_lists` ####
3115#### Extension: `compact_definition_lists` ####
3009
3116
3010Activates the definition list syntax of pandoc 1.12.x and earlier.
3117Activates the definition list syntax of pandoc 1.12.x and earlier.
3011−This syntax differs from the one described [above](#definition-lists)
3118+This syntax differs from the one described above under [Definition lists]
3012in several respects:
3119in several respects:
3013
3120
3014 - No blank line is required between consecutive items of the
3121 - No blank line is required between consecutive items of the
@@ -3043,7 +3150,7 @@ variants are supported:
3043 `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,
3150 `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,
3044 `header_attributes`, `abbreviations`, `shortcut_reference_links`.
3151 `header_attributes`, `abbreviations`, `shortcut_reference_links`.
3045
3152
3046−`markdown_github` (GitHub-flavored Markdown)
3153+`markdown_github` (GitHub-Flavored Markdown)
3047: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,
3154: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,
3048 `fenced_code_blocks`, `auto_identifiers`,
3155 `fenced_code_blocks`, `auto_identifiers`,
3049 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,
3156 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,
@@ -3081,7 +3188,7 @@ Producing slide shows with Pandoc
3081You can use Pandoc to produce an HTML + javascript slide presentation
3188You can use Pandoc to produce an HTML + javascript slide presentation
3082that can be viewed via a web browser. There are five ways to do this,
3189that can be viewed via a web browser. There are five ways to do this,
3083using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js].
3190using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js].
3084−You can also produce a PDF slide show using LaTeX [beamer].
3191+You can also produce a PDF slide show using LaTeX [`beamer`].
3085
3192
3086Here's the markdown source for a simple slide show, `habits.txt`:
3193Here's the markdown source for a simple slide show, `habits.txt`:
3087
3194
@@ -3239,7 +3346,7 @@ using the `-V` option:
3239
3346
3240Note that header attributes will turn into slide attributes
3347Note that header attributes will turn into slide attributes
3241(on a `<div>` or `<section>`) in HTML slide formats, allowing you
3348(on a `<div>` or `<section>`) in HTML slide formats, allowing you
3242−to style individual slides. In Beamer, the only header attribute
3349+to style individual slides. In beamer, the only header attribute
3243that affects slides is the `allowframebreaks` class, which sets the
3350that affects slides is the `allowframebreaks` class, which sets the
3244`allowframebreaks` option, causing multiple slides to be created
3351`allowframebreaks` option, causing multiple slides to be created
3245if the content overfills the frame. This is recommended especially for
3352if the content overfills the frame. This is recommended especially for
@@ -3279,8 +3386,8 @@ EPUB Metadata
3279=============
3386=============
3280
3387
3281EPUB metadata may be specified using the `--epub-metadata` option, but
3388EPUB metadata may be specified using the `--epub-metadata` option, but
3282−if the source document is markdown, it is better to use a YAML metadata
3389+if the source document is markdown, it is better to use a [YAML metadata
3283−block. Here is an example:
3390+block][Extension: `yaml_metadata_block`]. Here is an example:
3284
3391
3285 ---
3392 ---
3286 title:
3393 title:
@@ -3317,7 +3424,7 @@ The following fields are recognized:
3317`creator`
3424`creator`
3318 ~ Either a string value, or an object with fields `role`, `file-as`,
3425 ~ Either a string value, or an object with fields `role`, `file-as`,
3319 and `text`, or a list of such objects. Valid values for `role` are
3426 and `text`, or a list of such objects. Valid values for `role` are
3320− [marc relators](http://www.loc.gov/marc/relators/relaterm.html), but
3427+ [MARC relators], but
3321 pandoc will attempt to translate the human-readable versions
3428 pandoc will attempt to translate the human-readable versions
3322 (like "author" and "editor") to the appropriate marc relators.
3429 (like "author" and "editor") to the appropriate marc relators.
3323
3430
@@ -3361,7 +3468,10 @@ The following fields are recognized:
3361
3468
3362`page-progression-direction`
3469`page-progression-direction`
3363 ~ Either `ltr` or `rtl`. Specifies the `page-progression-direction`
3470 ~ Either `ltr` or `rtl`. Specifies the `page-progression-direction`
3364− spine [attribute][EPUBspine].
3471+ attribute for the [`spine` element].
3472+
3473+[MARC relators]: http://loc.gov/marc/relators/relaterm.html
3474+[`spine` element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
3365
3475
3366Literate Haskell support
3476Literate Haskell support
3367========================
3477========================
@@ -3374,13 +3484,13 @@ literate Haskell source. This means that
3374 - In markdown input, "bird track" sections will be parsed as Haskell
3484 - In markdown input, "bird track" sections will be parsed as Haskell
3375 code rather than block quotations. Text between `\begin{code}`
3485 code rather than block quotations. Text between `\begin{code}`
3376 and `\end{code}` will also be treated as Haskell code. For
3486 and `\end{code}` will also be treated as Haskell code. For
3377− atx-style headers the character '=' will be used instead of '#'.
3487+ ATX-style headers the character '=' will be used instead of '#'.
3378
3488
3379 - In markdown output, code blocks with classes `haskell` and `literate`
3489 - In markdown output, code blocks with classes `haskell` and `literate`
3380 will be rendered using bird tracks, and block quotations will be
3490 will be rendered using bird tracks, and block quotations will be
3381 indented one space, so they will not be treated as Haskell code.
3491 indented one space, so they will not be treated as Haskell code.
3382 In addition, headers will be rendered setext-style (with underlines)
3492 In addition, headers will be rendered setext-style (with underlines)
3383− rather than atx-style (with '#' characters). (This is because ghc
3493+ rather than ATX-style (with '#' characters). (This is because ghc
3384 treats '#' characters in column 1 as introducing line numbers.)
3494 treats '#' characters in column 1 as introducing line numbers.)
3385
3495
3386 - In restructured text input, "bird track" sections will be parsed
3496 - In restructured text input, "bird track" sections will be parsed
@@ -3413,10 +3523,8 @@ and pasted as literate Haskell source.
3413Syntax highlighting
3523Syntax highlighting
3414===================
3524===================
3415
3525
3416−Pandoc will automatically highlight syntax in fenced code blocks that
3526+Pandoc will automatically highlight syntax in [fenced code blocks] that
3417−are marked with a language name. (See [Extension:
3418−`inline_code_attributes`] and [Extension: `fenced_code_attributes`],
3419−above.) The Haskell library [highlighting-kate] is used for
3527+are marked with a language name. The Haskell library [highlighting-kate] is used for
3420highlighting, which works in HTML, Docx, and LaTeX/PDF output.
3528highlighting, which works in HTML, Docx, and LaTeX/PDF output.
3421The color scheme can be selected using the `--highlight-style` option.
3529The color scheme can be selected using the `--highlight-style` option.
3422The default color scheme is `pygments`, which imitates the default color
3530The default color scheme is `pygments`, which imitates the default color
@@ -3428,6 +3536,8 @@ To see a list of language names that pandoc will recognize, type
3428
3536
3429To disable highlighting, use the `--no-highlight` option.
3537To disable highlighting, use the `--no-highlight` option.
3430
3538
3539+[highlighting-kate]: https://github.com/jgm/highlighting-kate
3540+
3431Custom writers
3541Custom writers
3432==============
3542==============
3433
3543
@@ -3445,6 +3555,8 @@ which you can modify according to your needs, do
3445
3555
3446 pandoc --print-default-data-file sample.lua
3556 pandoc --print-default-data-file sample.lua
3447
3557
3558+[lua]: http://www.lua.org
3559+
3448Authors
3560Authors
3449=======
3561=======
3450
3562
@@ -3578,46 +3690,4 @@ Vincent,
3578Wikiwide, and
3690Wikiwide, and
3579Xavier Olive.
3691Xavier Olive.
3580
3692
3581−[markdown]: http://daringfireball.net/projects/markdown/
3582−[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
3583−[S5]: http://meyerweb.com/eric/tools/s5/
3584−[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
3585−[Slideous]: http://goessner.net/articles/slideous/
3586−[HTML]: http://www.w3.org/TR/html40/
3587−[HTML 5]: http://www.w3.org/TR/html5/
3588−[XHTML]: http://www.w3.org/TR/xhtml1/
3589−[LaTeX]: http://www.latex-project.org/
3590−[beamer]: https://ctan.org/pkg/beamer
3591−[ConTeXt]: http://www.pragma-ade.nl/
3592−[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
3593−[DocBook]: http://www.docbook.org/
3594−[OPML]: http://dev.opml.org/spec2.html
3595−[OpenDocument]: http://opendocument.xml.org/
3596−[ODT]: http://en.wikipedia.org/wiki/OpenDocument
3597−[Textile]: http://redcloth.org/textile
3598−[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting
3599−[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
3600−[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
3601−[Haddock markup]: http://www.haskell.org/haddock/doc/html/ch03s08.html
3602−[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
3603−[Haskell]: http://www.haskell.org/
3604−[GNU Texinfo]: http://www.gnu.org/software/texinfo/
3605−[Emacs Org-Mode]: http://orgmode.org
3606−[AsciiDoc]: http://www.methods.co.nz/asciidoc/
3607[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
3693[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
3608−[DZSlides]: http://paulrouget.com/dzslides/
3609−[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime
3610−[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx
3611−[PDF]: http://www.adobe.com/pdf/
3612−[reveal.js]: http://lab.hakim.se/reveal-js/
3613−[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
3614−[lua]: http://www.lua.org
3615−[marc relators]: http://www.loc.gov/marc/relators/relaterm.html
3616−[BCP 47]: https://tools.ietf.org/html/bcp47
3617−[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
3618−[txt2tags]: http://txt2tags.org/
3619−[EPUB]: http://idpf.org/epub
3620−[EPUBspine]: http://www.idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
3621−[KaTeX]: https://github.com/Khan/KaTeX
3622−[CommonMark]: http://commonmark.org
3623−[highlighting-kate]: http://github.com/jgm/highlighting-kate