man/pandoc.1 · typeable/pandoc

git.iko.soy/typeable/pandoc

on master help sign in

typeable/pandoc/man/pandoc.1

7723 lines 236 kB history raw

1'\" t

2.\" Automatically generated by Pandoc 2.14.0.1

3.\"

4.TH "Pandoc User\[cq]s Guide" "" "June 20, 2021" "pandoc 2.14.0.3" ""

5.hy

6.SH NAME

7pandoc - general markup converter

8.SH SYNOPSIS

9.PP

10\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]\&...

11.SH DESCRIPTION

12.PP

13Pandoc is a Haskell library for converting from one markup format to

14another, and a command-line tool that uses this library.

15.PP

16Pandoc can convert between numerous markup and word processing formats,

17including, but not limited to, various flavors of Markdown, HTML, LaTeX

18and Word docx.

19For the full lists of input and output formats, see the \f[C]--from\f[R]

20and \f[C]--to\f[R] options below.

21Pandoc can also produce PDF output: see creating a PDF, below.

22.PP

23Pandoc\[cq]s enhanced version of Markdown includes syntax for tables,

24definition lists, metadata blocks, footnotes, citations, math, and much

25more.

26See below under Pandoc\[cq]s Markdown.

27.PP

28Pandoc has a modular design: it consists of a set of readers, which

29parse text in a given format and produce a native representation of the

30document (an \f[I]abstract syntax tree\f[R] or AST), and a set of

31writers, which convert this native representation into a target format.

32Thus, adding an input or output format requires only adding a reader or

33writer.

34Users can also run custom pandoc filters to modify the intermediate AST.

35.PP

36Because pandoc\[cq]s intermediate representation of a document is less

37expressive than many of the formats it converts between, one should not

38expect perfect conversions between every format and every other.

39Pandoc attempts to preserve the structural elements of a document, but

40not formatting details such as margin size.

41And some document elements, such as complex tables, may not fit into

42pandoc\[cq]s simple document model.

43While conversions from pandoc\[cq]s Markdown to all formats aspire to be

44perfect, conversions from formats more expressive than pandoc\[cq]s

45Markdown can be expected to be lossy.

46.SS Using pandoc

47.PP

48If no \f[I]input-files\f[R] are specified, input is read from

49\f[I]stdin\f[R].

50Output goes to \f[I]stdout\f[R] by default.

51For output to a file, use the \f[C]-o\f[R] option:

52.IP

53.nf

54\f[C]

55pandoc -o output.html input.txt

56\f[R]

57.fi

58.PP

59By default, pandoc produces a document fragment.

60To produce a standalone document (e.g.\ a valid HTML file including

61\f[C]<head>\f[R] and \f[C]<body>\f[R]), use the \f[C]-s\f[R] or

62\f[C]--standalone\f[R] flag:

63.IP

64.nf

65\f[C]

66pandoc -s -o output.html input.txt

67\f[R]

68.fi

69.PP

70For more information on how standalone documents are produced, see

71Templates below.

72.PP

73If multiple input files are given, \f[C]pandoc\f[R] will concatenate

74them all (with blank lines between them) before parsing.

75(Use \f[C]--file-scope\f[R] to parse files individually.)

76.SS Specifying formats

77.PP

78The format of the input and output can be specified explicitly using

79command-line options.

80The input format can be specified using the \f[C]-f/--from\f[R] option,

81the output format using the \f[C]-t/--to\f[R] option.

82Thus, to convert \f[C]hello.txt\f[R] from Markdown to LaTeX, you could

83type:

84.IP

85.nf

86\f[C]

87pandoc -f markdown -t latex hello.txt

88\f[R]

89.fi

90.PP

91To convert \f[C]hello.html\f[R] from HTML to Markdown:

92.IP

93.nf

94\f[C]

95pandoc -f html -t markdown hello.html

96\f[R]

97.fi

98.PP

99Supported input and output formats are listed below under Options (see

100\f[C]-f\f[R] for input formats and \f[C]-t\f[R] for output formats).

101You can also use \f[C]pandoc --list-input-formats\f[R] and

102\f[C]pandoc --list-output-formats\f[R] to print lists of supported

103formats.

104.PP

105If the input or output format is not specified explicitly,

106\f[C]pandoc\f[R] will attempt to guess it from the extensions of the

107filenames.

108Thus, for example,

109.IP

110.nf

111\f[C]

112pandoc -o hello.tex hello.txt

113\f[R]

114.fi

115.PP

116will convert \f[C]hello.txt\f[R] from Markdown to LaTeX.

117If no output file is specified (so that output goes to

118\f[I]stdout\f[R]), or if the output file\[cq]s extension is unknown, the

119output format will default to HTML.

120If no input file is specified (so that input comes from

121\f[I]stdin\f[R]), or if the input files\[cq] extensions are unknown, the

122input format will be assumed to be Markdown.

123.SS Character encoding

124.PP

125Pandoc uses the UTF-8 character encoding for both input and output.

126If your local character encoding is not UTF-8, you should pipe input and

127output through \f[C]iconv\f[R]:

128.IP

129.nf

130\f[C]

131iconv -t utf-8 input.txt | pandoc | iconv -f utf-8

132\f[R]

133.fi

134.PP

135Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,

136OPML, DocBook, and Texinfo), information about the character encoding is

137included in the document header, which will only be included if you use

138the \f[C]-s/--standalone\f[R] option.

139.SS Creating a PDF

140.PP

141To produce a PDF, specify an output file with a \f[C].pdf\f[R]

142extension:

143.IP

144.nf

145\f[C]

146pandoc test.txt -o test.pdf

147\f[R]

148.fi

149.PP

150By default, pandoc will use LaTeX to create the PDF, which requires that

151a LaTeX engine be installed (see \f[C]--pdf-engine\f[R] below).

152Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an

153intermediate format.

154To do this, specify an output file with a \f[C].pdf\f[R] extension, as

155before, but add the \f[C]--pdf-engine\f[R] option or

156\f[C]-t context\f[R], \f[C]-t html\f[R], or \f[C]-t ms\f[R] to the

157command line.

158The tool used to generate the PDF from the intermediate format may be

159specified using \f[C]--pdf-engine\f[R].

160.PP

161You can control the PDF style using variables, depending on the

162intermediate format used: see variables for LaTeX, variables for

163ConTeXt, variables for \f[C]wkhtmltopdf\f[R], variables for ms.

164When HTML is used as an intermediate format, the output can be styled

165using \f[C]--css\f[R].

166.PP

167To debug the PDF creation, it can be useful to look at the intermediate

168representation: instead of \f[C]-o test.pdf\f[R], use for example

169\f[C]-s -o test.tex\f[R] to output the generated LaTeX.

170You can then test it with \f[C]pdflatex test.tex\f[R].

171.PP

172When using LaTeX, the following packages need to be available (they are

173included with all recent versions of TeX Live): \f[C]amsfonts\f[R],

174\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],

175\f[C]iftex\f[R], \f[C]listings\f[R] (if the \f[C]--listings\f[R] option

176is used), \f[C]fancyvrb\f[R], \f[C]longtable\f[R], \f[C]booktabs\f[R],

177\f[C]graphicx\f[R] (if the document contains images),

178\f[C]hyperref\f[R], \f[C]xcolor\f[R], \f[C]ulem\f[R], \f[C]geometry\f[R]

179(with the \f[C]geometry\f[R] variable set), \f[C]setspace\f[R] (with

180\f[C]linestretch\f[R]), and \f[C]babel\f[R] (with \f[C]lang\f[R]).

181The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine

182requires \f[C]fontspec\f[R].

183\f[C]lualatex\f[R] uses \f[C]selnolig\f[R].

184\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),

185\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable

186set).

187If the \f[C]mathspec\f[R] variable is set, \f[C]xelatex\f[R] will use

188\f[C]mathspec\f[R] instead of \f[C]unicode-math\f[R].

189The \f[C]upquote\f[R] and \f[C]microtype\f[R] packages are used if

190available, and \f[C]csquotes\f[R] will be used for typography if the

191\f[C]csquotes\f[R] variable or metadata field is set to a true value.

192The \f[C]natbib\f[R], \f[C]biblatex\f[R], \f[C]bibtex\f[R], and

193\f[C]biber\f[R] packages can optionally be used for citation rendering.

194The following packages will be used to improve output quality if

195present, but pandoc does not require them to be present:

196\f[C]upquote\f[R] (for straight quotes in verbatim environments),

197\f[C]microtype\f[R] (for better spacing adjustments), \f[C]parskip\f[R]

198(for better inter-paragraph spaces), \f[C]xurl\f[R] (for better line

199breaks in URLs), \f[C]bookmark\f[R] (for better PDF bookmarks), and

200\f[C]footnotehyper\f[R] or \f[C]footnote\f[R] (to allow footnotes in

201tables).

202.SS Reading from the Web

203.PP

204Instead of an input file, an absolute URI may be given.

205In this case pandoc will fetch the content using HTTP:

206.IP

207.nf

208\f[C]

209pandoc -f html -t markdown https://www.fsf.org

210\f[R]

211.fi

212.PP

213It is possible to supply a custom User-Agent string or other header when

214requesting a document from a URL:

215.IP

216.nf

217\f[C]

218pandoc -f html -t markdown --request-header User-Agent:\[dq]Mozilla/5.0\[dq] \[rs]

219 https://www.fsf.org

220\f[R]

221.fi

222.SH OPTIONS

223.SS General options

224.TP

225\f[B]\f[CB]-f\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]-r\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--from=\f[B]\f[R]\f[I]FORMAT\f[R], \f[B]\f[CB]--read=\f[B]\f[R]\f[I]FORMAT\f[R]

226Specify input format.

227\f[I]FORMAT\f[R] can be:

228.RS

229.IP \[bu] 2

230\f[C]bibtex\f[R] (BibTeX bibliography)

231.IP \[bu] 2

232\f[C]biblatex\f[R] (BibLaTeX bibliography)

233.IP \[bu] 2

234\f[C]commonmark\f[R] (CommonMark Markdown)

235.IP \[bu] 2

236\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)

237.IP \[bu] 2

238\f[C]creole\f[R] (Creole 1.0)

239.IP \[bu] 2

240\f[C]csljson\f[R] (CSL JSON bibliography)

241.IP \[bu] 2

242\f[C]csv\f[R] (CSV table)

243.IP \[bu] 2

244\f[C]docbook\f[R] (DocBook)

245.IP \[bu] 2

246\f[C]docx\f[R] (Word docx)

247.IP \[bu] 2

248\f[C]dokuwiki\f[R] (DokuWiki markup)

249.IP \[bu] 2

250\f[C]epub\f[R] (EPUB)

251.IP \[bu] 2

252\f[C]fb2\f[R] (FictionBook2 e-book)

253.IP \[bu] 2

254\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less

255accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only

256if you need extensions not supported in \f[C]gfm\f[R].

257.IP \[bu] 2

258\f[C]haddock\f[R] (Haddock markup)

259.IP \[bu] 2

260\f[C]html\f[R] (HTML)

261.IP \[bu] 2

262\f[C]ipynb\f[R] (Jupyter notebook)

263.IP \[bu] 2

264\f[C]jats\f[R] (JATS XML)

265.IP \[bu] 2

266\f[C]jira\f[R] (Jira/Confluence wiki markup)

267.IP \[bu] 2

268\f[C]json\f[R] (JSON version of native AST)

269.IP \[bu] 2

270\f[C]latex\f[R] (LaTeX)

271.IP \[bu] 2

272\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)

273.IP \[bu] 2

274\f[C]markdown_mmd\f[R] (MultiMarkdown)

275.IP \[bu] 2

276\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)

277.IP \[bu] 2

278\f[C]markdown_strict\f[R] (original unextended Markdown)

279.IP \[bu] 2

280\f[C]mediawiki\f[R] (MediaWiki markup)

281.IP \[bu] 2

282\f[C]man\f[R] (roff man)

283.IP \[bu] 2

284\f[C]muse\f[R] (Muse)

285.IP \[bu] 2

286\f[C]native\f[R] (native Haskell)

287.IP \[bu] 2

288\f[C]odt\f[R] (ODT)

289.IP \[bu] 2

290\f[C]opml\f[R] (OPML)

291.IP \[bu] 2

292\f[C]org\f[R] (Emacs Org mode)

293.IP \[bu] 2

294\f[C]rst\f[R] (reStructuredText)

295.IP \[bu] 2

296\f[C]t2t\f[R] (txt2tags)

297.IP \[bu] 2

298\f[C]textile\f[R] (Textile)

299.IP \[bu] 2

300\f[C]tikiwiki\f[R] (TikiWiki markup)

301.IP \[bu] 2

302\f[C]twiki\f[R] (TWiki markup)

303.IP \[bu] 2

304\f[C]vimwiki\f[R] (Vimwiki)

305.PP

306Extensions can be individually enabled or disabled by appending

307\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.

308See Extensions below, for a list of extensions and their names.

309See \f[C]--list-input-formats\f[R] and \f[C]--list-extensions\f[R],

310below.

311.RE

312.TP

313\f[B]\f[CB]-t\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]-w\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--to=\f[B]\f[R]\f[I]FORMAT\f[R], \f[B]\f[CB]--write=\f[B]\f[R]\f[I]FORMAT\f[R]

314Specify output format.

315\f[I]FORMAT\f[R] can be:

316.RS

317.IP \[bu] 2

318\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor)

319.IP \[bu] 2

320\f[C]beamer\f[R] (LaTeX beamer slide show)

321.IP \[bu] 2

322\f[C]bibtex\f[R] (BibTeX bibliography)

323.IP \[bu] 2

324\f[C]biblatex\f[R] (BibLaTeX bibliography)

325.IP \[bu] 2

326\f[C]commonmark\f[R] (CommonMark Markdown)

327.IP \[bu] 2

328\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)

329.IP \[bu] 2

330\f[C]context\f[R] (ConTeXt)

331.IP \[bu] 2

332\f[C]csljson\f[R] (CSL JSON bibliography)

333.IP \[bu] 2

334\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)

335.IP \[bu] 2

336\f[C]docbook5\f[R] (DocBook 5)

337.IP \[bu] 2

338\f[C]docx\f[R] (Word docx)

339.IP \[bu] 2

340\f[C]dokuwiki\f[R] (DokuWiki markup)

341.IP \[bu] 2

342\f[C]epub\f[R] or \f[C]epub3\f[R] (EPUB v3 book)

343.IP \[bu] 2

344\f[C]epub2\f[R] (EPUB v2)

345.IP \[bu] 2

346\f[C]fb2\f[R] (FictionBook2 e-book)

347.IP \[bu] 2

348\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less

349accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only

350if you need extensions not supported in \f[C]gfm\f[R].

351.IP \[bu] 2

352\f[C]haddock\f[R] (Haddock markup)

353.IP \[bu] 2

354\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot

355markup)

356.IP \[bu] 2

357\f[C]html4\f[R] (XHTML 1.0 Transitional)

358.IP \[bu] 2

359\f[C]icml\f[R] (InDesign ICML)

360.IP \[bu] 2

361\f[C]ipynb\f[R] (Jupyter notebook)

362.IP \[bu] 2

363\f[C]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set)

364.IP \[bu] 2

365\f[C]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set)

366.IP \[bu] 2

367\f[C]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set)

368.IP \[bu] 2

369\f[C]jats\f[R] (alias for \f[C]jats_archiving\f[R])

370.IP \[bu] 2

371\f[C]jira\f[R] (Jira/Confluence wiki markup)

372.IP \[bu] 2

373\f[C]json\f[R] (JSON version of native AST)

374.IP \[bu] 2

375\f[C]latex\f[R] (LaTeX)

376.IP \[bu] 2

377\f[C]man\f[R] (roff man)

378.IP \[bu] 2

379\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)

380.IP \[bu] 2

381\f[C]markdown_mmd\f[R] (MultiMarkdown)

382.IP \[bu] 2

383\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)

384.IP \[bu] 2

385\f[C]markdown_strict\f[R] (original unextended Markdown)

386.IP \[bu] 2

387\f[C]mediawiki\f[R] (MediaWiki markup)

388.IP \[bu] 2

389\f[C]ms\f[R] (roff ms)

390.IP \[bu] 2

391\f[C]muse\f[R] (Muse),

392.IP \[bu] 2

393\f[C]native\f[R] (native Haskell),

394.IP \[bu] 2

395\f[C]odt\f[R] (OpenOffice text document)

396.IP \[bu] 2

397\f[C]opml\f[R] (OPML)

398.IP \[bu] 2

399\f[C]opendocument\f[R] (OpenDocument)

400.IP \[bu] 2

401\f[C]org\f[R] (Emacs Org mode)

402.IP \[bu] 2

403\f[C]pdf\f[R] (PDF)

404.IP \[bu] 2

405\f[C]plain\f[R] (plain text),

406.IP \[bu] 2

407\f[C]pptx\f[R] (PowerPoint slide show)

408.IP \[bu] 2

409\f[C]rst\f[R] (reStructuredText)

410.IP \[bu] 2

411\f[C]rtf\f[R] (Rich Text Format)

412.IP \[bu] 2

413\f[C]texinfo\f[R] (GNU Texinfo)

414.IP \[bu] 2

415\f[C]textile\f[R] (Textile)

416.IP \[bu] 2

417\f[C]slideous\f[R] (Slideous HTML and JavaScript slide show)

418.IP \[bu] 2

419\f[C]slidy\f[R] (Slidy HTML and JavaScript slide show)

420.IP \[bu] 2

421\f[C]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show),

422.IP \[bu] 2

423\f[C]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)

424.IP \[bu] 2

425\f[C]s5\f[R] (S5 HTML and JavaScript slide show)

426.IP \[bu] 2

427\f[C]tei\f[R] (TEI Simple)

428.IP \[bu] 2

429\f[C]xwiki\f[R] (XWiki markup)

430.IP \[bu] 2

431\f[C]zimwiki\f[R] (ZimWiki markup)

432.IP \[bu] 2

433the path of a custom Lua writer, see Custom writers below

434.PP

435Note that \f[C]odt\f[R], \f[C]docx\f[R], \f[C]epub\f[R], and

436\f[C]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless

437forced with \f[C]-o -\f[R].

438.PP

439Extensions can be individually enabled or disabled by appending

440\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.

441See Extensions below, for a list of extensions and their names.

442See \f[C]--list-output-formats\f[R] and \f[C]--list-extensions\f[R],

443below.

444.RE

445.TP

446\f[B]\f[CB]-o\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--output=\f[B]\f[R]\f[I]FILE\f[R]

447Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].

448If \f[I]FILE\f[R] is \f[C]-\f[R], output will go to \f[I]stdout\f[R],

449even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],

450\f[C]epub2\f[R], \f[C]epub3\f[R]) is specified.

451.TP

452\f[B]\f[CB]--data-dir=\f[B]\f[R]\f[I]DIRECTORY\f[R]

453Specify the user data directory to search for pandoc data files.

454If this option is not specified, the default user data directory will be

455used.

456On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory

457of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],

458overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment

459variable).

460If that directory does not exist and \f[C]$HOME/.pandoc\f[R] exists, it

461will be used (for backwards compatibility).

462On Windows the default user data directory is

463\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].

464You can find the default user data directory on your system by looking

465at the output of \f[C]pandoc --version\f[R].

466Data files placed in this directory (for example,

467\f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],

468\f[C]templates\f[R]) will override pandoc\[cq]s normal defaults.

469.TP

470\f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]

471Specify a set of default option settings.

472\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line

473option settings.

474All options for document conversion, including input and output files,

475can be set using a defaults file.

476The file will be searched for first in the working directory, and then

477in the \f[C]defaults\f[R] subdirectory of the user data directory (see

478\f[C]--data-dir\f[R]).

479The \f[C].yaml\f[R] extension may be omitted.

480See the section Default files for more information on the file format.

481Settings from the defaults file may be overridden or extended by

482subsequent options on the command line.

483.TP

484\f[B]\f[CB]--bash-completion\f[B]\f[R]

485Generate a bash completion script.

486To enable bash completion with pandoc, add this to your

487\f[C].bashrc\f[R]:

488.RS

489.IP

490.nf

491\f[C]

492eval \[dq]$(pandoc --bash-completion)\[dq]

493\f[R]

494.fi

495.RE

496.TP

497\f[B]\f[CB]--verbose\f[B]\f[R]

498Give verbose debugging output.

499.TP

500\f[B]\f[CB]--quiet\f[B]\f[R]

501Suppress warning messages.

502.TP

503\f[B]\f[CB]--fail-if-warnings\f[B]\f[R]

504Exit with error status if there are any warnings.

505.TP

506\f[B]\f[CB]--log=\f[B]\f[R]\f[I]FILE\f[R]

507Write log messages in machine-readable JSON format to \f[I]FILE\f[R].

508All messages above DEBUG level will be written, regardless of verbosity

509settings (\f[C]--verbose\f[R], \f[C]--quiet\f[R]).

510.TP

511\f[B]\f[CB]--list-input-formats\f[B]\f[R]

512List supported input formats, one per line.

513.TP

514\f[B]\f[CB]--list-output-formats\f[B]\f[R]

515List supported output formats, one per line.

516.TP

517\f[B]\f[CB]--list-extensions\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]FORMAT\f[R]]

518List supported extensions for \f[I]FORMAT\f[R], one per line, preceded

519by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by

520default in \f[I]FORMAT\f[R].

521If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown

522are given.

523.TP

524\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]

525List supported languages for syntax highlighting, one per line.

526.TP

527\f[B]\f[CB]--list-highlight-styles\f[B]\f[R]

528List supported styles for syntax highlighting, one per line.

529See \f[C]--highlight-style\f[R].

530.TP

531\f[B]\f[CB]-v\f[B]\f[R], \f[B]\f[CB]--version\f[B]\f[R]

532Print version.

533.TP

534\f[B]\f[CB]-h\f[B]\f[R], \f[B]\f[CB]--help\f[B]\f[R]

535Show usage message.

536.SS Reader options

537.TP

538\f[B]\f[CB]--shift-heading-level-by=\f[B]\f[R]\f[I]NUMBER\f[R]

539Shift heading levels by a positive or negative integer.

540For example, with \f[C]--shift-heading-level-by=-1\f[R], level 2

541headings become level 1 headings, and level 3 headings become level 2

542headings.

543Headings cannot have a level less than 1, so a heading that would be

544shifted below level 1 becomes a regular paragraph.

545Exception: with a shift of -N, a level-N heading at the beginning of the

546document replaces the metadata title.

547\f[C]--shift-heading-level-by=-1\f[R] is a good choice when converting

548HTML or Markdown documents that use an initial level-1 heading for the

549document title and level-2+ headings for sections.

550\f[C]--shift-heading-level-by=1\f[R] may be a good choice for converting

551Markdown documents that use level-1 headings for sections to HTML, since

552pandoc uses a level-1 heading to render the document title.

553.TP

554\f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R]

555\f[I]Deprecated. Use \f[CI]--shift-heading-level-by\f[I]=X instead,

556where X = NUMBER - 1.\f[R] Specify the base level for headings (defaults

557to 1).

558.TP

559\f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R]

560\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension

561instead.\f[R] Ignore paragraphs with no content.

562This option is useful for converting word processing documents where

563users have used empty paragraphs to create inter-paragraph space.

564.TP

565\f[B]\f[CB]--indented-code-classes=\f[B]\f[R]\f[I]CLASSES\f[R]

566Specify classes to use for indented code blocks\[en]for example,

567\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].

568Multiple classes may be separated by spaces or commas.

569.TP

570\f[B]\f[CB]--default-image-extension=\f[B]\f[R]\f[I]EXTENSION\f[R]

571Specify a default extension to use when image paths/URLs have no

572extension.

573This allows you to use the same source for formats that require

574different kinds of images.

575Currently this option only affects the Markdown and LaTeX readers.

576.TP

577\f[B]\f[CB]--file-scope\f[B]\f[R]

578Parse each file individually before combining for multifile documents.

579This will allow footnotes in different files with the same identifiers

580to work as expected.

581If this option is set, footnotes and links will not work across files.

582Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].

583.TP

584\f[B]\f[CB]-F\f[B]\f[R] \f[I]PROGRAM\f[R], \f[B]\f[CB]--filter=\f[B]\f[R]\f[I]PROGRAM\f[R]

585Specify an executable to be used as a filter transforming the pandoc AST

586after the input is parsed and before the output is written.

587The executable should read JSON from stdin and write JSON to stdout.

588The JSON must be formatted like pandoc\[cq]s own JSON input and output.

589The name of the output format will be passed to the filter as the first

590argument.

591Hence,

592.RS

593.IP

594.nf

595\f[C]

596pandoc --filter ./caps.py -t latex

597\f[R]

598.fi

599.PP

600is equivalent to

601.IP

602.nf

603\f[C]

604pandoc -t json | ./caps.py latex | pandoc -f json -t latex

605\f[R]

606.fi

607.PP

608The latter form may be useful for debugging filters.

609.PP

610Filters may be written in any language.

611\f[C]Text.Pandoc.JSON\f[R] exports \f[C]toJSONFilter\f[R] to facilitate

612writing filters in Haskell.

613Those who would prefer to write filters in python can use the module

614\f[C]pandocfilters\f[R], installable from PyPI.

615There are also pandoc filter libraries in PHP, perl, and

616JavaScript/node.js.

617.PP

618In order of preference, pandoc will look for filters in

619.IP "1." 3

620a specified full or relative path (executable or non-executable)

621.IP "2." 3

622\f[C]$DATADIR/filters\f[R] (executable or non-executable) where

623\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],

624above).

625.IP "3." 3

626\f[C]$PATH\f[R] (executable only)

627.PP

628Filters, Lua-filters, and citeproc processing are applied in the order

629specified on the command line.

630.RE

631.TP

632\f[B]\f[CB]-L\f[B]\f[R] \f[I]SCRIPT\f[R], \f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]

633Transform the document in a similar fashion as JSON filters (see

634\f[C]--filter\f[R]), but use pandoc\[cq]s built-in Lua filtering system.

635The given Lua script is expected to return a list of Lua filters which

636will be applied in order.

637Each Lua filter must contain element-transforming functions indexed by

638the name of the AST element on which the filter function should be

639applied.

640.RS

641.PP

642The \f[C]pandoc\f[R] Lua module provides helper functions for element

643creation.

644It is always loaded into the script\[cq]s Lua environment.

645.PP

646See the Lua filters documentation for further details.

647.PP

648In order of preference, pandoc will look for Lua filters in

649.IP "1." 3

650a specified full or relative path

651.IP "2." 3

652\f[C]$DATADIR/filters\f[R] where \f[C]$DATADIR\f[R] is the user data

653directory (see \f[C]--data-dir\f[R], above).

654.PP

655Filters, Lua filters, and citeproc processing are applied in the order

656specified on the command line.

657.RE

658.TP

659\f[B]\f[CB]-M\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--metadata=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]

660Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].

661A value specified on the command line overrides a value specified in the

662document using YAML metadata blocks.

663Values will be parsed as YAML boolean or string values.

664If no value is specified, the value will be treated as Boolean true.

665Like \f[C]--variable\f[R], \f[C]--metadata\f[R] causes template

666variables to be set.

667But unlike \f[C]--variable\f[R], \f[C]--metadata\f[R] affects the

668metadata of the underlying document (which is accessible from filters

669and may be printed in some output formats) and metadata values will be

670escaped when inserted into the template.

671.TP

672\f[B]\f[CB]--metadata-file=\f[B]\f[R]\f[I]FILE\f[R]

673Read metadata from the supplied YAML (or JSON) file.

674This option can be used with every input format, but string scalars in

675the YAML file will always be parsed as Markdown.

676Generally, the input will be handled the same as in YAML metadata

677blocks.

678This option can be used repeatedly to include multiple metadata files;

679values in files specified later on the command line will be preferred

680over those specified in earlier files.

681Metadata values specified inside the document, or by using \f[C]-M\f[R],

682overwrite values specified with this option.

683.TP

684\f[B]\f[CB]-p\f[B]\f[R], \f[B]\f[CB]--preserve-tabs\f[B]\f[R]

685Preserve tabs instead of converting them to spaces.

686(By default, pandoc converts tabs to spaces before parsing its input.)

687Note that this will only affect tabs in literal code spans and code

688blocks.

689Tabs in regular text are always treated as spaces.

690.TP

691\f[B]\f[CB]--tab-stop=\f[B]\f[R]\f[I]NUMBER\f[R]

692Specify the number of spaces per tab (default is 4).

693.TP

694\f[B]\f[CB]--track-changes=accept\f[B]\f[R]|\f[B]\f[CB]reject\f[B]\f[R]|\f[B]\f[CB]all\f[B]\f[R]

695Specifies what to do with insertions, deletions, and comments produced

696by the MS Word \[lq]Track Changes\[rq] feature.

697\f[C]accept\f[R] (the default) processes all the insertions and

698deletions.

699\f[C]reject\f[R] ignores them.

700Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.

701\f[C]all\f[R] includes all insertions, deletions, and comments, wrapped

702in spans with \f[C]insertion\f[R], \f[C]deletion\f[R],

703\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,

704respectively.

705The author and time of change is included.

706\f[C]all\f[R] is useful for scripting: only accepting changes from a

707certain reviewer, say, or before a certain date.

708If a paragraph is inserted or deleted, \f[C]track-changes=all\f[R]

709produces a span with the class

710\f[C]paragraph-insertion\f[R]/\f[C]paragraph-deletion\f[R] before the

711affected paragraph break.

712This option only affects the docx reader.

713.TP

714\f[B]\f[CB]--extract-media=\f[B]\f[R]\f[I]DIR\f[R]

715Extract images and other media contained in or linked from the source

716document to the path \f[I]DIR\f[R], creating it if necessary, and adjust

717the images references in the document so they point to the extracted

718files.

719Media are downloaded, read from the file system, or extracted from a

720binary container (e.g.\ docx), as needed.

721The original file paths are used if they are relative paths not

722containing \f[C]..\f[R].

723Otherwise filenames are constructed from the SHA1 hash of the contents.

724.TP

725\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]

726Specifies a custom abbreviations file, with abbreviations one to a line.

727If this option is not specified, pandoc will read the data file

728\f[C]abbreviations\f[R] from the user data directory or fall back on a

729system default.

730To see the system default, use

731\f[C]pandoc --print-default-data-file=abbreviations\f[R].

732The only use pandoc makes of this list is in the Markdown reader.

733Strings found in this list will be followed by a nonbreaking space, and

734the period will not produce sentence-ending space in formats like LaTeX.

735The strings may not contain spaces.

736.SS General writer options

737.TP

738\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]

739Produce output with an appropriate header and footer (e.g.\ a standalone

740HTML, LaTeX, TEI, or RTF file, not a fragment).

741This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],

742\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]

743output.

744For \f[C]native\f[R] output, this option causes metadata to be included;

745otherwise, metadata is suppressed.

746.TP

747\f[B]\f[CB]--template=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]

748Use the specified file as a custom template for the generated document.

749Implies \f[C]--standalone\f[R].

750See Templates, below, for a description of template syntax.

751If no extension is specified, an extension corresponding to the writer

752will be added, so that \f[C]--template=special\f[R] looks for

753\f[C]special.html\f[R] for HTML output.

754If the template is not found, pandoc will search for it in the

755\f[C]templates\f[R] subdirectory of the user data directory (see

756\f[C]--data-dir\f[R]).

757If this option is not used, a default template appropriate for the

758output format will be used (see \f[C]-D/--print-default-template\f[R]).

759.TP

760\f[B]\f[CB]-V\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--variable=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]

761Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when

762rendering the document in standalone mode.

763If no \f[I]VAL\f[R] is specified, the key will be given the value

764\f[C]true\f[R].

765.TP

766\f[B]\f[CB]-D\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--print-default-template=\f[B]\f[R]\f[I]FORMAT\f[R]

767Print the system default template for an output \f[I]FORMAT\f[R].

768(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates

769in the user data directory are ignored.

770This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect

771output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before

772\f[C]--print-default-template\f[R] on the command line.

773.RS

774.PP

775Note that some of the default templates use partials, for example

776\f[C]styles.html\f[R].

777To print the partials, use \f[C]--print-default-data-file\f[R]: for

778example, \f[C]--print-default-data-file=templates/styles.html\f[R].

779.RE

780.TP

781\f[B]\f[CB]--print-default-data-file=\f[B]\f[R]\f[I]FILE\f[R]

782Print a system default data file.

783Files in the user data directory are ignored.

784This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect

785output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before

786\f[C]--print-default-data-file\f[R] on the command line.

787.TP

788\f[B]\f[CB]--eol=crlf\f[B]\f[R]|\f[B]\f[CB]lf\f[B]\f[R]|\f[B]\f[CB]native\f[B]\f[R]

789Manually specify line endings: \f[C]crlf\f[R] (Windows), \f[C]lf\f[R]

790(macOS/Linux/UNIX), or \f[C]native\f[R] (line endings appropriate to the

791OS on which pandoc is being run).

792The default is \f[C]native\f[R].

793.TP

794\f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R]

795Specify the default dpi (dots per inch) value for conversion from pixels

796to inch/centimeters and vice versa.

797(Technically, the correct term would be ppi: pixels per inch.) The

798default is 96dpi.

799When images contain information about dpi internally, the encoded value

800is used instead of the default specified by this option.

801.TP

802\f[B]\f[CB]--wrap=auto\f[B]\f[R]|\f[B]\f[CB]none\f[B]\f[R]|\f[B]\f[CB]preserve\f[B]\f[R]

803Determine how text is wrapped in the output (the source code, not the

804rendered version).

805With \f[C]auto\f[R] (the default), pandoc will attempt to wrap lines to

806the column width specified by \f[C]--columns\f[R] (default 72).

807With \f[C]none\f[R], pandoc will not wrap lines at all.

808With \f[C]preserve\f[R], pandoc will attempt to preserve the wrapping

809from the source document (that is, where there are nonsemantic newlines

810in the source, there will be nonsemantic newlines in the output as

811well).

812Automatic wrapping does not currently work in HTML output.

813In \f[C]ipynb\f[R] output, this option affects wrapping of the contents

814of markdown cells.

815.TP

816\f[B]\f[CB]--columns=\f[B]\f[R]\f[I]NUMBER\f[R]

817Specify length of lines in characters.

818This affects text wrapping in the generated source code (see

819\f[C]--wrap\f[R]).

820It also affects calculation of column widths for plain text tables (see

821Tables below).

822.TP

823\f[B]\f[CB]--toc\f[B]\f[R], \f[B]\f[CB]--table-of-contents\f[B]\f[R]

824Include an automatically generated table of contents (or, in the case of

825\f[C]latex\f[R], \f[C]context\f[R], \f[C]docx\f[R], \f[C]odt\f[R],

826\f[C]opendocument\f[R], \f[C]rst\f[R], or \f[C]ms\f[R], an instruction

827to create one) in the output document.

828This option has no effect unless \f[C]-s/--standalone\f[R] is used, and

829it has no effect on \f[C]man\f[R], \f[C]docbook4\f[R],

830\f[C]docbook5\f[R], or \f[C]jats\f[R] output.

831.RS

832.PP

833Note that if you are producing a PDF via \f[C]ms\f[R], the table of

834contents will appear at the beginning of the document, before the title.

835If you would prefer it to be at the end of the document, use the option

836\f[C]--pdf-engine-opt=--no-toc-relocation\f[R].

837.RE

838.TP

839\f[B]\f[CB]--toc-depth=\f[B]\f[R]\f[I]NUMBER\f[R]

840Specify the number of section levels to include in the table of

841contents.

842The default is 3 (which means that level-1, 2, and 3 headings will be

843listed in the contents).

844.TP

845\f[B]\f[CB]--strip-comments\f[B]\f[R]

846Strip out HTML comments in the Markdown or Textile source, rather than

847passing them on to Markdown, Textile or HTML output as raw HTML.

848This does not apply to HTML comments inside raw HTML blocks when the

849\f[C]markdown_in_html_blocks\f[R] extension is not set.

850.TP

851\f[B]\f[CB]--no-highlight\f[B]\f[R]

852Disables syntax highlighting for code blocks and inlines, even when a

853language attribute is given.

854.TP

855\f[B]\f[CB]--highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]

856Specifies the coloring style to be used in highlighted source code.

857Options are \f[C]pygments\f[R] (the default), \f[C]kate\f[R],

858\f[C]monochrome\f[R], \f[C]breezeDark\f[R], \f[C]espresso\f[R],

859\f[C]zenburn\f[R], \f[C]haddock\f[R], and \f[C]tango\f[R].

860For more information on syntax highlighting in pandoc, see Syntax

861highlighting, below.

862See also \f[C]--list-highlight-styles\f[R].

863.RS

864.PP

865Instead of a \f[I]STYLE\f[R] name, a JSON file with extension

866\f[C].theme\f[R] may be supplied.

867This will be parsed as a KDE syntax highlighting theme and (if valid)

868used as the highlighting style.

869.PP

870To generate the JSON version of an existing style, use

871\f[C]--print-highlight-style\f[R].

872.RE

873.TP

874\f[B]\f[CB]--print-highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]

875Prints a JSON version of a highlighting style, which can be modified,

876saved with a \f[C].theme\f[R] extension, and used with

877\f[C]--highlight-style\f[R].

878This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect

879output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before

880\f[C]--print-highlight-style\f[R] on the command line.

881.TP

882\f[B]\f[CB]--syntax-definition=\f[B]\f[R]\f[I]FILE\f[R]

883Instructs pandoc to load a KDE XML syntax definition file, which will be

884used for syntax highlighting of appropriately marked code blocks.

885This can be used to add support for new languages or to use altered

886syntax definitions for existing languages.

887This option may be repeated to add multiple syntax definitions.

888.TP

889\f[B]\f[CB]-H\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-in-header=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]

890Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.

891This can be used, for example, to include special CSS or JavaScript in

892HTML documents.

893This option can be used repeatedly to include multiple files in the

894header.

895They will be included in the order specified.

896Implies \f[C]--standalone\f[R].

897.TP

898\f[B]\f[CB]-B\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-before-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]

899Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the

900document body (e.g.\ after the \f[C]<body>\f[R] tag in HTML, or the

901\f[C]\[rs]begin{document}\f[R] command in LaTeX).

902This can be used to include navigation bars or banners in HTML

903documents.

904This option can be used repeatedly to include multiple files.

905They will be included in the order specified.

906Implies \f[C]--standalone\f[R].

907.TP

908\f[B]\f[CB]-A\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-after-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]

909Include contents of \f[I]FILE\f[R], verbatim, at the end of the document

910body (before the \f[C]</body>\f[R] tag in HTML, or the

911\f[C]\[rs]end{document}\f[R] command in LaTeX).

912This option can be used repeatedly to include multiple files.

913They will be included in the order specified.

914Implies \f[C]--standalone\f[R].

915.TP

916\f[B]\f[CB]--resource-path=\f[B]\f[R]\f[I]SEARCHPATH\f[R]

917List of paths to search for images and other resources.

918The paths should be separated by \f[C]:\f[R] on Linux, UNIX, and macOS

919systems, and by \f[C];\f[R] on Windows.

920If \f[C]--resource-path\f[R] is not specified, the default resource path

921is the working directory.

922Note that, if \f[C]--resource-path\f[R] is specified, the working

923directory must be explicitly listed or it will not be searched.

924For example: \f[C]--resource-path=.:test\f[R] will search the working

925directory and the \f[C]test\f[R] subdirectory, in that order.

926This option can be used repeatedly.

927Search path components that come later on the command line will be

928searched before those that come earlier, so

929\f[C]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent

930to \f[C]--resource-path baz:bim:foo:bar\f[R].

931.TP

932\f[B]\f[CB]--request-header=\f[B]\f[R]\f[I]NAME\f[R]\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]

933Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when

934making HTTP requests (for example, when a URL is given on the command

935line, or when resources used in a document must be downloaded).

936If you\[cq]re behind a proxy, you also need to set the environment

937variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].

938.TP

939\f[B]\f[CB]--no-check-certificate\f[B]\f[R]

940Disable the certificate verification to allow access to unsecure HTTP

941resources (for example when the certificate is no longer valid or self

942signed).

943.SS Options affecting specific writers

944.TP

945\f[B]\f[CB]--self-contained\f[B]\f[R]

946Produce a standalone HTML file with no external dependencies, using

947\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,

948stylesheets, images, and videos.

949Implies \f[C]--standalone\f[R].

950The resulting file should be \[lq]self-contained,\[rq] in the sense that

951it needs no external files and no net access to be displayed properly by

952a browser.

953This option works only with HTML output formats, including

954\f[C]html4\f[R], \f[C]html5\f[R], \f[C]html+lhs\f[R],

955\f[C]html5+lhs\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],

956\f[C]dzslides\f[R], and \f[C]revealjs\f[R].

957Scripts, images, and stylesheets at absolute URLs will be downloaded;

958those at relative URLs will be sought relative to the working directory

959(if the first source file is local) or relative to the base URL (if the

960first source file is remote).

961Elements with the attribute \f[C]data-external=\[dq]1\[dq]\f[R] will be

962left alone; the documents they link to will not be incorporated in the

963document.

964Limitation: resources that are loaded dynamically through JavaScript

965cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not

966work with \f[C]--mathjax\f[R], and some advanced features (e.g.\ zoom or

967speaker notes) may not work in an offline \[lq]self-contained\[rq]

968\f[C]reveal.js\f[R] slide show.

969.TP

970\f[B]\f[CB]--html-q-tags\f[B]\f[R]

971Use \f[C]<q>\f[R] tags for quotes in HTML.

972(This option only has an effect if the \f[C]smart\f[R] extension is

973enabled for the input format used.)

974.TP

975\f[B]\f[CB]--ascii\f[B]\f[R]

976Use only ASCII characters in output.

977Currently supported for XML and HTML formats (which use entities instead

978of UTF-8 when this option is selected), CommonMark, gfm, and Markdown

979(which use entities), roff ms (which use hexadecimal escapes), and to a

980limited degree LaTeX (which uses standard commands for accented

981characters when possible).

982roff man output uses ASCII by default.

983.TP

984\f[B]\f[CB]--reference-links\f[B]\f[R]

985Use reference-style links, rather than inline links, in writing Markdown

986or reStructuredText.

987By default inline links are used.

988The placement of link references is affected by the

989\f[C]--reference-location\f[R] option.

990.TP

991\f[B]\f[CB]--reference-location=block\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]document\f[B]\f[R]

992Specify whether footnotes (and references, if \f[C]reference-links\f[R]

993is set) are placed at the end of the current (top-level) block, the

994current section, or the document.

995The default is \f[C]document\f[R].

996Currently only affects the markdown writer.

997.TP

998\f[B]\f[CB]--markdown-headings=setext\f[B]\f[R]|\f[B]\f[CB]atx\f[B]\f[R]

999Specify whether to use ATX-style (\f[C]#\f[R]-prefixed) or Setext-style

1000(underlined) headings for level 1 and 2 headings in Markdown output.

1001(The default is \f[C]atx\f[R].) ATX-style headings are always used for

1002levels 3+.

1003This option also affects Markdown cells in \f[C]ipynb\f[R] output.

1004.TP

1005\f[B]\f[CB]--atx-headers\f[B]\f[R]

1006\f[I]Deprecated synonym for \f[CI]--markdown-headings=atx\f[I].\f[R]

1007.TP

1008\f[B]\f[CB]--top-level-division=default\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]chapter\f[B]\f[R]|\f[B]\f[CB]part\f[B]\f[R]

1009Treat top-level headings as the given division type in LaTeX, ConTeXt,

1010DocBook, and TEI output.

1011The hierarchy order is part, chapter, then section; all headings are

1012shifted such that the top-level heading becomes the specified type.

1013The default behavior is to determine the best division type via

1014heuristics: unless other conditions apply, \f[C]section\f[R] is chosen.

1015When the \f[C]documentclass\f[R] variable is set to \f[C]report\f[R],

1016\f[C]book\f[R], or \f[C]memoir\f[R] (unless the \f[C]article\f[R] option

1017is specified), \f[C]chapter\f[R] is implied as the setting for this

1018option.

1019If \f[C]beamer\f[R] is the output format, specifying either

1020\f[C]chapter\f[R] or \f[C]part\f[R] will cause top-level headings to

1021become \f[C]\[rs]part{..}\f[R], while second-level headings remain as

1022their default type.

1023.TP

1024\f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]

1025Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB

1026output.

1027By default, sections are not numbered.

1028Sections with class \f[C]unnumbered\f[R] will never be numbered, even if

1029\f[C]--number-sections\f[R] is specified.

1030.TP

1031\f[B]\f[CB]--number-offset=\f[B]\f[R]\f[I]NUMBER\f[R][\f[B]\f[CB],\f[B]\f[R]\f[I]NUMBER\f[R]\f[B]\f[CB],\f[B]\f[R]\f[I]\&...\f[R]]

1032Offset for section headings in HTML output (ignored in other output

1033formats).

1034The first number is added to the section number for top-level headings,

1035the second for second-level headings, and so on.

1036So, for example, if you want the first top-level heading in your

1037document to be numbered \[lq]6\[rq], specify

1038\f[C]--number-offset=5\f[R].

1039If your document starts with a level-2 heading which you want to be

1040numbered \[lq]1.5\[rq], specify \f[C]--number-offset=1,4\f[R].

1041Offsets are 0 by default.

1042Implies \f[C]--number-sections\f[R].

1043.TP

1044\f[B]\f[CB]--listings\f[B]\f[R]

1045Use the \f[C]listings\f[R] package for LaTeX code blocks.

1046The package does not support multi-byte encoding for source code.

1047To handle UTF-8 you would need to use a custom template.

1048This issue is fully documented here: Encoding issue with the listings

1049package.

1050.TP

1051\f[B]\f[CB]-i\f[B]\f[R], \f[B]\f[CB]--incremental\f[B]\f[R]

1052Make list items in slide shows display incrementally (one by one).

1053The default is for lists to be displayed all at once.

1054.TP

1055\f[B]\f[CB]--slide-level=\f[B]\f[R]\f[I]NUMBER\f[R]

1056Specifies that headings with the specified level create slides (for

1057\f[C]beamer\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],

1058\f[C]dzslides\f[R]).

1059Headings above this level in the hierarchy are used to divide the slide

1060show into sections; headings below this level create subheads within a

1061slide.

1062Note that content that is not contained under slide-level headings will

1063not appear in the slide show.

1064The default is to set the slide level based on the contents of the

1065document; see Structuring the slide show.

1066.TP

1067\f[B]\f[CB]--section-divs\f[B]\f[R]

1068Wrap sections in \f[C]<section>\f[R] tags (or \f[C]<div>\f[R] tags for

1069\f[C]html4\f[R]), and attach identifiers to the enclosing

1070\f[C]<section>\f[R] (or \f[C]<div>\f[R]) rather than the heading itself.

1071See Heading identifiers, below.

1072.TP

1073\f[B]\f[CB]--email-obfuscation=none\f[B]\f[R]|\f[B]\f[CB]javascript\f[B]\f[R]|\f[B]\f[CB]references\f[B]\f[R]

1074Specify a method for obfuscating \f[C]mailto:\f[R] links in HTML

1075documents.

1076\f[C]none\f[R] leaves \f[C]mailto:\f[R] links as they are.

1077\f[C]javascript\f[R] obfuscates them using JavaScript.

1078\f[C]references\f[R] obfuscates them by printing their letters as

1079decimal or hexadecimal character references.

1080The default is \f[C]none\f[R].

1081.TP

1082\f[B]\f[CB]--id-prefix=\f[B]\f[R]\f[I]STRING\f[R]

1083Specify a prefix to be added to all identifiers and internal links in

1084HTML and DocBook output, and to footnote numbers in Markdown and Haddock

1085output.

1086This is useful for preventing duplicate identifiers when generating

1087fragments to be included in other pages.

1088.TP

1089\f[B]\f[CB]-T\f[B]\f[R] \f[I]STRING\f[R], \f[B]\f[CB]--title-prefix=\f[B]\f[R]\f[I]STRING\f[R]

1090Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that

1091appears in the HTML header (but not in the title as it appears at the

1092beginning of the HTML body).

1093Implies \f[C]--standalone\f[R].

1094.TP

1095\f[B]\f[CB]-c\f[B]\f[R] \f[I]URL\f[R], \f[B]\f[CB]--css=\f[B]\f[R]\f[I]URL\f[R]

1096Link to a CSS style sheet.

1097This option can be used repeatedly to include multiple files.

1098They will be included in the order specified.

1099.RS

1100.PP

1101A stylesheet is required for generating EPUB.

1102If none is provided using this option (or the \f[C]css\f[R] or

1103\f[C]stylesheet\f[R] metadata fields), pandoc will look for a file

1104\f[C]epub.css\f[R] in the user data directory (see

1105\f[C]--data-dir\f[R]).

1106If it is not found there, sensible defaults will be used.

1107.RE

1108.TP

1109\f[B]\f[CB]--reference-doc=\f[B]\f[R]\f[I]FILE\f[R]

1110Use the specified file as a style reference in producing a docx or ODT

1111file.

1112.RS

1113.TP

1114Docx

1115For best results, the reference docx should be a modified version of a

1116docx file produced using pandoc.

1117The contents of the reference docx are ignored, but its stylesheets and

1118document properties (including margins, page size, header, and footer)

1119are used in the new docx.

1120If no reference docx is specified on the command line, pandoc will look

1121for a file \f[C]reference.docx\f[R] in the user data directory (see

1122\f[C]--data-dir\f[R]).

1123If this is not found either, sensible defaults will be used.

1124.RS

1125.PP

1126To produce a custom \f[C]reference.docx\f[R], first get a copy of the

1127default \f[C]reference.docx\f[R]:

1128\f[C]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R].

1129Then open \f[C]custom-reference.docx\f[R] in Word, modify the styles as

1130you wish, and save the file.

1131For best results, do not make changes to this file other than modifying

1132the styles used by pandoc:

1133.PP

1134Paragraph styles:

1135.IP \[bu] 2

1136Normal

1137.IP \[bu] 2

1138Body Text

1139.IP \[bu] 2

1140First Paragraph

1141.IP \[bu] 2

1142Compact

1143.IP \[bu] 2

1144Title

1145.IP \[bu] 2

1146Subtitle

1147.IP \[bu] 2

1148Author

1149.IP \[bu] 2

1150Date

1151.IP \[bu] 2

1152Abstract

1153.IP \[bu] 2

1154Bibliography

1155.IP \[bu] 2

1156Heading 1

1157.IP \[bu] 2

1158Heading 2

1159.IP \[bu] 2

1160Heading 3

1161.IP \[bu] 2

1162Heading 4

1163.IP \[bu] 2

1164Heading 5

1165.IP \[bu] 2

1166Heading 6

1167.IP \[bu] 2

1168Heading 7

1169.IP \[bu] 2

1170Heading 8

1171.IP \[bu] 2

1172Heading 9

1173.IP \[bu] 2

1174Block Text

1175.IP \[bu] 2

1176Footnote Text

1177.IP \[bu] 2

1178Definition Term

1179.IP \[bu] 2

1180Definition

1181.IP \[bu] 2

1182Caption

1183.IP \[bu] 2

1184Table Caption

1185.IP \[bu] 2

1186Image Caption

1187.IP \[bu] 2

1188Figure

1189.IP \[bu] 2

1190Captioned Figure

1191.IP \[bu] 2

1192TOC Heading

1193.PP

1194Character styles:

1195.IP \[bu] 2

1196Default Paragraph Font

1197.IP \[bu] 2

1198Body Text Char

1199.IP \[bu] 2

1200Verbatim Char

1201.IP \[bu] 2

1202Footnote Reference

1203.IP \[bu] 2

1204Hyperlink

1205.IP \[bu] 2

1206Section Number

1207.PP

1208Table style:

1209.IP \[bu] 2

1210Table

1211.RE

1212.TP

1213ODT

1214For best results, the reference ODT should be a modified version of an

1215ODT produced using pandoc.

1216The contents of the reference ODT are ignored, but its stylesheets are

1217used in the new ODT.

1218If no reference ODT is specified on the command line, pandoc will look

1219for a file \f[C]reference.odt\f[R] in the user data directory (see

1220\f[C]--data-dir\f[R]).

1221If this is not found either, sensible defaults will be used.

1222.RS

1223.PP

1224To produce a custom \f[C]reference.odt\f[R], first get a copy of the

1225default \f[C]reference.odt\f[R]:

1226\f[C]pandoc -o custom-reference.odt --print-default-data-file reference.odt\f[R].

1227Then open \f[C]custom-reference.odt\f[R] in LibreOffice, modify the

1228styles as you wish, and save the file.

1229.RE

1230.TP

1231PowerPoint

1232Templates included with Microsoft PowerPoint 2013 (either with

1233\f[C].pptx\f[R] or \f[C].potx\f[R] extension) are known to work, as are

1234most templates derived from these.

1235.RS

1236.PP

1237The specific requirement is that the template should begin with the

1238following first four layouts:

1239.IP "1." 3

1240Title Slide

1241.IP "2." 3

1242Title and Content

1243.IP "3." 3

1244Section Header

1245.IP "4." 3

1246Two Content

1247.PP

1248All templates included with a recent version of MS PowerPoint will fit

1249these criteria.

1250(You can click on \f[C]Layout\f[R] under the \f[C]Home\f[R] menu to

1251check.)

1252.PP

1253You can also modify the default \f[C]reference.pptx\f[R]: first run

1254\f[C]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R],

1255and then modify \f[C]custom-reference.pptx\f[R] in MS PowerPoint (pandoc

1256will use the first four layout slides, as mentioned above).

1257.RE

1258.RE

1259.TP

1260\f[B]\f[CB]--epub-cover-image=\f[B]\f[R]\f[I]FILE\f[R]

1261Use the specified image as the EPUB cover.

1262It is recommended that the image be less than 1000px in width and

1263height.

1264Note that in a Markdown source document you can also specify

1265\f[C]cover-image\f[R] in a YAML metadata block (see EPUB Metadata,

1266below).

1267.TP

1268\f[B]\f[CB]--epub-metadata=\f[B]\f[R]\f[I]FILE\f[R]

1269Look in the specified XML file for metadata for the EPUB.

1270The file should contain a series of Dublin Core elements.

1271For example:

1272.RS

1273.IP

1274.nf

1275\f[C]

1276 <dc:rights>Creative Commons</dc:rights>

1277 <dc:language>es-AR</dc:language>

1278\f[R]

1279.fi

1280.PP

1281By default, pandoc will include the following metadata elements:

1282\f[C]<dc:title>\f[R] (from the document title), \f[C]<dc:creator>\f[R]

1283(from the document authors), \f[C]<dc:date>\f[R] (from the document

1284date, which should be in ISO 8601 format), \f[C]<dc:language>\f[R] (from

1285the \f[C]lang\f[R] variable, or, if is not set, the locale), and

1286\f[C]<dc:identifier id=\[dq]BookId\[dq]>\f[R] (a randomly generated

1287UUID).

1288Any of these may be overridden by elements in the metadata file.

1289.PP

1290Note: if the source document is Markdown, a YAML metadata block in the

1291document can be used instead.

1292See below under EPUB Metadata.

1293.RE

1294.TP

1295\f[B]\f[CB]--epub-embed-font=\f[B]\f[R]\f[I]FILE\f[R]

1296Embed the specified font in the EPUB.

1297This option can be repeated to embed multiple fonts.

1298Wildcards can also be used: for example, \f[C]DejaVuSans-*.ttf\f[R].

1299However, if you use wildcards on the command line, be sure to escape

1300them or put the whole filename in single quotes, to prevent them from

1301being interpreted by the shell.

1302To use the embedded fonts, you will need to add declarations like the

1303following to your CSS (see \f[C]--css\f[R]):

1304.RS

1305.IP

1306.nf

1307\f[C]

1308\[at]font-face {

1309font-family: DejaVuSans;

1310font-style: normal;

1311font-weight: normal;

1312src:url(\[dq]DejaVuSans-Regular.ttf\[dq]);

1313}

1314\[at]font-face {

1315font-family: DejaVuSans;

1316font-style: normal;

1317font-weight: bold;

1318src:url(\[dq]DejaVuSans-Bold.ttf\[dq]);

1319}

1320\[at]font-face {

1321font-family: DejaVuSans;

1322font-style: italic;

1323font-weight: normal;

1324src:url(\[dq]DejaVuSans-Oblique.ttf\[dq]);

1325}

1326\[at]font-face {

1327font-family: DejaVuSans;

1328font-style: italic;

1329font-weight: bold;

1330src:url(\[dq]DejaVuSans-BoldOblique.ttf\[dq]);

1331}

1332body { font-family: \[dq]DejaVuSans\[dq]; }

1333\f[R]

1334.fi

1335.RE

1336.TP

1337\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]

1338Specify the heading level at which to split the EPUB into separate

1339\[lq]chapter\[rq] files.

1340The default is to split into chapters at level-1 headings.

1341This option only affects the internal composition of the EPUB, not the

1342way chapters and sections are displayed to users.

1343Some readers may be slow if the chapter files are too large, so for

1344large documents with few level-1 headings, one might want to use a

1345chapter level of 2 or 3.

1346.TP

1347\f[B]\f[CB]--epub-subdirectory=\f[B]\f[R]\f[I]DIRNAME\f[R]

1348Specify the subdirectory in the OCF container that is to hold the

1349EPUB-specific contents.

1350The default is \f[C]EPUB\f[R].

1351To put the EPUB contents in the top level, use an empty string.

1352.TP

1353\f[B]\f[CB]--ipynb-output=all|none|best\f[B]\f[R]

1354Determines how ipynb output cells are treated.

1355\f[C]all\f[R] means that all of the data formats included in the

1356original are preserved.

1357\f[C]none\f[R] means that the contents of data cells are omitted.

1358\f[C]best\f[R] causes pandoc to try to pick the richest data block in

1359each output cell that is compatible with the output format.

1360The default is \f[C]best\f[R].

1361.TP

1362\f[B]\f[CB]--pdf-engine=\f[B]\f[R]\f[I]PROGRAM\f[R]

1363Use the specified engine when producing PDF output.

1364Valid values are \f[C]pdflatex\f[R], \f[C]lualatex\f[R],

1365\f[C]xelatex\f[R], \f[C]latexmk\f[R], \f[C]tectonic\f[R],

1366\f[C]wkhtmltopdf\f[R], \f[C]weasyprint\f[R], \f[C]prince\f[R],

1367\f[C]context\f[R], and \f[C]pdfroff\f[R].

1368If the engine is not in your PATH, the full path of the engine may be

1369specified here.

1370If this option is not specified, pandoc uses the following defaults

1371depending on the output format specified using \f[C]-t/--to\f[R]:

1372.RS

1373.IP \[bu] 2

1374\f[C]-t latex\f[R] or none: \f[C]pdflatex\f[R] (other options:

1375\f[C]xelatex\f[R], \f[C]lualatex\f[R], \f[C]tectonic\f[R],

1376\f[C]latexmk\f[R])

1377.IP \[bu] 2

1378\f[C]-t context\f[R]: \f[C]context\f[R]

1379.IP \[bu] 2

1380\f[C]-t html\f[R]: \f[C]wkhtmltopdf\f[R] (other options:

1381\f[C]prince\f[R], \f[C]weasyprint\f[R]; see print-css.rocks for a good

1382introduction to PDF generation from HTML/CSS.)

1383.IP \[bu] 2

1384\f[C]-t ms\f[R]: \f[C]pdfroff\f[R]

1385.RE

1386.TP

1387\f[B]\f[CB]--pdf-engine-opt=\f[B]\f[R]\f[I]STRING\f[R]

1388Use the given string as a command-line argument to the

1389\f[C]pdf-engine\f[R].

1390For example, to use a persistent directory \f[C]foo\f[R] for

1391\f[C]latexmk\f[R]\[cq]s auxiliary files, use

1392\f[C]--pdf-engine-opt=-outdir=foo\f[R].

1393Note that no check for duplicate options is done.

1394.SS Citation rendering

1395.TP

1396\f[B]\f[CB]-C\f[B]\f[R], \f[B]\f[CB]--citeproc\f[B]\f[R]

1397Process the citations in the file, replacing them with rendered

1398citations and adding a bibliography.

1399Citation processing will not take place unless bibliographic data is

1400supplied, either through an external file specified using the

1401\f[C]--bibliography\f[R] option or the \f[C]bibliography\f[R] field in

1402metadata, or via a \f[C]references\f[R] section in metadata containing a

1403list of citations in CSL YAML format with Markdown formatting.

1404The style is controlled by a CSL stylesheet specified using the

1405\f[C]--csl\f[R] option or the \f[C]csl\f[R] field in metadata.

1406(If no stylesheet is specified, the \f[C]chicago-author-date\f[R] style

1407will be used by default.) The citation processing transformation may be

1408applied before or after filters or Lua filters (see \f[C]--filter\f[R],

1409\f[C]--lua-filter\f[R]): these transformations are applied in the order

1410they appear on the command line.

1411For more information, see the section on Citations.

1412.TP

1413\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]

1414Set the \f[C]bibliography\f[R] field in the document\[cq]s metadata to

1415\f[I]FILE\f[R], overriding any value set in the metadata.

1416If you supply this argument multiple times, each \f[I]FILE\f[R] will be

1417added to bibliography.

1418If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.

1419If \f[I]FILE\f[R] is not found relative to the working directory, it

1420will be sought in the resource path (see \f[C]--resource-path\f[R]).

1421.TP

1422\f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R]

1423Set the \f[C]csl\f[R] field in the document\[cq]s metadata to

1424\f[I]FILE\f[R], overriding any value set in the metadata.

1425(This is equivalent to \f[C]--metadata csl=FILE\f[R].) If \f[I]FILE\f[R]

1426is a URL, it will be fetched via HTTP.

1427If \f[I]FILE\f[R] is not found relative to the working directory, it

1428will be sought in the resource path (see \f[C]--resource-path\f[R]) and

1429finally in the \f[C]csl\f[R] subdirectory of the pandoc user data

1430directory.

1431.TP

1432\f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]

1433Set the \f[C]citation-abbreviations\f[R] field in the document\[cq]s

1434metadata to \f[I]FILE\f[R], overriding any value set in the metadata.

1435(This is equivalent to

1436\f[C]--metadata citation-abbreviations=FILE\f[R].) If \f[I]FILE\f[R] is

1437a URL, it will be fetched via HTTP.

1438If \f[I]FILE\f[R] is not found relative to the working directory, it

1439will be sought in the resource path (see \f[C]--resource-path\f[R]) and

1440finally in the \f[C]csl\f[R] subdirectory of the pandoc user data

1441directory.

1442.TP

1443\f[B]\f[CB]--natbib\f[B]\f[R]

1444Use \f[C]natbib\f[R] for citations in LaTeX output.

1445This option is not for use with the \f[C]--citeproc\f[R] option or with

1446PDF output.

1447It is intended for use in producing a LaTeX file that can be processed

1448with \f[C]bibtex\f[R].

1449.TP

1450\f[B]\f[CB]--biblatex\f[B]\f[R]

1451Use \f[C]biblatex\f[R] for citations in LaTeX output.

1452This option is not for use with the \f[C]--citeproc\f[R] option or with

1453PDF output.

1454It is intended for use in producing a LaTeX file that can be processed

1455with \f[C]bibtex\f[R] or \f[C]biber\f[R].

1456.SS Math rendering in HTML

1457.PP

1458The default is to render TeX math as far as possible using Unicode

1459characters.

1460Formulas are put inside a \f[C]span\f[R] with

1461\f[C]class=\[dq]math\[dq]\f[R], so that they may be styled differently

1462from the surrounding text if needed.

1463However, this gives acceptable results only for basic math, usually you

1464will want to use \f[C]--mathjax\f[R] or another of the following

1465options.

1466.TP

1467\f[B]\f[CB]--mathjax\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]

1468Use MathJax to display embedded TeX math in HTML output.

1469TeX math will be put between \f[C]\[rs](...\[rs])\f[R] (for inline math)

1470or \f[C]\[rs][...\[rs]]\f[R] (for display math) and wrapped in

1471\f[C]<span>\f[R] tags with class \f[C]math\f[R].

1472Then the MathJax JavaScript will render it.

1473The \f[I]URL\f[R] should point to the \f[C]MathJax.js\f[R] load script.

1474If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be

1475inserted.

1476.TP

1477\f[B]\f[CB]--mathml\f[B]\f[R]

1478Convert TeX math to MathML (in \f[C]epub3\f[R], \f[C]docbook4\f[R],

1479\f[C]docbook5\f[R], \f[C]jats\f[R], \f[C]html4\f[R] and

1480\f[C]html5\f[R]).

1481This is the default in \f[C]odt\f[R] output.

1482Note that currently only Firefox and Safari (and select e-book readers)

1483natively support MathML.

1484.TP

1485\f[B]\f[CB]--webtex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]

1486Convert TeX formulas to \f[C]<img>\f[R] tags that link to an external

1487script that converts formulas to images.

1488The formula will be URL-encoded and concatenated with the URL provided.

1489For SVG images you can for example use

1490\f[C]--webtex https://latex.codecogs.com/svg.latex?\f[R].

1491If no URL is specified, the CodeCogs URL generating PNGs will be used

1492(\f[C]https://latex.codecogs.com/png.latex?\f[R]).

1493Note: the \f[C]--webtex\f[R] option will affect Markdown output as well

1494as HTML, which is useful if you\[cq]re targeting a version of Markdown

1495without native math support.

1496.TP

1497\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]

1498Use KaTeX to display embedded TeX math in HTML output.

1499The \f[I]URL\f[R] is the base URL for the KaTeX library.

1500That directory should contain a \f[C]katex.min.js\f[R] and a

1501\f[C]katex.min.css\f[R] file.

1502If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be

1503inserted.

1504.TP

1505\f[B]\f[CB]--gladtex\f[B]\f[R]

1506Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.

1507The resulting HTML can then be processed by GladTeX to produce SVG

1508images of the typeset formulas and an HTML file with these images

1509embedded.

1510.RS

1511.IP

1512.nf

1513\f[C]

1514pandoc -s --gladtex input.md -o myfile.htex

1515gladtex -d image_dir myfile.htex

1516# produces myfile.html and images in image_dir

1517\f[R]

1518.fi

1519.RE

1520.SS Options for wrapper scripts

1521.TP

1522\f[B]\f[CB]--dump-args\f[B]\f[R]

1523Print information about command-line arguments to \f[I]stdout\f[R], then

1524exit.

1525This option is intended primarily for use in wrapper scripts.

1526The first line of output contains the name of the output file specified

1527with the \f[C]-o\f[R] option, or \f[C]-\f[R] (for \f[I]stdout\f[R]) if

1528no output file was specified.

1529The remaining lines contain the command-line arguments, one per line, in

1530the order they appear.

1531These do not include regular pandoc options and their arguments, but do

1532include any options appearing after a \f[C]--\f[R] separator at the end

1533of the line.

1534.TP

1535\f[B]\f[CB]--ignore-args\f[B]\f[R]

1536Ignore command-line arguments (for use in wrapper scripts).

1537Regular pandoc options are not ignored.

1538Thus, for example,

1539.RS

1540.IP

1541.nf

1542\f[C]

1543pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1

1544\f[R]

1545.fi

1546.PP

1547is equivalent to

1548.IP

1549.nf

1550\f[C]

1551pandoc -o foo.html -s

1552\f[R]

1553.fi

1554.RE

1555.SH EXIT CODES

1556.PP

1557If pandoc completes successfully, it will return exit code 0.

1558Nonzero exit codes have the following meanings:

1559.PP

1560.TS

1561tab(@);

1562r l.

1563T{

1564Code

1565T}@T{

1566Error

1567T}

1568_

1569T{

15703

1571T}@T{

1572PandocFailOnWarningError

1573T}

1574T{

15754

1576T}@T{

1577PandocAppError

1578T}

1579T{

15805

1581T}@T{

1582PandocTemplateError

1583T}

1584T{

15856

1586T}@T{

1587PandocOptionError

1588T}

1589T{

159021

1591T}@T{

1592PandocUnknownReaderError

1593T}

1594T{

159522

1596T}@T{

1597PandocUnknownWriterError

1598T}

1599T{

160023

1601T}@T{

1602PandocUnsupportedExtensionError

1603T}

1604T{

160524

1606T}@T{

1607PandocCiteprocError

1608T}

1609T{

161031

1611T}@T{

1612PandocEpubSubdirectoryError

1613T}

1614T{

161543

1616T}@T{

1617PandocPDFError

1618T}

1619T{

162044

1621T}@T{

1622PandocXMLError

1623T}

1624T{

162547

1626T}@T{

1627PandocPDFProgramNotFoundError

1628T}

1629T{

163061

1631T}@T{

1632PandocHttpError

1633T}

1634T{

163562

1636T}@T{

1637PandocShouldNeverHappenError

1638T}

1639T{

164063

1641T}@T{

1642PandocSomeError

1643T}

1644T{

164564

1646T}@T{

1647PandocParseError

1648T}

1649T{

165065

1651T}@T{

1652PandocParsecError

1653T}

1654T{

165566

1656T}@T{

1657PandocMakePDFError

1658T}

1659T{

166067

1661T}@T{

1662PandocSyntaxMapError

1663T}

1664T{

166583

1666T}@T{

1667PandocFilterError

1668T}

1669T{

167091

1671T}@T{

1672PandocMacroLoop

1673T}

1674T{

167592

1676T}@T{

1677PandocUTF8DecodingError

1678T}

1679T{

168093

1681T}@T{

1682PandocIpynbDecodingError

1683T}

1684T{

168594

1686T}@T{

1687PandocUnsupportedCharsetError

1688T}

1689T{

169097

1691T}@T{

1692PandocCouldNotFindDataFileError

1693T}

1694T{

169599

1696T}@T{

1697PandocResourceNotFound

1698T}

1699.TE

1700.SH DEFAULT FILES

1701.PP

1702The \f[C]--defaults\f[R] option may be used to specify a package of

1703options.

1704Here is a sample defaults file demonstrating all of the fields that may

1705be used:

1706.IP

1707.nf

1708\f[C]

1709from: markdown+emoji

1710# reader: may be used instead of from:

1711to: html5

1712# writer: may be used instead of to:

1713

1714# leave blank for output to stdout:

1715output-file:

1716# leave blank for input from stdin, use [] for no input:

1717input-files:

1718- preface.md

1719- content.md

1720# or you may use input-file: with a single value

1721

1722# Include options from the specified defaults files.

1723# The files will be searched for first in the working directory

1724# and then in the defaults subdirectory of the user data directory.

1725# The files are included in the same order in which they appear in

1726# the list. Options specified in this defaults file always have

1727# priority over the included ones.

1728defaults:

1729- defsA

1730- defsB

1731

1732template: letter

1733standalone: true

1734self-contained: false

1735

1736# note that structured variables may be specified:

1737variables:

1738 documentclass: book

1739 classoption:

1740 - twosides

1741 - draft

1742

1743# metadata values specified here are parsed as literal

1744# string text, not markdown:

1745metadata:

1746 author:

1747 - Sam Smith

1748 - Julie Liu

1749metadata-files:

1750- boilerplate.yaml

1751# or you may use metadata-file: with a single value

1752

1753# Note that these take files, not their contents:

1754include-before-body: []

1755include-after-body: []

1756include-in-header: []

1757resource-path: [\[dq].\[dq]]

1758

1759# turn on built-in citation processing. Note that if you need

1760# control over when the citeproc processing is done relative

1761# to other filters, you should instead use \[ga]citeproc\[ga] in the

1762# list of \[ga]filters\[ga] (see below).

1763citeproc: true

1764csl: ieee

1765bibliography:

1766- foobar.bib

1767- barbaz.json

1768citation-abbreviations: abbrevs.json

1769

1770# Filters will be assumed to be Lua filters if they have

1771# the .lua extension, and json filters otherwise. But

1772# the filter type can also be specified explicitly, as shown.

1773# Filters are run in the order specified.

1774# To include the built-in citeproc filter, use either \[ga]citeproc\[ga]

1775# or \[ga]{type: citeproc}\[ga].

1776filters:

1777- wordcount.lua

1778- type: json

1779 path: foo.lua

1780

1781file-scope: false

1782

1783data-dir:

1784

1785# ERROR, WARNING, or INFO

1786verbosity: INFO

1787log-file: log.json

1788

1789# citeproc, natbib, or biblatex. This only affects LaTeX

1790# output. If you want to use citeproc to format citations,

1791# you should also set \[aq]citeproc: true\[aq] (see above).

1792cite-method: citeproc

1793

1794# part, chapter, section, or default:

1795top-level-division: chapter

1796abbreviations:

1797

1798pdf-engine: pdflatex

1799pdf-engine-opts:

1800- \[dq]-shell-escape\[dq]

1801# you may also use pdf-engine-opt: with a single option

1802# pdf-engine-opt: \[dq]-shell-escape\[dq]

1803

1804# auto, preserve, or none

1805wrap: auto

1806columns: 78

1807dpi: 72

1808

1809extract-media: mediadir

1810

1811table-of-contents: true

1812toc-depth: 2

1813number-sections: false

1814# a list of offsets at each heading level

1815number-offset: [0,0,0,0,0,0]

1816# toc: may also be used instead of table-of-contents:

1817shift-heading-level-by: 1

1818section-divs: true

1819identifier-prefix: foo

1820title-prefix: \[dq]\[dq]

1821strip-empty-paragraphs: true

1822# lf, crlf, or native

1823eol: lf

1824strip-comments: false

1825indented-code-classes: []

1826ascii: true

1827default-image-extension: \[dq].jpg\[dq]

1828

1829# either a style name of a style definition file:

1830highlight-style: pygments

1831syntax-definitions:

1832- c.xml

1833# or you may use syntax-definition: with a single value

1834listings: false

1835

1836reference-doc: myref.docx

1837

1838# method is plain, webtex, gladtex, mathml, mathjax, katex

1839# you may specify a url with webtex, mathjax, katex

1840html-math-method:

1841 method: mathjax

1842 url: \[dq]https://cdn.jsdelivr.net/npm/mathjax\[at]3/es5/tex-mml-chtml.js\[dq]

1843# none, references, or javascript

1844email-obfuscation: javascript

1845

1846tab-stop: 8

1847preserve-tabs: true

1848

1849incremental: false

1850slide-level: 2

1851

1852epub-subdirectory: EPUB

1853epub-metadata: meta.xml

1854epub-fonts:

1855- foobar.otf

1856epub-chapter-level: 1

1857epub-cover-image: cover.jpg

1858

1859reference-links: true

1860# block, section, or document

1861reference-location: block

1862markdown-headings: setext

1863

1864# accept, reject, or all

1865track-changes: accept

1866

1867html-q-tags: false

1868css:

1869- site.css

1870

1871# none, all, or best

1872ipynb-output: best

1873

1874# A list of two-element lists

1875request-headers:

1876- [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]

1877

1878fail-if-warnings: false

1879dump-args: false

1880ignore-args: false

1881trace: false

1882\f[R]

1883.fi

1884.PP

1885Fields that are omitted will just have their regular default values.

1886So a defaults file can be as simple as one line:

1887.IP

1888.nf

1889\f[C]

1890verbosity: INFO

1891\f[R]

1892.fi

1893.PP

1894In fields that expect a file path (or list of file paths), the following

1895syntax may be used to interpolate environment variables:

1896.IP

1897.nf

1898\f[C]

1899csl: ${HOME}/mycsldir/special.csl

1900\f[R]

1901.fi

1902.PP

1903\f[C]${USERDATA}\f[R] may also be used; this will always resolve to the

1904user data directory that is current when the defaults file is parsed,

1905regardless of the setting of the environment variable

1906\f[C]USERDATA\f[R].

1907.PP

1908\f[C]${.}\f[R] will resolve to the directory containing the default file

1909itself.

1910This allows you to refer to resources contained in that directory:

1911.IP

1912.nf

1913\f[C]

1914epub-cover-image: ${.}/cover.jpg

1915epub-metadata: ${.}/meta.xml

1916resource-path:

1917- . # the working directory from which pandoc is run

1918- ${.}/images # the images subdirectory of the directory

1919 # containing this defaults file

1920\f[R]

1921.fi

1922.PP

1923This environment variable interpolation syntax \f[I]only\f[R] works in

1924fields that expect file paths.

1925.PP

1926Default files can be placed in the \f[C]defaults\f[R] subdirectory of

1927the user data directory and used from any directory.

1928For example, one could create a file specifying defaults for writing

1929letters, save it as \f[C]letter.yaml\f[R] in the \f[C]defaults\f[R]

1930subdirectory of the user data directory, and then invoke these defaults

1931from any directory using \f[C]pandoc --defaults letter\f[R] or

1932\f[C]pandoc -dletter\f[R].

1933.PP

1934When multiple defaults are used, their contents will be combined.

1935.PP

1936Note that, where command-line arguments may be repeated

1937(\f[C]--metadata-file\f[R], \f[C]--css\f[R],

1938\f[C]--include-in-header\f[R], \f[C]--include-before-body\f[R],

1939\f[C]--include-after-body\f[R], \f[C]--variable\f[R],

1940\f[C]--metadata\f[R], \f[C]--syntax-definition\f[R]), the values

1941specified on the command line will combine with values specified in the

1942defaults file, rather than replacing them.

1943.SH TEMPLATES

1944.PP

1945When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a

1946template to add header and footer material that is needed for a

1947self-standing document.

1948To see the default template that is used, just type

1949.IP

1950.nf

1951\f[C]

1952pandoc -D *FORMAT*

1953\f[R]

1954.fi

1955.PP

1956where \f[I]FORMAT\f[R] is the name of the output format.

1957A custom template can be specified using the \f[C]--template\f[R]

1958option.

1959You can also override the system default templates for a given output

1960format \f[I]FORMAT\f[R] by putting a file

1961\f[C]templates/default.*FORMAT*\f[R] in the user data directory (see

1962\f[C]--data-dir\f[R], above).

1963\f[I]Exceptions:\f[R]

1964.IP \[bu] 2

1965For \f[C]odt\f[R] output, customize the \f[C]default.opendocument\f[R]

1966template.

1967.IP \[bu] 2

1968For \f[C]pdf\f[R] output, customize the \f[C]default.latex\f[R] template

1969(or the \f[C]default.context\f[R] template, if you use

1970\f[C]-t context\f[R], or the \f[C]default.ms\f[R] template, if you use

1971\f[C]-t ms\f[R], or the \f[C]default.html\f[R] template, if you use

1972\f[C]-t html\f[R]).

1973.IP \[bu] 2

1974\f[C]docx\f[R] and \f[C]pptx\f[R] have no template (however, you can use

1975\f[C]--reference-doc\f[R] to customize the output).

1976.PP

1977Templates contain \f[I]variables\f[R], which allow for the inclusion of

1978arbitrary information at any point in the file.

1979They may be set at the command line using the \f[C]-V/--variable\f[R]

1980option.

1981If a variable is not set, pandoc will look for the key in the

1982document\[cq]s metadata, which can be set using either YAML metadata

1983blocks or with the \f[C]-M/--metadata\f[R] option.

1984In addition, some variables are given default values by pandoc.

1985See Variables below for a list of variables used in pandoc\[cq]s default

1986templates.

1987.PP

1988If you use custom templates, you may need to revise them as pandoc

1989changes.

1990We recommend tracking the changes in the default templates, and

1991modifying your custom templates accordingly.

1992An easy way to do this is to fork the pandoc-templates repository and

1993merge in changes after each pandoc release.

1994.SS Template syntax

1995.SS Comments

1996.PP

1997Anything between the sequence \f[C]$--\f[R] and the end of the line will

1998be treated as a comment and omitted from the output.

1999.SS Delimiters

2000.PP

2001To mark variables and control structures in the template, either

2002\f[C]$\f[R]\&...\f[C]$\f[R] or \f[C]${\f[R]\&...\f[C]}\f[R] may be used

2003as delimiters.

2004The styles may also be mixed in the same template, but the opening and

2005closing delimiter must match in each case.

2006The opening delimiter may be followed by one or more spaces or tabs,

2007which will be ignored.

2008The closing delimiter may be followed by one or more spaces or tabs,

2009which will be ignored.

2010.PP

2011To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].

2012.SS Interpolated variables

2013.PP

2014A slot for an interpolated variable is a variable name surrounded by

2015matched delimiters.

2016Variable names must begin with a letter and can contain letters,

2017numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].

2018The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],

2019\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may

2020not be used as variable names.

2021Examples:

2022.IP

2023.nf

2024\f[C]

2025$foo$

2026$foo.bar.baz$

2027$foo_bar.baz-bim$

2028$ foo $

2029${foo}

2030${foo.bar.baz}

2031${foo_bar.baz-bim}

2032${ foo }

2033\f[R]

2034.fi

2035.PP

2036Variable names with periods are used to get at structured variable

2037values.

2038So, for example, \f[C]employee.salary\f[R] will return the value of the

2039\f[C]salary\f[R] field of the object that is the value of the

2040\f[C]employee\f[R] field.

2041.IP \[bu] 2

2042If the value of the variable is simple value, it will be rendered

2043verbatim.

2044(Note that no escaping is done; the assumption is that the calling

2045program will escape the strings appropriately for the output format.)

2046.IP \[bu] 2

2047If the value is a list, the values will be concatenated.

2048.IP \[bu] 2

2049If the value is a map, the string \f[C]true\f[R] will be rendered.

2050.IP \[bu] 2

2051Every other value will be rendered as the empty string.

2052.SS Conditionals

2053.PP

2054A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched

2055delimiters) and ends with \f[C]endif\f[R] (enclosed in matched

2056delimiters).

2057It may optionally contain an \f[C]else\f[R] (enclosed in matched

2058delimiters).

2059The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty

2060value, otherwise the \f[C]else\f[R] section is used (if present).

2061Examples:

2062.IP

2063.nf

2064\f[C]

2065$if(foo)$bar$endif$

2066

2067$if(foo)$

2068 $foo$

2069$endif$

2070

2071$if(foo)$

2072part one

2073$else$

2074part two

2075$endif$

2076

2077${if(foo)}bar${endif}

2078

2079${if(foo)}

2080 ${foo}

2081${endif}

2082

2083${if(foo)}

2084${ foo.bar }

2085${else}

2086no foo!

2087${endif}

2088\f[R]

2089.fi

2090.PP

2091The keyword \f[C]elseif\f[R] may be used to simplify complex nested

2092conditionals:

2093.IP

2094.nf

2095\f[C]

2096$if(foo)$

2097XXX

2098$elseif(bar)$

2099YYY

2100$else$

2101ZZZ

2102$endif$

2103\f[R]

2104.fi

2105.SS For loops

2106.PP

2107A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched

2108delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched

2109delimiters.

2110.IP \[bu] 2

2111If \f[C]variable\f[R] is an array, the material inside the loop will be

2112evaluated repeatedly, with \f[C]variable\f[R] being set to each value of

2113the array in turn, and concatenated.

2114.IP \[bu] 2

2115If \f[C]variable\f[R] is a map, the material inside will be set to the

2116map.

2117.IP \[bu] 2

2118If the value of the associated variable is not an array or a map, a

2119single iteration will be performed on its value.

2120.PP

2121Examples:

2122.IP

2123.nf

2124\f[C]

2125$for(foo)$$foo$$sep$, $endfor$

2126

2127$for(foo)$

2128 - $foo.last$, $foo.first$

2129$endfor$

2130

2131${ for(foo.bar) }

2132 - ${ foo.bar.last }, ${ foo.bar.first }

2133${ endfor }

2134

2135$for(mymap)$

2136$it.name$: $it.office$

2137$endfor$

2138\f[R]

2139.fi

2140.PP

2141You may optionally specify a separator between consecutive values using

2142\f[C]sep\f[R] (enclosed in matched delimiters).

2143The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the

2144separator.

2145.IP

2146.nf

2147\f[C]

2148${ for(foo) }${ foo }${ sep }, ${ endfor }

2149\f[R]

2150.fi

2151.PP

2152Instead of using \f[C]variable\f[R] inside the loop, the special

2153anaphoric keyword \f[C]it\f[R] may be used.

2154.IP

2155.nf

2156\f[C]

2157${ for(foo.bar) }

2158 - ${ it.last }, ${ it.first }

2159${ endfor }

2160\f[R]

2161.fi

2162.SS Partials

2163.PP

2164Partials (subtemplates stored in different files) may be included by

2165using the name of the partial, followed by \f[C]()\f[R], for example:

2166.IP

2167.nf

2168\f[C]

2169${ styles() }

2170\f[R]

2171.fi

2172.PP

2173Partials will be sought in the directory containing the main template.

2174The file name will be assumed to have the same extension as the main

2175template if it lacks an extension.

2176When calling the partial, the full name including file extension can

2177also be used:

2178.IP

2179.nf

2180\f[C]

2181${ styles.html() }

2182\f[R]

2183.fi

2184.PP

2185(If a partial is not found in the directory of the template and the

2186template path is given as a relative path, it will also be sought in the

2187\f[C]templates\f[R] subdirectory of the user data directory.)

2188.PP

2189Partials may optionally be applied to variables using a colon:

2190.IP

2191.nf

2192\f[C]

2193${ date:fancy() }

2194

2195${ articles:bibentry() }

2196\f[R]

2197.fi

2198.PP

2199If \f[C]articles\f[R] is an array, this will iterate over its values,

2200applying the partial \f[C]bibentry()\f[R] to each one.

2201So the second example above is equivalent to

2202.IP

2203.nf

2204\f[C]

2205${ for(articles) }

2206${ it:bibentry() }

2207${ endfor }

2208\f[R]

2209.fi

2210.PP

2211Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating

2212over partials.

2213In the above examples, the \f[C]bibentry\f[R] partial should contain

2214\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].

2215.PP

2216Final newlines are omitted from included partials.

2217.PP

2218Partials may include other partials.

2219.PP

2220A separator between values of an array may be specified in square

2221brackets, immediately after the variable name or partial:

2222.IP

2223.nf

2224\f[C]

2225${months[, ]}$

2226

2227${articles:bibentry()[; ]$

2228\f[R]

2229.fi

2230.PP

2231The separator in this case is literal and (unlike with \f[C]sep\f[R] in

2232an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or

2233other template directives.

2234.SS Nesting

2235.PP

2236To ensure that content is \[lq]nested,\[rq] that is, subsequent lines

2237indented, use the \f[C]\[ha]\f[R] directive:

2238.IP

2239.nf

2240\f[C]

2241$item.number$ $\[ha]$$item.description$ ($item.price$)

2242\f[R]

2243.fi

2244.PP

2245In this example, if \f[C]item.description\f[R] has multiple lines, they

2246will all be indented to line up with the first line:

2247.IP

2248.nf

2249\f[C]

225000123 A fine bottle of 18-year old

2251 Oban whiskey. ($148)

2252\f[R]

2253.fi

2254.PP

2255To nest multiple lines to the same level, align them with the

2256\f[C]\[ha]\f[R] directive in the template.

2257For example:

2258.IP

2259.nf

2260\f[C]

2261$item.number$ $\[ha]$$item.description$ ($item.price$)

2262 (Available til $item.sellby$.)

2263\f[R]

2264.fi

2265.PP

2266will produce

2267.IP

2268.nf

2269\f[C]

227000123 A fine bottle of 18-year old

2271 Oban whiskey. ($148)

2272 (Available til March 30, 2020.)

2273\f[R]

2274.fi

2275.PP

2276If a variable occurs by itself on a line, preceded by whitespace and not

2277followed by further text or directives on the same line, and the

2278variable\[cq]s value contains multiple lines, it will be nested

2279automatically.

2280.SS Breakable spaces

2281.PP

2282Normally, spaces in the template itself (as opposed to values of the

2283interpolated variables) are not breakable, but they can be made

2284breakable in part of the template by using the \f[C]\[ti]\f[R] keyword

2285(ended with another \f[C]\[ti]\f[R]).

2286.IP

2287.nf

2288\f[C]

2289$\[ti]$This long line may break if the document is rendered

2290with a short line length.$\[ti]$

2291\f[R]

2292.fi

2293.SS Pipes

2294.PP

2295A pipe transforms the value of a variable or partial.

2296Pipes are specified using a slash (\f[C]/\f[R]) between the variable

2297name (or partial) and the pipe name.

2298Example:

2299.IP

2300.nf

2301\f[C]

2302$for(name)$

2303$name/uppercase$

2304$endfor$

2305

2306$for(metadata/pairs)$

2307- $it.key$: $it.value$

2308$endfor$

2309

2310$employee:name()/uppercase$

2311\f[R]

2312.fi

2313.PP

2314Pipes may be chained:

2315.IP

2316.nf

2317\f[C]

2318$for(employees/pairs)$

2319$it.key/alpha/uppercase$. $it.name$

2320$endfor$

2321\f[R]

2322.fi

2323.PP

2324Some pipes take parameters:

2325.IP

2326.nf

2327\f[C]

2328|----------------------|------------|

2329$for(employee)$

2330$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$

2331$endfor$

2332|----------------------|------------|

2333\f[R]

2334.fi

2335.PP

2336Currently the following pipes are predefined:

2337.IP \[bu] 2

2338\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with

2339\f[C]key\f[R] and \f[C]value\f[R] fields.

2340If the original value was an array, the \f[C]key\f[R] will be the array

2341index, starting with 1.

2342.IP \[bu] 2

2343\f[C]uppercase\f[R]: Converts text to uppercase.

2344.IP \[bu] 2

2345\f[C]lowercase\f[R]: Converts text to lowercase.

2346.IP \[bu] 2

2347\f[C]length\f[R]: Returns the length of the value: number of characters

2348for a textual value, number of elements for a map or array.

2349.IP \[bu] 2

2350\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect

2351on other values.

2352.IP \[bu] 2

2353\f[C]first\f[R]: Returns the first value of an array, if applied to a

2354non-empty array; otherwise returns the original value.

2355.IP \[bu] 2

2356\f[C]last\f[R]: Returns the last value of an array, if applied to a

2357non-empty array; otherwise returns the original value.

2358.IP \[bu] 2

2359\f[C]rest\f[R]: Returns all but the first value of an array, if applied

2360to a non-empty array; otherwise returns the original value.

2361.IP \[bu] 2

2362\f[C]allbutlast\f[R]: Returns all but the last value of an array, if

2363applied to a non-empty array; otherwise returns the original value.

2364.IP \[bu] 2

2365\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).

2366.IP \[bu] 2

2367\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.

2368.IP \[bu] 2

2369\f[C]alpha\f[R]: Converts textual values that can be read as an integer

2370into lowercase alphabetic characters \f[C]a..z\f[R] (mod 26).

2371This can be used to get lettered enumeration from array indices.

2372To get uppercase letters, chain with \f[C]uppercase\f[R].

2373.IP \[bu] 2

2374\f[C]roman\f[R]: Converts textual values that can be read as an integer

2375into lowercase roman numerials.

2376This can be used to get lettered enumeration from array indices.

2377To get uppercase roman, chain with \f[C]uppercase\f[R].

2378.IP \[bu] 2

2379\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2380textual value in a block of width \f[C]n\f[R], aligned to the left, with

2381an optional left and right border.

2382Has no effect on other values.

2383This can be used to align material in tables.

2384Widths are positive integers indicating the number of characters.

2385Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and

2386\f[C]\[rs]\f[R] characters must be backslash-escaped.

2387.IP \[bu] 2

2388\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2389textual value in a block of width \f[C]n\f[R], aligned to the right, and

2390has no effect on other values.

2391.IP \[bu] 2

2392\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2393textual value in a block of width \f[C]n\f[R], aligned to the center,

2394and has no effect on other values.

2395.SS Variables

2396.SS Metadata variables

2397.TP

2398\f[B]\f[CB]title\f[B]\f[R], \f[B]\f[CB]author\f[B]\f[R], \f[B]\f[CB]date\f[B]\f[R]

2399allow identification of basic aspects of the document.

2400Included in PDF metadata through LaTeX and ConTeXt.

2401These can be set through a pandoc title block, which allows for multiple

2402authors, or through a YAML metadata block:

2403.RS

2404.IP

2405.nf

2406\f[C]

2407---

2408author:

2409- Aristotle

2410- Peter Abelard

2411\&...

2412\f[R]

2413.fi

2414.PP

2415Note that if you just want to set PDF or HTML metadata, without

2416including a title block in the document itself, you can set the

2417\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]

2418variables.

2419(By default these are set automatically, based on \f[C]title\f[R],

2420\f[C]author\f[R], and \f[C]date\f[R].) The page title in HTML is set by

2421\f[C]pagetitle\f[R], which is equal to \f[C]title\f[R] by default.

2422.RE

2423.TP

2424\f[B]\f[CB]subtitle\f[B]\f[R]

2425document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx

2426documents

2427.TP

2428\f[B]\f[CB]abstract\f[B]\f[R]

2429document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx

2430documents

2431.TP

2432\f[B]\f[CB]keywords\f[B]\f[R]

2433list of keywords to be included in HTML, PDF, ODT, pptx, docx and

2434AsciiDoc metadata; repeat as for \f[C]author\f[R], above

2435.TP

2436\f[B]\f[CB]subject\f[B]\f[R]

2437document subject, included in ODT, PDF, docx and pptx metadata

2438.TP

2439\f[B]\f[CB]description\f[B]\f[R]

2440document description, included in ODT, docx and pptx metadata.

2441Some applications show this as \f[C]Comments\f[R] metadata.

2442.TP

2443\f[B]\f[CB]category\f[B]\f[R]

2444document category, included in docx and pptx metadata

2445.PP

2446Additionally, any root-level string metadata, not included in ODT, docx

2447or pptx metadata is added as a \f[I]custom property\f[R].

2448The following YAML metadata block for instance:

2449.IP

2450.nf

2451\f[C]

2452---

2453title: \[aq]This is the title\[aq]

2454subtitle: \[dq]This is the subtitle\[dq]

2455author:

2456- Author One

2457- Author Two

2458description: |

2459 This is a long

2460 description.

2461

2462 It consists of two paragraphs

2463\&...

2464\f[R]

2465.fi

2466.PP

2467will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]

2468as standard document properties and \f[C]subtitle\f[R] as a custom

2469property when converting to docx, ODT or pptx.

2470.SS Language variables

2471.TP

2472\f[B]\f[CB]lang\f[B]\f[R]

2473identifies the main language of the document using IETF language tags

2474(following the BCP 47 standard), such as \f[C]en\f[R] or

2475\f[C]en-GB\f[R].

2476The Language subtag lookup tool can look up or verify these tags.

2477This affects most formats, and controls hyphenation in PDF output when

2478using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or

2479ConTeXt.

2480.RS

2481.PP

2482Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to

2483switch the language:

2484.IP

2485.nf

2486\f[C]

2487---

2488lang: en-GB

2489\&...

2490

2491Text in the main document language (British English).

2492

2493::: {lang=fr-CA}

2494> Cette citation est \['e]crite en fran\[,c]ais canadien.

2495:::

2496

2497More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}

2498\f[R]

2499.fi

2500.RE

2501.TP

2502\f[B]\f[CB]dir\f[B]\f[R]

2503the base script direction, either \f[C]rtl\f[R] (right-to-left) or

2504\f[C]ltr\f[R] (left-to-right).

2505.RS

2506.PP

2507For bidirectional documents, native pandoc \f[C]span\f[R]s and

2508\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or

2509\f[C]ltr\f[R]) can be used to override the base direction in some output

2510formats.

2511This may not always be necessary if the final renderer (e.g.\ the

2512browser, when generating HTML) supports the Unicode Bidirectional

2513Algorithm.

2514.PP

2515When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]

2516engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).

2517.RE

2518.SS Variables for HTML

2519.TP

2520\f[B]\f[CB]document-css\f[B]\f[R]

2521Enables inclusion of most of the CSS in the \f[C]styles.html\f[R]

2522partial (have a look with

2523\f[C]pandoc --print-default-data-file=templates/styles.html\f[R]).

2524Unless you use \f[C]--css\f[R], this variable is set to \f[C]true\f[R]

2525by default.

2526You can disable it with e.g.\ \f[C]pandoc -M document-css=false\f[R].

2527.TP

2528\f[B]\f[CB]mainfont\f[B]\f[R]

2529sets the CSS \f[C]font-family\f[R] property on the \f[C]html\f[R]

2530element.

2531.TP

2532\f[B]\f[CB]fontsize\f[B]\f[R]

2533sets the base CSS \f[C]font-size\f[R], which you\[cq]d usually set to

2534e.g.\ \f[C]20px\f[R], but it also accepts \f[C]pt\f[R] (12pt = 16px in

2535most browsers).

2536.TP

2537\f[B]\f[CB]fontcolor\f[B]\f[R]

2538sets the CSS \f[C]color\f[R] property on the \f[C]html\f[R] element.

2539.TP

2540\f[B]\f[CB]linkcolor\f[B]\f[R]

2541sets the CSS \f[C]color\f[R] property on all links.

2542.TP

2543\f[B]\f[CB]monofont\f[B]\f[R]

2544sets the CSS \f[C]font-family\f[R] property on \f[C]code\f[R] elements.

2545.TP

2546\f[B]\f[CB]monobackgroundcolor\f[B]\f[R]

2547sets the CSS \f[C]background-color\f[R] property on \f[C]code\f[R]

2548elements and adds extra padding.

2549.TP

2550\f[B]\f[CB]linestretch\f[B]\f[R]

2551sets the CSS \f[C]line-height\f[R] property on the \f[C]html\f[R]

2552element, which is preferred to be unitless.

2553.TP

2554\f[B]\f[CB]backgroundcolor\f[B]\f[R]

2555sets the CSS \f[C]background-color\f[R] property on the \f[C]html\f[R]

2556element.

2557.TP

2558\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]

2559sets the corresponding CSS \f[C]padding\f[R] properties on the

2560\f[C]body\f[R] element.

2561.PP

2562To override or extend some CSS for just one document, include for

2563example:

2564.IP

2565.nf

2566\f[C]

2567---

2568header-includes: |

2569 <style>

2570 blockquote {

2571 font-style: italic;

2572 }

2573 tr.even {

2574 background-color: #f0f0f0;

2575 }

2576 td, th {

2577 padding: 0.5em 2em 0.5em 0.5em;

2578 }

2579 tbody {

2580 border-bottom: none;

2581 }

2582 </style>

2583---

2584\f[R]

2585.fi

2586.SS Variables for HTML math

2587.TP

2588\f[B]\f[CB]classoption\f[B]\f[R]

2589when using KaTeX, you can render display math equations flush left using

2590YAML metadata or with \f[C]-M classoption=fleqn\f[R].

2591.SS Variables for HTML slides

2592.PP

2593These affect HTML output when [producing slide shows with pandoc].

2594.TP

2595\f[B]\f[CB]institute\f[B]\f[R]

2596author affiliations: can be a list when there are multiple authors

2597.TP

2598\f[B]\f[CB]revealjs-url\f[B]\f[R]

2599base URL for reveal.js documents (defaults to

2600\f[C]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R])

2601.TP

2602\f[B]\f[CB]s5-url\f[B]\f[R]

2603base URL for S5 documents (defaults to \f[C]s5/default\f[R])

2604.TP

2605\f[B]\f[CB]slidy-url\f[B]\f[R]

2606base URL for Slidy documents (defaults to

2607\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])

2608.TP

2609\f[B]\f[CB]slideous-url\f[B]\f[R]

2610base URL for Slideous documents (defaults to \f[C]slideous\f[R])

2611.TP

2612\f[B]\f[CB]title-slide-attributes\f[B]\f[R]

2613additional attributes for the title slide of reveal.js slide shows.

2614See background in reveal.js and beamer for an example.

2615.PP

2616All reveal.js configuration options are available as variables.

2617To turn off boolean flags that default to true in reveal.js, use

2618\f[C]0\f[R].

2619.SS Variables for Beamer slides

2620.PP

2621These variables change the appearance of PDF slides using

2622\f[C]beamer\f[R].

2623.TP

2624\f[B]\f[CB]aspectratio\f[B]\f[R]

2625slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for

262616:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]

2627for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)

2628.TP

2629\f[B]\f[CB]beamerarticle\f[B]\f[R]

2630produce an article from Beamer slides

2631.TP

2632\f[B]\f[CB]beameroption\f[B]\f[R]

2633add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]

2634.TP

2635\f[B]\f[CB]institute\f[B]\f[R]

2636author affiliations: can be a list when there are multiple authors

2637.TP

2638\f[B]\f[CB]logo\f[B]\f[R]

2639logo image for slides

2640.TP

2641\f[B]\f[CB]navigation\f[B]\f[R]

2642controls navigation symbols (default is \f[C]empty\f[R] for no

2643navigation symbols; other valid values are \f[C]frame\f[R],

2644\f[C]vertical\f[R], and \f[C]horizontal\f[R])

2645.TP

2646\f[B]\f[CB]section-titles\f[B]\f[R]

2647enables \[lq]title pages\[rq] for new sections (default is true)

2648.TP

2649\f[B]\f[CB]theme\f[B]\f[R], \f[B]\f[CB]colortheme\f[B]\f[R], \f[B]\f[CB]fonttheme\f[B]\f[R], \f[B]\f[CB]innertheme\f[B]\f[R], \f[B]\f[CB]outertheme\f[B]\f[R]

2650beamer themes

2651.TP

2652\f[B]\f[CB]themeoptions\f[B]\f[R]

2653options for LaTeX beamer themes (a list).

2654.TP

2655\f[B]\f[CB]titlegraphic\f[B]\f[R]

2656image for title slide

2657.SS Variables for PowerPoint

2658.PP

2659These variables control the visual aspects of a slide show that are not

2660easily controlled via templates.

2661.TP

2662\f[B]\f[CB]monofont\f[B]\f[R]

2663font to use for code.

2664.SS Variables for LaTeX

2665.PP

2666Pandoc uses these variables when creating a PDF with a LaTeX engine.

2667.SS Layout

2668.TP

2669\f[B]\f[CB]block-headings\f[B]\f[R]

2670make \f[C]\[rs]paragraph\f[R] and \f[C]\[rs]subparagraph\f[R] (fourth-

2671and fifth-level headings, or fifth- and sixth-level with book classes)

2672free-standing rather than run-in; requires further formatting to

2673distinguish from \f[C]\[rs]subsubsection\f[R] (third- or fourth-level

2674headings).

2675Instead of using this option, KOMA-Script can adjust headings more

2676extensively:

2677.RS

2678.IP

2679.nf

2680\f[C]

2681---

2682documentclass: scrartcl

2683header-includes: |

2684 \[rs]RedeclareSectionCommand[

2685 beforeskip=-10pt plus -2pt minus -1pt,

2686 afterskip=1sp plus -1sp minus 1sp,

2687 font=\[rs]normalfont\[rs]itshape]{paragraph}

2688 \[rs]RedeclareSectionCommand[

2689 beforeskip=-10pt plus -2pt minus -1pt,

2690 afterskip=1sp plus -1sp minus 1sp,

2691 font=\[rs]normalfont\[rs]scshape,

2692 indent=0pt]{subparagraph}

2693\&...

2694\f[R]

2695.fi

2696.RE

2697.TP

2698\f[B]\f[CB]classoption\f[B]\f[R]

2699option for document class, e.g.\ \f[C]oneside\f[R]; repeat for multiple

2700options:

2701.RS

2702.IP

2703.nf

2704\f[C]

2705---

2706classoption:

2707- twocolumn

2708- landscape

2709\&...

2710\f[R]

2711.fi

2712.RE

2713.TP

2714\f[B]\f[CB]documentclass\f[B]\f[R]

2715document class: usually one of the standard classes, \f[C]article\f[R],

2716\f[C]book\f[R], and \f[C]report\f[R]; the KOMA-Script equivalents,

2717\f[C]scrartcl\f[R], \f[C]scrbook\f[R], and \f[C]scrreprt\f[R], which

2718default to smaller margins; or \f[C]memoir\f[R]

2719.TP

2720\f[B]\f[CB]geometry\f[B]\f[R]

2721option for \f[C]geometry\f[R] package, e.g.\ \f[C]margin=1in\f[R];

2722repeat for multiple options:

2723.RS

2724.IP

2725.nf

2726\f[C]

2727---

2728geometry:

2729- top=30mm

2730- left=20mm

2731- heightrounded

2732\&...

2733\f[R]

2734.fi

2735.RE

2736.TP

2737\f[B]\f[CB]hyperrefoptions\f[B]\f[R]

2738option for \f[C]hyperref\f[R] package, e.g.\ \f[C]linktoc=all\f[R];

2739repeat for multiple options:

2740.RS

2741.IP

2742.nf

2743\f[C]

2744---

2745hyperrefoptions:

2746- linktoc=all

2747- pdfwindowui

2748- pdfpagemode=FullScreen

2749\&...

2750\f[R]

2751.fi

2752.RE

2753.TP

2754\f[B]\f[CB]indent\f[B]\f[R]

2755if true, pandoc will use document class settings for indentation (the

2756default LaTeX template otherwise removes indentation and adds space

2757between paragraphs)

2758.TP

2759\f[B]\f[CB]linestretch\f[B]\f[R]

2760adjusts line spacing using the \f[C]setspace\f[R] package,

2761e.g.\ \f[C]1.25\f[R], \f[C]1.5\f[R]

2762.TP

2763\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]

2764sets margins if \f[C]geometry\f[R] is not used (otherwise

2765\f[C]geometry\f[R] overrides these)

2766.TP

2767\f[B]\f[CB]pagestyle\f[B]\f[R]

2768control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports

2769\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page

2770numbers), and \f[C]headings\f[R] (section titles in running heads)

2771.TP

2772\f[B]\f[CB]papersize\f[B]\f[R]

2773paper size, e.g.\ \f[C]letter\f[R], \f[C]a4\f[R]

2774.TP

2775\f[B]\f[CB]secnumdepth\f[B]\f[R]

2776numbering depth for sections (with \f[C]--number-sections\f[R] option or

2777\f[C]numbersections\f[R] variable)

2778.SS Fonts

2779.TP

2780\f[B]\f[CB]fontenc\f[B]\f[R]

2781allows font encoding to be specified through \f[C]fontenc\f[R] package

2782(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font

2783encodings guide)

2784.TP

2785\f[B]\f[CB]fontfamily\f[B]\f[R]

2786font package for use with \f[C]pdflatex\f[R]: TeX Live includes many

2787options, documented in the LaTeX Font Catalogue.

2788The default is Latin Modern.

2789.TP

2790\f[B]\f[CB]fontfamilyoptions\f[B]\f[R]

2791options for package used as \f[C]fontfamily\f[R]; repeat for multiple

2792options.

2793For example, to use the Libertine font with proportional lowercase

2794(old-style) figures through the \f[C]libertinus\f[R] package:

2795.RS

2796.IP

2797.nf

2798\f[C]

2799---

2800fontfamily: libertinus

2801fontfamilyoptions:

2802- osf

2803- p

2804\&...

2805\f[R]

2806.fi

2807.RE

2808.TP

2809\f[B]\f[CB]fontsize\f[B]\f[R]

2810font size for body text.

2811The standard classes allow 10pt, 11pt, and 12pt.

2812To use another size, set \f[C]documentclass\f[R] to one of the

2813KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].

2814.TP

2815\f[B]\f[CB]mainfont\f[B]\f[R], \f[B]\f[CB]sansfont\f[B]\f[R], \f[B]\f[CB]monofont\f[B]\f[R], \f[B]\f[CB]mathfont\f[B]\f[R], \f[B]\f[CB]CJKmainfont\f[B]\f[R]

2816font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take

2817the name of any system font, using the \f[C]fontspec\f[R] package.

2818\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.

2819.TP

2820\f[B]\f[CB]mainfontoptions\f[B]\f[R], \f[B]\f[CB]sansfontoptions\f[B]\f[R], \f[B]\f[CB]monofontoptions\f[B]\f[R], \f[B]\f[CB]mathfontoptions\f[B]\f[R], \f[B]\f[CB]CJKoptions\f[B]\f[R]

2821options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],

2822\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in

2823\f[C]xelatex\f[R] and \f[C]lualatex\f[R].

2824Allow for any choices available through \f[C]fontspec\f[R]; repeat for

2825multiple options.

2826For example, to use the TeX Gyre version of Palatino with lowercase

2827figures:

2828.RS

2829.IP

2830.nf

2831\f[C]

2832---

2833mainfont: TeX Gyre Pagella

2834mainfontoptions:

2835- Numbers=Lowercase

2836- Numbers=Proportional

2837\&...

2838\f[R]

2839.fi

2840.RE

2841.TP

2842\f[B]\f[CB]microtypeoptions\f[B]\f[R]

2843options to pass to the microtype package

2844.SS Links

2845.TP

2846\f[B]\f[CB]colorlinks\f[B]\f[R]

2847add color to link text; automatically enabled if any of

2848\f[C]linkcolor\f[R], \f[C]filecolor\f[R], \f[C]citecolor\f[R],

2849\f[C]urlcolor\f[R], or \f[C]toccolor\f[R] are set

2850.TP

2851\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]filecolor\f[B]\f[R], \f[B]\f[CB]citecolor\f[B]\f[R], \f[B]\f[CB]urlcolor\f[B]\f[R], \f[B]\f[CB]toccolor\f[B]\f[R]

2852color for internal links, external links, citation links, linked URLs,

2853and links in table of contents, respectively: uses options allowed by

2854\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],

2855\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists

2856.TP

2857\f[B]\f[CB]links-as-notes\f[B]\f[R]

2858causes links to be printed as footnotes

2859.SS Front matter

2860.TP

2861\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]

2862include list of figures, list of tables

2863.TP

2864\f[B]\f[CB]thanks\f[B]\f[R]

2865contents of acknowledgments footnote after document title

2866.TP

2867\f[B]\f[CB]toc\f[B]\f[R]

2868include table of contents (can also be set using

2869\f[C]--toc/--table-of-contents\f[R])

2870.TP

2871\f[B]\f[CB]toc-depth\f[B]\f[R]

2872level of section to include in table of contents

2873.SS BibLaTeX Bibliographies

2874.PP

2875These variables function when using BibLaTeX for citation rendering.

2876.TP

2877\f[B]\f[CB]biblatexoptions\f[B]\f[R]

2878list of options for biblatex

2879.TP

2880\f[B]\f[CB]biblio-style\f[B]\f[R]

2881bibliography style, when used with \f[C]--natbib\f[R] and

2882\f[C]--biblatex\f[R].

2883.TP

2884\f[B]\f[CB]biblio-title\f[B]\f[R]

2885bibliography title, when used with \f[C]--natbib\f[R] and

2886\f[C]--biblatex\f[R].

2887.TP

2888\f[B]\f[CB]bibliography\f[B]\f[R]

2889bibliography to use for resolving references

2890.TP

2891\f[B]\f[CB]natbiboptions\f[B]\f[R]

2892list of options for natbib

2893.SS Variables for ConTeXt

2894.PP

2895Pandoc uses these variables when creating a PDF with ConTeXt.

2896.TP

2897\f[B]\f[CB]fontsize\f[B]\f[R]

2898font size for body text (e.g.\ \f[C]10pt\f[R], \f[C]12pt\f[R])

2899.TP

2900\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]

2901text to be placed in running header or footer (see ConTeXt Headers and

2902Footers); repeat up to four times for different placement

2903.TP

2904\f[B]\f[CB]indenting\f[B]\f[R]

2905controls indentation of paragraphs, e.g.\ \f[C]yes,small,next\f[R] (see

2906ConTeXt Indentation); repeat for multiple options

2907.TP

2908\f[B]\f[CB]interlinespace\f[B]\f[R]

2909adjusts line spacing, e.g.\ \f[C]4ex\f[R] (using

2910\f[C]setupinterlinespace\f[R]); repeat for multiple options

2911.TP

2912\f[B]\f[CB]layout\f[B]\f[R]

2913options for page margins and text arrangement (see ConTeXt Layout);

2914repeat for multiple options

2915.TP

2916\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]

2917color for links outside and inside a page, e.g.\ \f[C]red\f[R],

2918\f[C]blue\f[R] (see ConTeXt Color)

2919.TP

2920\f[B]\f[CB]linkstyle\f[B]\f[R]

2921typeface style for links, e.g.\ \f[C]normal\f[R], \f[C]bold\f[R],

2922\f[C]slanted\f[R], \f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R],

2923\f[C]small\f[R]

2924.TP

2925\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]

2926include list of figures, list of tables

2927.TP

2928\f[B]\f[CB]mainfont\f[B]\f[R], \f[B]\f[CB]sansfont\f[B]\f[R], \f[B]\f[CB]monofont\f[B]\f[R], \f[B]\f[CB]mathfont\f[B]\f[R]

2929font families: take the name of any system font (see ConTeXt Font

2930Switching)

2931.TP

2932\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]

2933sets margins, if \f[C]layout\f[R] is not used (otherwise

2934\f[C]layout\f[R] overrides these)

2935.TP

2936\f[B]\f[CB]pagenumbering\f[B]\f[R]

2937page number style and location (using \f[C]setuppagenumbering\f[R]);

2938repeat for multiple options

2939.TP

2940\f[B]\f[CB]papersize\f[B]\f[R]

2941paper size, e.g.\ \f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R]

2942(see ConTeXt Paper Setup); repeat for multiple options

2943.TP

2944\f[B]\f[CB]pdfa\f[B]\f[R]

2945adds to the preamble the setup necessary to generate PDF/A of the type

2946specified, e.g.\ \f[C]1a:2005\f[R], \f[C]2a\f[R].

2947If no type is specified (i.e.\ the value is set to True, by e.g.

2948\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata

2949block), \f[C]1b:2005\f[R] will be used as default, for reasons of

2950backwards compatibility.

2951Using \f[C]--variable=pdfa\f[R] without specified value is not

2952supported.

2953To successfully generate PDF/A the required ICC color profiles have to

2954be available and the content and all included files (such as images)

2955have to be standard conforming.

2956The ICC profiles and output intent may be specified using the variables

2957\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].

2958See also ConTeXt PDFA for more details.

2959.TP

2960\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]

2961when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile

2962to use in the PDF, e.g.\ \f[C]default.cmyk\f[R].

2963If left unspecified, \f[C]sRGB.icc\f[R] is used as default.

2964May be repeated to include multiple profiles.

2965Note that the profiles have to be available on the system.

2966They can be obtained from ConTeXt ICC Profiles.

2967.TP

2968\f[B]\f[CB]pdfaintent\f[B]\f[R]

2969when used in conjunction with \f[C]pdfa\f[R], specifies the output

2970intent for the colors,

2971e.g.\ \f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If

2972left unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.

2973.TP

2974\f[B]\f[CB]toc\f[B]\f[R]

2975include table of contents (can also be set using

2976\f[C]--toc/--table-of-contents\f[R])

2977.TP

2978\f[B]\f[CB]whitespace\f[B]\f[R]

2979spacing between paragraphs, e.g.\ \f[C]none\f[R], \f[C]small\f[R] (using

2980\f[C]setupwhitespace\f[R])

2981.TP

2982\f[B]\f[CB]includesource\f[B]\f[R]

2983include all source documents as file attachments in the PDF file

2984.SS Variables for \f[C]wkhtmltopdf\f[R]

2985.PP

2986Pandoc uses these variables when creating a PDF with

2987\f[C]wkhtmltopdf\f[R].

2988The \f[C]--css\f[R] option also affects the output.

2989.TP

2990\f[B]\f[CB]footer-html\f[B]\f[R], \f[B]\f[CB]header-html\f[B]\f[R]

2991add information to the header and footer

2992.TP

2993\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]

2994set the page margins

2995.TP

2996\f[B]\f[CB]papersize\f[B]\f[R]

2997sets the PDF paper size

2998.SS Variables for man pages

2999.TP

3000\f[B]\f[CB]adjusting\f[B]\f[R]

3001adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center

3002(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins

3003.TP

3004\f[B]\f[CB]footer\f[B]\f[R]

3005footer in man pages

3006.TP

3007\f[B]\f[CB]header\f[B]\f[R]

3008header in man pages

3009.TP

3010\f[B]\f[CB]hyphenate\f[B]\f[R]

3011if \f[C]true\f[R] (the default), hyphenation will be used

3012.TP

3013\f[B]\f[CB]section\f[B]\f[R]

3014section number in man pages

3015.SS Variables for ms

3016.TP

3017\f[B]\f[CB]fontfamily\f[B]\f[R]

3018font family (e.g.\ \f[C]T\f[R] or \f[C]P\f[R])

3019.TP

3020\f[B]\f[CB]indent\f[B]\f[R]

3021paragraph indent (e.g.\ \f[C]2m\f[R])

3022.TP

3023\f[B]\f[CB]lineheight\f[B]\f[R]

3024line height (e.g.\ \f[C]12p\f[R])

3025.TP

3026\f[B]\f[CB]pointsize\f[B]\f[R]

3027point size (e.g.\ \f[C]10p\f[R])

3028.SS Variables set automatically

3029.PP

3030Pandoc sets these variables automatically in response to options or

3031document contents; users can also modify them.

3032These vary depending on the output format, and include the following:

3033.TP

3034\f[B]\f[CB]body\f[B]\f[R]

3035body of document

3036.TP

3037\f[B]\f[CB]date-meta\f[B]\f[R]

3038the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included

3039in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,

3040s5, slideous, slidy).

3041The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],

3042\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),

3043\f[C]dd MM yyyy\f[R] (e.g.\ either \f[C]02 Apr 2018\f[R] or

3044\f[C]02 April 2018\f[R]), \f[C]MM dd, yyyy\f[R]

3045(e.g.\ \f[C]Apr. 02, 2018\f[R] or

3046\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,

3047\f[C]201804\f[R] or \f[C]2018\f[R]).

3048.TP

3049\f[B]\f[CB]header-includes\f[B]\f[R]

3050contents specified by \f[C]-H/--include-in-header\f[R] (may have

3051multiple values)

3052.TP

3053\f[B]\f[CB]include-before\f[B]\f[R]

3054contents specified by \f[C]-B/--include-before-body\f[R] (may have

3055multiple values)

3056.TP

3057\f[B]\f[CB]include-after\f[B]\f[R]

3058contents specified by \f[C]-A/--include-after-body\f[R] (may have

3059multiple values)

3060.TP

3061\f[B]\f[CB]meta-json\f[B]\f[R]

3062JSON representation of all of the document\[cq]s metadata.

3063Field values are transformed to the selected output format.

3064.TP

3065\f[B]\f[CB]numbersections\f[B]\f[R]

3066non-null value if \f[C]-N/--number-sections\f[R] was specified

3067.TP

3068\f[B]\f[CB]sourcefile\f[B]\f[R], \f[B]\f[CB]outputfile\f[B]\f[R]

3069source and destination filenames, as given on the command line.

3070\f[C]sourcefile\f[R] can also be a list if input comes from multiple

3071files, or empty if input is from stdin.

3072You can use the following snippet in your template to distinguish them:

3073.RS

3074.IP

3075.nf

3076\f[C]

3077$if(sourcefile)$

3078$for(sourcefile)$

3079$sourcefile$

3080$endfor$

3081$else$

3082(stdin)

3083$endif$

3084\f[R]

3085.fi

3086.PP

3087Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the

3088terminal.

3089.PP

3090If you need absolute paths, use e.g.\ \f[C]$curdir$/$sourcefile$\f[R].

3091.RE

3092.TP

3093\f[B]\f[CB]curdir\f[B]\f[R]

3094working directory from which pandoc is run.

3095.TP

3096\f[B]\f[CB]toc\f[B]\f[R]

3097non-null value if \f[C]--toc/--table-of-contents\f[R] was specified

3098.TP

3099\f[B]\f[CB]toc-title\f[B]\f[R]

3100title of table of contents (works only with EPUB, HTML, opendocument,

3101odt, docx, pptx, beamer, LaTeX)

3102.SH EXTENSIONS

3103.PP

3104The behavior of some of the readers and writers can be adjusted by

3105enabling or disabling various extensions.

3106.PP

3107An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format

3108name and disabled by adding \f[C]-EXTENSION\f[R].

3109For example, \f[C]--from markdown_strict+footnotes\f[R] is strict

3110Markdown with footnotes enabled, while

3111\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s Markdown

3112without footnotes or pipe tables.

3113.PP

3114The markdown reader and writer make by far the most use of extensions.

3115Extensions only used by them are therefore covered in the section

3116Pandoc\[cq]s Markdown below (See Markdown variants for

3117\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions

3118that also work for other formats are covered.

3119.PP

3120Note that markdown extensions added to the \f[C]ipynb\f[R] format affect

3121Markdown cells in Jupyter notebooks (as do command-line options like

3122\f[C]--atx-headers\f[R]).

3123.SS Typography

3124.SS Extension: \f[C]smart\f[R]

3125.PP

3126Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,

3127\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.

3128Nonbreaking spaces are inserted after certain abbreviations, such as

3129\[lq]Mr.\[rq]

3130.PP

3131This extension can be enabled/disabled for the following formats:

3132.TP

3133input formats

3134\f[C]markdown\f[R], \f[C]commonmark\f[R], \f[C]latex\f[R],

3135\f[C]mediawiki\f[R], \f[C]org\f[R], \f[C]rst\f[R], \f[C]twiki\f[R]

3136.TP

3137output formats

3138\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R], \f[C]rst\f[R]

3139.TP

3140enabled by default in

3141\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R] (both input and

3142output)

3143.PP

3144Note: If you are \f[I]writing\f[R] Markdown, then the \f[C]smart\f[R]

3145extension has the reverse effect: what would have been curly quotes

3146comes out straight.

3147.PP

3148In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for

3149quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for

3150double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)

3151and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).

3152If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse

3153these characters literally.

3154In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the

3155ligatures when possible; if \f[C]smart\f[R] is disabled pandoc will use

3156unicode quotation mark and dash characters.

3157.SS Headings and sections

3158.SS Extension: \f[C]auto_identifiers\f[R]

3159.PP

3160A heading without an explicitly specified identifier will be

3161automatically assigned a unique identifier based on the heading text.

3162.PP

3163This extension can be enabled/disabled for the following formats:

3164.TP

3165input formats

3166\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]rst\f[R], \f[C]mediawiki\f[R],

3167\f[C]textile\f[R]

3168.TP

3169output formats

3170\f[C]markdown\f[R], \f[C]muse\f[R]

3171.TP

3172enabled by default in

3173\f[C]markdown\f[R], \f[C]muse\f[R]

3174.PP

3175The default algorithm used to derive the identifier from the heading

3176text is:

3177.IP \[bu] 2

3178Remove all formatting, links, etc.

3179.IP \[bu] 2

3180Remove all footnotes.

3181.IP \[bu] 2

3182Remove all non-alphanumeric characters, except underscores, hyphens, and

3183periods.

3184.IP \[bu] 2

3185Replace all spaces and newlines with hyphens.

3186.IP \[bu] 2

3187Convert all alphabetic characters to lowercase.

3188.IP \[bu] 2

3189Remove everything up to the first letter (identifiers may not begin with

3190a number or punctuation mark).

3191.IP \[bu] 2

3192If nothing is left after this, use the identifier \f[C]section\f[R].

3193.PP

3194Thus, for example,

3195.PP

3196.TS

3197tab(@);

3198l l.

3199T{

3200Heading

3201T}@T{

3202Identifier

3203T}

3204_

3205T{

3206\f[C]Heading identifiers in HTML\f[R]

3207T}@T{

3208\f[C]heading-identifiers-in-html\f[R]

3209T}

3210T{

3211\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]

3212T}@T{

3213\f[C]ma\[^i]tre-dh\[^o]tel\f[R]

3214T}

3215T{

3216\f[C]*Dogs*?--in *my* house?\f[R]

3217T}@T{

3218\f[C]dogs--in-my-house\f[R]

3219T}

3220T{

3221\f[C][HTML], [S5], or [RTF]?\f[R]

3222T}@T{

3223\f[C]html-s5-or-rtf\f[R]

3224T}

3225T{

3226\f[C]3. Applications\f[R]

3227T}@T{

3228\f[C]applications\f[R]

3229T}

3230T{

3231\f[C]33\f[R]

3232T}@T{

3233\f[C]section\f[R]

3234T}

3235.TE

3236.PP

3237These rules should, in most cases, allow one to determine the identifier

3238from the heading text.

3239The exception is when several headings have the same text; in this case,

3240the first will get an identifier as described above; the second will get

3241the same identifier with \f[C]-1\f[R] appended; the third with

3242\f[C]-2\f[R]; and so on.

3243.PP

3244(However, a different algorithm is used if

3245\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)

3246.PP

3247These identifiers are used to provide link targets in the table of

3248contents generated by the \f[C]--toc|--table-of-contents\f[R] option.

3249They also make it easy to provide links from one section of a document

3250to another.

3251A link to this section, for example, might look like this:

3252.IP

3253.nf

3254\f[C]

3255See the section on

3256[heading identifiers](#heading-identifiers-in-html-latex-and-context).

3257\f[R]

3258.fi

3259.PP

3260Note, however, that this method of providing links to sections works

3261only in HTML, LaTeX, and ConTeXt formats.

3262.PP

3263If the \f[C]--section-divs\f[R] option is specified, then each section

3264will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if

3265\f[C]html4\f[R] was specified), and the identifier will be attached to

3266the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than

3267the heading itself.

3268This allows entire sections to be manipulated using JavaScript or

3269treated differently in CSS.

3270.SS Extension: \f[C]ascii_identifiers\f[R]

3271.PP

3272Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure

3273ASCII.

3274Accents are stripped off of accented Latin letters, and non-Latin

3275letters are omitted.

3276.SS Extension: \f[C]gfm_auto_identifiers\f[R]

3277.PP

3278Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to

3279GitHub\[cq]s method.

3280Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to

3281lowercase characters, and punctuation characters other than \f[C]-\f[R]

3282and \f[C]_\f[R] are removed.

3283Emojis are replaced by their names.

3284.SS Math Input

3285.PP

3286The extensions \f[C]tex_math_dollars\f[R],

3287\f[C]tex_math_single_backslash\f[R], and

3288\f[C]tex_math_double_backslash\f[R] are described in the section about

3289Pandoc\[cq]s Markdown.

3290.PP

3291However, they can also be used with HTML input.

3292This is handy for reading web pages formatted using MathJax, for

3293example.

3294.SS Raw HTML/TeX

3295.PP

3296The following extensions are described in more detail in their

3297respective sections of Pandoc\[cq]s Markdown:

3298.IP \[bu] 2

3299\f[C]raw_html\f[R] allows HTML elements which are not representable in

3300pandoc\[cq]s AST to be parsed as raw HTML.

3301By default, this is disabled for HTML input.

3302.IP \[bu] 2

3303\f[C]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a

3304document.

3305This extension can be enabled/disabled for the following formats (in

3306addition to \f[C]markdown\f[R]):

3307.RS 2

3308.TP

3309input formats

3310\f[C]latex\f[R], \f[C]textile\f[R], \f[C]html\f[R] (environments,

3311\f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only), \f[C]ipynb\f[R]

3312.TP

3313output formats

3314\f[C]textile\f[R], \f[C]commonmark\f[R]

3315.PP

3316Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and

3317\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data

3318with mime type \f[C]text/html\f[R] in output cells.

3319Since the \f[C]ipynb\f[R] reader attempts to preserve the richest

3320possible outputs when several options are given, you will get best

3321results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when

3322converting to formats like \f[C]docx\f[R] which don\[cq]t allow raw

3323\f[C]html\f[R] or \f[C]tex\f[R].

3324.RE

3325.IP \[bu] 2

3326\f[C]native_divs\f[R] causes HTML \f[C]div\f[R] elements to be parsed as

3327native pandoc Div blocks.

3328If you want them to be parsed as raw HTML, use

3329\f[C]-f html-native_divs+raw_html\f[R].

3330.IP \[bu] 2

3331\f[C]native_spans\f[R] causes HTML \f[C]span\f[R] elements to be parsed

3332as native pandoc Span inlines.

3333If you want them to be parsed as raw HTML, use

3334\f[C]-f html-native_spans+raw_html\f[R].

3335If you want to drop all \f[C]div\f[R]s and \f[C]span\f[R]s when

3336converting HTML to Markdown, you can use

3337\f[C]pandoc -f html-native_divs-native_spans -t markdown\f[R].

3338.SS Literate Haskell support

3339.SS Extension: \f[C]literate_haskell\f[R]

3340.PP

3341Treat the document as literate Haskell source.

3342.PP

3343This extension can be enabled/disabled for the following formats:

3344.TP

3345input formats

3346\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R]

3347.TP

3348output formats

3349\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R], \f[C]html\f[R]

3350.PP

3351If you append \f[C]+lhs\f[R] (or \f[C]+literate_haskell\f[R]) to one of

3352the formats above, pandoc will treat the document as literate Haskell

3353source.

3354This means that

3355.IP \[bu] 2

3356In Markdown input, \[lq]bird track\[rq] sections will be parsed as

3357Haskell code rather than block quotations.

3358Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]

3359will also be treated as Haskell code.

3360For ATX-style headings the character `=' will be used instead of `#'.

3361.IP \[bu] 2

3362In Markdown output, code blocks with classes \f[C]haskell\f[R] and

3363\f[C]literate\f[R] will be rendered using bird tracks, and block

3364quotations will be indented one space, so they will not be treated as

3365Haskell code.

3366In addition, headings will be rendered setext-style (with underlines)

3367rather than ATX-style (with `#' characters).

3368(This is because ghc treats `#' characters in column 1 as introducing

3369line numbers.)

3370.IP \[bu] 2

3371In restructured text input, \[lq]bird track\[rq] sections will be parsed

3372as Haskell code.

3373.IP \[bu] 2

3374In restructured text output, code blocks with class \f[C]haskell\f[R]

3375will be rendered using bird tracks.

3376.IP \[bu] 2

3377In LaTeX input, text in \f[C]code\f[R] environments will be parsed as

3378Haskell code.

3379.IP \[bu] 2

3380In LaTeX output, code blocks with class \f[C]haskell\f[R] will be

3381rendered inside \f[C]code\f[R] environments.

3382.IP \[bu] 2

3383In HTML output, code blocks with class \f[C]haskell\f[R] will be

3384rendered with class \f[C]literatehaskell\f[R] and bird tracks.

3385.PP

3386Examples:

3387.IP

3388.nf

3389\f[C]

3390pandoc -f markdown+lhs -t html

3391\f[R]

3392.fi

3393.PP

3394reads literate Haskell source formatted with Markdown conventions and

3395writes ordinary HTML (without bird tracks).

3396.IP

3397.nf

3398\f[C]

3399pandoc -f markdown+lhs -t html+lhs

3400\f[R]

3401.fi

3402.PP

3403writes HTML with the Haskell code in bird tracks, so it can be copied

3404and pasted as literate Haskell source.

3405.PP

3406Note that GHC expects the bird tracks in the first column, so indented

3407literate code blocks (e.g.\ inside an itemized environment) will not be

3408picked up by the Haskell compiler.

3409.SS Other extensions

3410.SS Extension: \f[C]empty_paragraphs\f[R]

3411.PP

3412Allows empty paragraphs.

3413By default empty paragraphs are omitted.

3414.PP

3415This extension can be enabled/disabled for the following formats:

3416.TP

3417input formats

3418\f[C]docx\f[R], \f[C]html\f[R]

3419.TP

3420output formats

3421\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]

3422.SS Extension: \f[C]native_numbering\f[R]

3423.PP

3424Enables native numbering of figures and tables.

3425Enumeration starts at 1.

3426.PP

3427This extension can be enabled/disabled for the following formats:

3428.TP

3429output formats

3430\f[C]odt\f[R], \f[C]opendocument\f[R]

3431.SS Extension: \f[C]xrefs_name\f[R]

3432.PP

3433Links to headings, figures and tables inside the document are

3434substituted with cross-references that will use the name or caption of

3435the referenced item.

3436The original link text is replaced once the generated document is

3437refreshed.

3438This extension can be combined with \f[C]xrefs_number\f[R] in which case

3439numbers will appear before the name.

3440.PP

3441Text in cross-references is only made consistent with the referenced

3442item once the document has been refreshed.

3443.PP

3444This extension can be enabled/disabled for the following formats:

3445.TP

3446output formats

3447\f[C]odt\f[R], \f[C]opendocument\f[R]

3448.SS Extension: \f[C]xrefs_number\f[R]

3449.PP

3450Links to headings, figures and tables inside the document are

3451substituted with cross-references that will use the number of the

3452referenced item.

3453The original link text is discarded.

3454This extension can be combined with \f[C]xrefs_name\f[R] in which case

3455the name or caption numbers will appear after the number.

3456.PP

3457For the \f[C]xrefs_number\f[R] to be useful heading numbers must be

3458enabled in the generated document, also table and figure captions must

3459be enabled using for example the \f[C]native_numbering\f[R] extension.

3460.PP

3461Numbers in cross-references are only visible in the final document once

3462it has been refreshed.

3463.PP

3464This extension can be enabled/disabled for the following formats:

3465.TP

3466output formats

3467\f[C]odt\f[R], \f[C]opendocument\f[R]

3468.SS Extension: \f[C]styles\f[R]

3469.PP

3470When converting from docx, read all docx styles as divs (for paragraph

3471styles) and spans (for character styles) regardless of whether pandoc

3472understands the meaning of these styles.

3473This can be used with docx custom styles.

3474Disabled by default.

3475.TP

3476input formats

3477\f[C]docx\f[R]

3478.SS Extension: \f[C]amuse\f[R]

3479.PP

3480In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions

3481to Emacs Muse markup.

3482.SS Extension: \f[C]raw_markdown\f[R]

3483.PP

3484In the \f[C]ipynb\f[R] input format, this causes Markdown cells to be

3485included as raw Markdown blocks (allowing lossless round-tripping)

3486rather than being parsed.

3487Use this only when you are targeting \f[C]ipynb\f[R] or a markdown-based

3488output format.

3489.SS Extension: \f[C]citations\f[R]

3490.PP

3491Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted

3492in \f[C]org\f[R] input.

3493.SS Extension: \f[C]element_citations\f[R]

3494.PP

3495In the \f[C]jats\f[R] output formats, this causes reference items to be

3496replaced with \f[C]<element-citation>\f[R] elements.

3497These elements are not influenced by CSL styles, but all information on

3498the item is included in tags.

3499.SS Extension: \f[C]ntb\f[R]

3500.PP

3501In the \f[C]context\f[R] output format this enables the use of Natural

3502Tables (TABLE) instead of the default Extreme Tables (xtables).

3503Natural tables allow more fine-grained global customization but come at

3504a performance penalty compared to extreme tables.

3505.SH PANDOC\[cq]S MARKDOWN

3506.PP

3507Pandoc understands an extended and slightly revised version of John

3508Gruber\[cq]s Markdown syntax.

3509This document explains the syntax, noting differences from standard

3510Markdown.

3511Except where noted, these differences can be suppressed by using the

3512\f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R].

3513Extensions can be enabled or disabled to specify the behavior more

3514granularly.

3515They are described in the following.

3516See also Extensions above, for extensions that work also on other

3517formats.

3518.SS Philosophy

3519.PP

3520Markdown is designed to be easy to write, and, even more importantly,

3521easy to read:

3522.RS

3523.PP

3524A Markdown-formatted document should be publishable as-is, as plain

3525text, without looking like it\[cq]s been marked up with tags or

3526formatting instructions.

3527\[en] John Gruber

3528.RE

3529.PP

3530This principle has guided pandoc\[cq]s decisions in finding syntax for

3531tables, footnotes, and other extensions.

3532.PP

3533There is, however, one respect in which pandoc\[cq]s aims are different

3534from the original aims of Markdown.

3535Whereas Markdown was originally designed with HTML generation in mind,

3536pandoc is designed for multiple output formats.

3537Thus, while pandoc allows the embedding of raw HTML, it discourages it,

3538and provides other, non-HTMLish ways of representing important document

3539elements like definition lists, tables, mathematics, and footnotes.

3540.SS Paragraphs

3541.PP

3542A paragraph is one or more lines of text followed by one or more blank

3543lines.

3544Newlines are treated as spaces, so you can reflow your paragraphs as you

3545like.

3546If you need a hard line break, put two or more spaces at the end of a

3547line.

3548.SS Extension: \f[C]escaped_line_breaks\f[R]

3549.PP

3550A backslash followed by a newline is also a hard line break.

3551Note: in multiline and grid table cells, this is the only way to create

3552a hard line break, since trailing spaces in the cells are ignored.

3553.SS Headings

3554.PP

3555There are two kinds of headings: Setext and ATX.

3556.SS Setext-style headings

3557.PP

3558A setext-style heading is a line of text \[lq]underlined\[rq] with a row

3559of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for

3560a level-two heading):

3561.IP

3562.nf

3563\f[C]

3564A level-one heading

3565===================

3566

3567A level-two heading

3568-------------------

3569\f[R]

3570.fi

3571.PP

3572The heading text can contain inline formatting, such as emphasis (see

3573Inline formatting, below).

3574.SS ATX-style headings

3575.PP

3576An ATX-style heading consists of one to six \f[C]#\f[R] signs and a line

3577of text, optionally followed by any number of \f[C]#\f[R] signs.

3578The number of \f[C]#\f[R] signs at the beginning of the line is the

3579heading level:

3580.IP

3581.nf

3582\f[C]

3583## A level-two heading

3584

3585### A level-three heading ###

3586\f[R]

3587.fi

3588.PP

3589As with setext-style headings, the heading text can contain formatting:

3590.IP

3591.nf

3592\f[C]

3593# A level-one heading with a [link](/url) and *emphasis*

3594\f[R]

3595.fi

3596.SS Extension: \f[C]blank_before_header\f[R]

3597.PP

3598Standard Markdown syntax does not require a blank line before a heading.

3599Pandoc does require this (except, of course, at the beginning of the

3600document).

3601The reason for the requirement is that it is all too easy for a

3602\f[C]#\f[R] to end up at the beginning of a line by accident (perhaps

3603through line wrapping).

3604Consider, for example:

3605.IP

3606.nf

3607\f[C]

3608I like several of their flavors of ice cream:

3609#22, for example, and #5.

3610\f[R]

3611.fi

3612.SS Extension: \f[C]space_in_atx_header\f[R]

3613.PP

3614Many Markdown implementations do not require a space between the opening

3615\f[C]#\f[R]s of an ATX heading and the heading text, so that

3616\f[C]#5 bolt\f[R] and \f[C]#hashtag\f[R] count as headings.

3617With this extension, pandoc does require the space.

3618.SS Heading identifiers

3619.PP

3620See also the \f[C]auto_identifiers\f[R] extension above.

3621.SS Extension: \f[C]header_attributes\f[R]

3622.PP

3623Headings can be assigned attributes using this syntax at the end of the

3624line containing the heading text:

3625.IP

3626.nf

3627\f[C]

3628{#identifier .class .class key=value key=value}

3629\f[R]

3630.fi

3631.PP

3632Thus, for example, the following headings will all be assigned the

3633identifier \f[C]foo\f[R]:

3634.IP

3635.nf

3636\f[C]

3637# My heading {#foo}

3638

3639## My heading ## {#foo}

3640

3641My other heading {#foo}

3642---------------

3643\f[R]

3644.fi

3645.PP

3646(This syntax is compatible with PHP Markdown Extra.)

3647.PP

3648Note that although this syntax allows assignment of classes and

3649key/value attributes, writers generally don\[cq]t use all of this

3650information.

3651Identifiers, classes, and key/value attributes are used in HTML and

3652HTML-based formats such as EPUB and slidy.

3653Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,

3654Textile, Jira markup, and AsciiDoc writers.

3655.PP

3656Headings with the class \f[C]unnumbered\f[R] will not be numbered, even

3657if \f[C]--number-sections\f[R] is specified.

3658A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to

3659\f[C].unnumbered\f[R], and preferable in non-English documents.

3660So,

3661.IP

3662.nf

3663\f[C]

3664# My heading {-}

3665\f[R]

3666.fi

3667.PP

3668is just the same as

3669.IP

3670.nf

3671\f[C]

3672# My heading {.unnumbered}

3673\f[R]

3674.fi

3675.PP

3676If the \f[C]unlisted\f[R] class is present in addition to

3677\f[C]unnumbered\f[R], the heading will not be included in a table of

3678contents.

3679(Currently this feature is only implemented for certain formats: those

3680based on LaTeX and HTML, PowerPoint, and RTF.)

3681.SS Extension: \f[C]implicit_header_references\f[R]

3682.PP

3683Pandoc behaves as if reference links have been defined for each heading.

3684So, to link to a heading

3685.IP

3686.nf

3687\f[C]

3688# Heading identifiers in HTML

3689\f[R]

3690.fi

3691.PP

3692you can simply write

3693.IP

3694.nf

3695\f[C]

3696[Heading identifiers in HTML]

3697\f[R]

3698.fi

3699.PP

3700or

3701.IP

3702.nf

3703\f[C]

3704[Heading identifiers in HTML][]

3705\f[R]

3706.fi

3707.PP

3708or

3709.IP

3710.nf

3711\f[C]

3712[the section on heading identifiers][heading identifiers in

3713HTML]

3714\f[R]

3715.fi

3716.PP

3717instead of giving the identifier explicitly:

3718.IP

3719.nf

3720\f[C]

3721[Heading identifiers in HTML](#heading-identifiers-in-html)

3722\f[R]

3723.fi

3724.PP

3725If there are multiple headings with identical text, the corresponding

3726reference will link to the first one only, and you will need to use

3727explicit links to link to the others, as described above.

3728.PP

3729Like regular reference links, these references are case-insensitive.

3730.PP

3731Explicit link reference definitions always take priority over implicit

3732heading references.

3733So, in the following example, the link will point to \f[C]bar\f[R], not

3734to \f[C]#foo\f[R]:

3735.IP

3736.nf

3737\f[C]

3738# Foo

3739

3740[foo]: bar

3741

3742See [foo]

3743\f[R]

3744.fi

3745.SS Block quotations

3746.PP

3747Markdown uses email conventions for quoting blocks of text.

3748A block quotation is one or more paragraphs or other block elements

3749(such as lists or headings), with each line preceded by a \f[C]>\f[R]

3750character and an optional space.

3751(The \f[C]>\f[R] need not start at the left margin, but it should not be

3752indented more than three spaces.)

3753.IP

3754.nf

3755\f[C]

3756> This is a block quote. This

3757> paragraph has two lines.

3758>

3759> 1. This is a list inside a block quote.

3760> 2. Second item.

3761\f[R]

3762.fi

3763.PP

3764A \[lq]lazy\[rq] form, which requires the \f[C]>\f[R] character only on

3765the first line of each block, is also allowed:

3766.IP

3767.nf

3768\f[C]

3769> This is a block quote. This

3770paragraph has two lines.

3771

3772> 1. This is a list inside a block quote.

37732. Second item.

3774\f[R]

3775.fi

3776.PP

3777Among the block elements that can be contained in a block quote are

3778other block quotes.

3779That is, block quotes can be nested:

3780.IP

3781.nf

3782\f[C]

3783> This is a block quote.

3784>

3785> > A block quote within a block quote.

3786\f[R]

3787.fi

3788.PP

3789If the \f[C]>\f[R] character is followed by an optional space, that

3790space will be considered part of the block quote marker and not part of

3791the indentation of the contents.

3792Thus, to put an indented code block in a block quote, you need five

3793spaces after the \f[C]>\f[R]:

3794.IP

3795.nf

3796\f[C]

3797> code

3798\f[R]

3799.fi

3800.SS Extension: \f[C]blank_before_blockquote\f[R]

3801.PP

3802Standard Markdown syntax does not require a blank line before a block

3803quote.

3804Pandoc does require this (except, of course, at the beginning of the

3805document).

3806The reason for the requirement is that it is all too easy for a

3807\f[C]>\f[R] to end up at the beginning of a line by accident (perhaps

3808through line wrapping).

3809So, unless the \f[C]markdown_strict\f[R] format is used, the following

3810does not produce a nested block quote in pandoc:

3811.IP

3812.nf

3813\f[C]

3814> This is a block quote.

3815>> Nested.

3816\f[R]

3817.fi

3818.SS Verbatim (code) blocks

3819.SS Indented code blocks

3820.PP

3821A block of text indented four spaces (or one tab) is treated as verbatim

3822text: that is, special characters do not trigger special formatting, and

3823all spaces and line breaks are preserved.

3824For example,

3825.IP

3826.nf

3827\f[C]

3828 if (a > 3) {

3829 moveShip(5 * gravity, DOWN);

3830 }

3831\f[R]

3832.fi

3833.PP

3834The initial (four space or one tab) indentation is not considered part

3835of the verbatim text, and is removed in the output.

3836.PP

3837Note: blank lines in the verbatim text need not begin with four spaces.

3838.SS Fenced code blocks

3839.SS Extension: \f[C]fenced_code_blocks\f[R]

3840.PP

3841In addition to standard indented code blocks, pandoc supports

3842\f[I]fenced\f[R] code blocks.

3843These begin with a row of three or more tildes (\f[C]\[ti]\f[R]) and end

3844with a row of tildes that must be at least as long as the starting row.

3845Everything between these lines is treated as code.

3846No indentation is necessary:

3847.IP

3848.nf

3849\f[C]

3850\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3851if (a > 3) {

3852 moveShip(5 * gravity, DOWN);

3853}

3854\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3855\f[R]

3856.fi

3857.PP

3858Like regular code blocks, fenced code blocks must be separated from

3859surrounding text by blank lines.

3860.PP

3861If the code itself contains a row of tildes or backticks, just use a

3862longer row of tildes or backticks at the start and end:

3863.IP

3864.nf

3865\f[C]

3866\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3867\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3868code including tildes

3869\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3870\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3871\f[R]

3872.fi

3873.SS Extension: \f[C]backtick_code_blocks\f[R]

3874.PP

3875Same as \f[C]fenced_code_blocks\f[R], but uses backticks

3876(\f[C]\[ga]\f[R]) instead of tildes (\f[C]\[ti]\f[R]).

3877.SS Extension: \f[C]fenced_code_attributes\f[R]

3878.PP

3879Optionally, you may attach attributes to fenced or backtick code block

3880using this syntax:

3881.IP

3882.nf

3883\f[C]

3884\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}

3885qsort [] = []

3886qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++

3887 qsort (filter (>= x) xs)

3888\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3889\f[R]

3890.fi

3891.PP

3892Here \f[C]mycode\f[R] is an identifier, \f[C]haskell\f[R] and

3893\f[C]numberLines\f[R] are classes, and \f[C]startFrom\f[R] is an

3894attribute with value \f[C]100\f[R].

3895Some output formats can use this information to do syntax highlighting.

3896Currently, the only output formats that uses this information are HTML,

3897LaTeX, Docx, Ms, and PowerPoint.

3898If highlighting is supported for your output format and language, then

3899the code block above will appear highlighted, with numbered lines.

3900(To see which languages are supported, type