man/pandoc.1 · typeable/pandoc

git.iko.soy/typeable/pandoc

on 2.11.0.2 help sign in

typeable/pandoc/man/pandoc.1

7371 lines 223 kB history raw

1.\"t

2.\" Automatically generated by Pandoc 2.11.0.1

3.\"

4.TH "Pandoc User\[cq]s Guide" "" "July 23, 2020" "pandoc 2.11.0.2" ""

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]ifxetex\f[R], \f[C]ifluatex\f[R], \f[C]listings\f[R] (if the

176\f[C]--listings\f[R] option is used), \f[C]fancyvrb\f[R],

177\f[C]longtable\f[R], \f[C]booktabs\f[R], \f[C]graphicx\f[R] (if the

178document contains images), \f[C]hyperref\f[R], \f[C]xcolor\f[R],

179\f[C]ulem\f[R], \f[C]geometry\f[R] (with the \f[C]geometry\f[R] variable

180set), \f[C]setspace\f[R] (with \f[C]linestretch\f[R]), and

181\f[C]babel\f[R] (with \f[C]lang\f[R]).

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

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

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

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

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

187set).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

202tables).

203.SS Reading from the Web

204.PP

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

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

207.IP

208.nf

209\f[C]

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

211\f[R]

212.fi

213.PP

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

215requesting a document from a URL:

216.IP

217.nf

218\f[C]

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

220 https://www.fsf.org

221\f[R]

222.fi

223.SH OPTIONS

224.SS General options

225.TP

226\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]

227Specify input format.

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

229.RS

230.IP \[bu] 2

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

232.IP \[bu] 2

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

234.IP \[bu] 2

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

236.IP \[bu] 2

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

238.IP \[bu] 2

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

240.IP \[bu] 2

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

242.IP \[bu] 2

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

244.IP \[bu] 2

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

246.IP \[bu] 2

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

248.IP \[bu] 2

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

250.IP \[bu] 2

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

252.IP \[bu] 2

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

254.IP \[bu] 2

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

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

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

258.IP \[bu] 2

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

260.IP \[bu] 2

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

262.IP \[bu] 2

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

264.IP \[bu] 2

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

266.IP \[bu] 2

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

268.IP \[bu] 2

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

270.IP \[bu] 2

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

272.IP \[bu] 2

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

274.IP \[bu] 2

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

276.IP \[bu] 2

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

278.IP \[bu] 2

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

280.IP \[bu] 2

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

282.IP \[bu] 2

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

284.IP \[bu] 2

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

286.IP \[bu] 2

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

288.IP \[bu] 2

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

290.IP \[bu] 2

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

292.IP \[bu] 2

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

294.IP \[bu] 2

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

296.IP \[bu] 2

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

298.IP \[bu] 2

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

300.IP \[bu] 2

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

302.IP \[bu] 2

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

304.IP \[bu] 2

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

306.PP

307Extensions can be individually enabled or disabled by appending

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

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

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

311below.

312.RE

313.TP

314\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]

315Specify output format.

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

317.RS

318.IP \[bu] 2

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

320.IP \[bu] 2

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

322.IP \[bu] 2

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

324.IP \[bu] 2

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

326.IP \[bu] 2

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

328.IP \[bu] 2

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

330.IP \[bu] 2

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

332.IP \[bu] 2

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

334.IP \[bu] 2

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

336.IP \[bu] 2

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

338.IP \[bu] 2

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

340.IP \[bu] 2

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

342.IP \[bu] 2

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

344.IP \[bu] 2

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

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

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

348.IP \[bu] 2

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

350.IP \[bu] 2

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

352markup)

353.IP \[bu] 2

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

355.IP \[bu] 2

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

357.IP \[bu] 2

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

359.IP \[bu] 2

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

361.IP \[bu] 2

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

363.IP \[bu] 2

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

365.IP \[bu] 2

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

367.IP \[bu] 2

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

369.IP \[bu] 2

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

371.IP \[bu] 2

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

373.IP \[bu] 2

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

375.IP \[bu] 2

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

377.IP \[bu] 2

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

379.IP \[bu] 2

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

381.IP \[bu] 2

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

383.IP \[bu] 2

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

385.IP \[bu] 2

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

387.IP \[bu] 2

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

389.IP \[bu] 2

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

391.IP \[bu] 2

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

393.IP \[bu] 2

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

395.IP \[bu] 2

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

397.IP \[bu] 2

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

399.IP \[bu] 2

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

401.IP \[bu] 2

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

403.IP \[bu] 2

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

405.IP \[bu] 2

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

407.IP \[bu] 2

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

409.IP \[bu] 2

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

411.IP \[bu] 2

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

413.IP \[bu] 2

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

415.IP \[bu] 2

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

417.IP \[bu] 2

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

419.IP \[bu] 2

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

421.IP \[bu] 2

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

423.IP \[bu] 2

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

425.IP \[bu] 2

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

427.IP \[bu] 2

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

429.IP \[bu] 2

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

431.PP

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

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

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

435.PP

436Extensions can be individually enabled or disabled by appending

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

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

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

440below.

441.RE

442.TP

443\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]

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

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

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

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

448.TP

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

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

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

452used.

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

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

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

456variable).

457If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used

458(for backwards compatibility).

459In Windows the default user data directory is

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

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

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

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

464\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or

465\f[C]s5\f[R] directory placed in this directory will override

466pandoc\[cq]s normal defaults.

467.TP

468\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]

469Specify a set of default option settings.

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

471option settings.

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

473can be set using a defaults file.

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

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

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

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

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

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

480subsequent options on the command line.

481.TP

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

483Generate a bash completion script.

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

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

486.RS

487.IP

488.nf

489\f[C]

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

491\f[R]

492.fi

493.RE

494.TP

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

496Give verbose debugging output.

497.TP

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

499Suppress warning messages.

500.TP

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

502Exit with error status if there are any warnings.

503.TP

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

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

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

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

508.TP

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

510List supported input formats, one per line.

511.TP

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

513List supported output formats, one per line.

514.TP

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

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

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

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

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

520are given.

521.TP

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

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

524.TP

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

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

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

528.TP

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

530Print version.

531.TP

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

533Show usage message.

534.SS Reader options

535.TP

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

537Shift heading levels by a positive or negative integer.

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

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

540headings.

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

542shifted below level 1 becomes a regular paragraph.

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

544document replaces the metadata title.

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

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

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

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

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

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

551.TP

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

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

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

555to 1).

556.TP

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

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

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

560This option is useful for converting word processing documents where

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

562.TP

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

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

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

566Multiple classes may be separated by spaces or commas.

567.TP

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

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

570extension.

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

572different kinds of images.

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

574.TP

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

576Parse each file individually before combining for multifile documents.

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

578to work as expected.

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

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

581.TP

582\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]

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

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

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

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

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

588argument.

589Hence,

590.RS

591.IP

592.nf

593\f[C]

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

595\f[R]

596.fi

597.PP

598is equivalent to

599.IP

600.nf

601\f[C]

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

603\f[R]

604.fi

605.PP

606The latter form may be useful for debugging filters.

607.PP

608Filters may be written in any language.

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

610writing filters in Haskell.

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

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

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

614JavaScript/node.js.

615.PP

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

617.IP "1." 3

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

619.IP "2." 3

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

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

622above).

623.IP "3." 3

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

625.PP

626Filters and Lua-filters are applied in the order specified on the

627command line.

628.RE

629.TP

630\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]

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

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

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

634will be applied in order.

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

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

637applied.

638.RS

639.PP

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

641creation.

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

643.PP

644The following is an example Lua script for macro-expansion:

645.IP

646.nf

647\f[C]

648function expand_hello_world(inline)

649 if inline.c == \[aq]{{helloworld}}\[aq] then

650 return pandoc.Emph{ pandoc.Str \[dq]Hello, World\[dq] }

651 else

652 return inline

653 end

654end

655

656return {{Str = expand_hello_world}}

657\f[R]

658.fi

659.PP

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

661.IP "1." 3

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

663.IP "2." 3

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

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

666above).

667.RE

668.TP

669\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]]

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

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

672document using YAML metadata blocks.

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

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

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

676variables to be set.

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

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

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

680escaped when inserted into the template.

681.TP

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

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

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

685the YAML file will always be parsed as Markdown.

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

687blocks.

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

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

690over those specified in earlier files.

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

692overwrite values specified with this option.

693.TP

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

695Preserve tabs instead of converting them to spaces.

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

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

698blocks.

699Tabs in regular text are always treated as spaces.

700.TP

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

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

703.TP

704\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]

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

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

707\f[C]accept\f[R] (the default), inserts all insertions, and ignores all

708deletions.

709\f[C]reject\f[R] inserts all deletions and ignores insertions.

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

711\f[C]all\f[R] puts in insertions, deletions, and comments, wrapped in

712spans with \f[C]insertion\f[R], \f[C]deletion\f[R],

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

714respectively.

715The author and time of change is included.

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

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

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

719produces a span with the class

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

721affected paragraph break.

722This option only affects the docx reader.

723.TP

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

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

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

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

728files.

729If the source format is a binary container (docx, epub, or odt), the

730media is extracted from the container and the original filenames are

731used.

732Otherwise the media is read from the file system or downloaded, and new

733filenames are constructed based on SHA1 hashes of the contents.

734.TP

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

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

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

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

739system default.

740To see the system default, use

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

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

743Strings ending in a period that are found in this list will be followed

744by a nonbreaking space, so that the period will not produce

745sentence-ending space in formats like LaTeX.

746.SS General writer options

747.TP

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

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

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

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

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

753output.

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

755otherwise, metadata is suppressed.

756.TP

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

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

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

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

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

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

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

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

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

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

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

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

769.TP

770\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]]

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

772rendering the document in standalone mode.

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

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

775.TP

776\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]

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

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

779in the user data directory are ignored.

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

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

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

783.RS

784.PP

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

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

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

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

789.RE

790.TP

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

792Print a system default data file.

793Files in the user data directory are ignored.

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

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

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

797.TP

798\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]

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

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

801OS on which pandoc is being run).

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

803.TP

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

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

806to inch/centimeters and vice versa.

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

808default is 96dpi.

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

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

811.TP

812\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]

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

814rendered version).

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

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

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

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

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

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

821well).

822Automatic wrapping does not currently work in HTML output.

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

824of markdown cells.

825.TP

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

827Specify length of lines in characters.

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

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

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

831Tables below).

832.TP

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

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

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

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

837to create one) in the output document.

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

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

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

841.RS

842.PP

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

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

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

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

847.RE

848.TP

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

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

851contents.

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

853listed in the contents).

854.TP

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

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

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

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

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

860.TP

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

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

863language attribute is given.

864.TP

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

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

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

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

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

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

871highlighting, below.

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

873.RS

874.PP

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

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

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

878used as the highlighting style.

879.PP

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

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

882.RE

883.TP

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

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

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

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

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

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

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

891.TP

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

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

894used for syntax highlighting of appropriately marked code blocks.

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

896syntax definitions for existing languages.

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

898.TP

899\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]

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

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

902HTML documents.

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

904header.

905They will be included in the order specified.

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

907.TP

908\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]

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

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

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

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

913documents.

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

915They will be included in the order specified.

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

917.TP

918\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]

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

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

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

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

923They will be included in the order specified.

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

925.TP

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

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

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

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

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

931is the working directory.

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

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

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

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

936.RS

937.PP

938\f[C]--resource-path\f[R] only has an effect if (a) the output format

939embeds images (for example, \f[C]docx\f[R], \f[C]pdf\f[R], or

940\f[C]html\f[R] with \f[C]--self-contained\f[R]) or (b) it is used

941together with \f[C]--extract-media\f[R].

942.RE

943.TP

944\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]

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

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

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

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

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

950.TP

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

952Disable the certificate verification to allow access to unsecure HTTP

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

954signed).

955.SS Options affecting specific writers

956.TP

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

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

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

960stylesheets, images, and videos.

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

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

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

964a browser.

965This option works only with HTML output formats, including

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

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

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

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

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

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

972first source file is remote).

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

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

975document.

976Limitation: resources that are loaded dynamically through JavaScript

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

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

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

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

981.TP

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

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

984.TP

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

986Use only ASCII characters in output.

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

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

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

990limited degree LaTeX (which uses standard commands for accented

991characters when possible).

992roff man output uses ASCII by default.

993.TP

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

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

996or reStructuredText.

997By default inline links are used.

998The placement of link references is affected by the

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

1000.TP

1001\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]

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

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

1004current section, or the document.

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

1006Currently only affects the markdown writer.

1007.TP

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

1009Use ATX-style headings in Markdown output.

1010The default is to use setext-style headings for levels 1 to 2, and then

1011ATX headings.

1012(Note: for \f[C]gfm\f[R] output, ATX headings are always used.) This

1013option also affects markdown cells in \f[C]ipynb\f[R] output.

1014.TP

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

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

1017DocBook, and TEI output.

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

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

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

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

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

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

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

1025option.

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

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

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

1029their default type.

1030.TP

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

1032Number section headings in LaTeX, ConTeXt, HTML, Docx, or EPUB output.

1033By default, sections are not numbered.

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

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

1036.TP

1037\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]]

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

1039formats).

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

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

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

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

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

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

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

1047Offsets are 0 by default.

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

1049.TP

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

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

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

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

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

1055package.

1056.TP

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

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

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

1060.TP

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

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

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

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

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

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

1067slide.

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

1069not appear in the slide show.

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

1071document; see Structuring the slide show.

1072.TP

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

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

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

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

1077See Heading identifiers, below.

1078.TP

1079\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]

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

1081documents.

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

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

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

1085decimal or hexadecimal character references.

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

1087.TP

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

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

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

1091output.

1092This is useful for preventing duplicate identifiers when generating

1093fragments to be included in other pages.

1094.TP

1095\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]

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

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

1098beginning of the HTML body).

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

1100.TP

1101\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]

1102Link to a CSS style sheet.

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

1104They will be included in the order specified.

1105.RS

1106.PP

1107A stylesheet is required for generating EPUB.

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

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

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

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

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

1113.RE

1114.TP

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

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

1117file.

1118.RS

1119.TP

1120Docx

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

1122docx file produced using pandoc.

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

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

1125are used in the new docx.

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

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

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

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

1130.RS

1131.PP

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

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

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

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

1136you wish, and save the file.

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

1138the styles used by pandoc:

1139.PP

1140Paragraph styles:

1141.IP \[bu] 2

1142Normal

1143.IP \[bu] 2

1144Body Text

1145.IP \[bu] 2

1146First Paragraph

1147.IP \[bu] 2

1148Compact

1149.IP \[bu] 2

1150Title

1151.IP \[bu] 2

1152Subtitle

1153.IP \[bu] 2

1154Author

1155.IP \[bu] 2

1156Date

1157.IP \[bu] 2

1158Abstract

1159.IP \[bu] 2

1160Bibliography

1161.IP \[bu] 2

1162Heading 1

1163.IP \[bu] 2

1164Heading 2

1165.IP \[bu] 2

1166Heading 3

1167.IP \[bu] 2

1168Heading 4

1169.IP \[bu] 2

1170Heading 5

1171.IP \[bu] 2

1172Heading 6

1173.IP \[bu] 2

1174Heading 7

1175.IP \[bu] 2

1176Heading 8

1177.IP \[bu] 2

1178Heading 9

1179.IP \[bu] 2

1180Block Text

1181.IP \[bu] 2

1182Footnote Text

1183.IP \[bu] 2

1184Definition Term

1185.IP \[bu] 2

1186Definition

1187.IP \[bu] 2

1188Caption

1189.IP \[bu] 2

1190Table Caption

1191.IP \[bu] 2

1192Image Caption

1193.IP \[bu] 2

1194Figure

1195.IP \[bu] 2

1196Captioned Figure

1197.IP \[bu] 2

1198TOC Heading

1199.PP

1200Character styles:

1201.IP \[bu] 2

1202Default Paragraph Font

1203.IP \[bu] 2

1204Body Text Char

1205.IP \[bu] 2

1206Verbatim Char

1207.IP \[bu] 2

1208Footnote Reference

1209.IP \[bu] 2

1210Hyperlink

1211.IP \[bu] 2

1212Section Number

1213.PP

1214Table style:

1215.IP \[bu] 2

1216Table

1217.RE

1218.TP

1219ODT

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

1221ODT produced using pandoc.

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

1223used in the new ODT.

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

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

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

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

1228.RS

1229.PP

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

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

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

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

1234styles as you wish, and save the file.

1235.RE

1236.TP

1237PowerPoint

1238Templates included with Microsoft PowerPoint 2013 (either with

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

1240most templates derived from these.

1241.RS

1242.PP

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

1244following first four layouts:

1245.IP "1." 3

1246Title Slide

1247.IP "2." 3

1248Title and Content

1249.IP "3." 3

1250Section Header

1251.IP "4." 3

1252Two Content

1253.PP

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

1255these criteria.

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

1257check.)

1258.PP

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

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

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

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

1263.RE

1264.RE

1265.TP

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

1267Use the specified image as the EPUB cover.

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

1269height.

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

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

1272below).

1273.TP

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

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

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

1277For example:

1278.RS

1279.IP

1280.nf

1281\f[C]

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

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

1284\f[R]

1285.fi

1286.PP

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

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

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

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

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

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

1293UUID).

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

1295.PP

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

1297document can be used instead.

1298See below under EPUB Metadata.

1299.RE

1300.TP

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

1302Embed the specified font in the EPUB.

1303This option can be repeated to embed multiple fonts.

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

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

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

1307being interpreted by the shell.

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

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

1310.RS

1311.IP

1312.nf

1313\f[C]

1314\[at]font-face {

1315font-family: DejaVuSans;

1316font-style: normal;

1317font-weight: normal;

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

1319}

1320\[at]font-face {

1321font-family: DejaVuSans;

1322font-style: normal;

1323font-weight: bold;

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

1325}

1326\[at]font-face {

1327font-family: DejaVuSans;

1328font-style: italic;

1329font-weight: normal;

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

1331}

1332\[at]font-face {

1333font-family: DejaVuSans;

1334font-style: italic;

1335font-weight: bold;

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

1337}

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

1339\f[R]

1340.fi

1341.RE

1342.TP

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

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

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

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

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

1348way chapters and sections are displayed to users.

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

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

1351chapter level of 2 or 3.

1352.TP

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

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

1355EPUB-specific contents.

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

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

1358.TP

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

1360Determines how ipynb output cells are treated.

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

1362original are preserved.

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

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

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

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

1367.TP

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

1369Use the specified engine when producing PDF output.

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

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

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

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

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

1375specified here.

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

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

1378.RS

1379.IP \[bu] 2

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

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

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

1383.IP \[bu] 2

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

1385.IP \[bu] 2

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

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

1388introduction to PDF generation from HTML/CSS.)

1389.IP \[bu] 2

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

1391.RE

1392.TP

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

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

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

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

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

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

1399Note that no check for duplicate options is done.

1400.SS Citation rendering

1401.TP

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

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

1404citations and adding a bibliography.

1405Citation processing will not take place unless bibliographic data is

1406supplied, either through an external file specified using the

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

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

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

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

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

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

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

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

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

1416they appear on the command line.

1417For more information, see the section on Citations.

1418.TP

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

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

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

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

1423added to bibliography.

1424.TP

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

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

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

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

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

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

1431will be sought in the resource path and finally in the \f[C]csl\f[R]

1432subdirectory of the pandoc user data directory.

1433.TP

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

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

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

1437(This is equivalent to

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

1439a URL, it will be fetched via HTTP.

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

1441will be sought in the resource path and finally in the \f[C]csl\f[R]

1442subdirectory of the pandoc user data directory.

1443.TP

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

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

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

1447PDF output.

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

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

1450.TP

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

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

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

1454PDF output.

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

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

1457.SS Math rendering in HTML

1458.PP

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

1460characters.

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

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

1463from the surrounding text if needed.

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

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

1466options.

1467.TP

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

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

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

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

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

1473Then the MathJax JavaScript will render it.

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

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

1476inserted.

1477.TP

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

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

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

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

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

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

1484natively support MathML.

1485.TP

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

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

1488script that converts formulas to images.

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

1490For SVG images you can for example use

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

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

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

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

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

1496without native math support.

1497.TP

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

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

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

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

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

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

1504inserted.

1505.TP

1506\f[B]\f[CB]--gladtex\f[B]\f[R]

1507Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.

1508The resulting HTML can then be processed by GladTeX to produce images of

1509the typeset formulas and an HTML file with links to these images.

1510So, the procedure is:

1511.RS

1512.IP

1513.nf

1514\f[C]

1515pandoc -s --gladtex input.md -o myfile.htex

1516gladtex -d myfile-images myfile.htex

1517# produces myfile.html and images in myfile-images

1518\f[R]

1519.fi

1520.RE

1521.SS Options for wrapper scripts

1522.TP

1523\f[B]\f[CB]--dump-args\f[B]\f[R]

1524Print information about command-line arguments to \f[I]stdout\f[R], then

1525exit.

1526This option is intended primarily for use in wrapper scripts.

1527The first line of output contains the name of the output file specified

1528with the \f[C]-o\f[R] option, or \f[C]-\f[R] (for \f[I]stdout\f[R]) if

1529no output file was specified.

1530The remaining lines contain the command-line arguments, one per line, in

1531the order they appear.

1532These do not include regular pandoc options and their arguments, but do

1533include any options appearing after a \f[C]--\f[R] separator at the end

1534of the line.

1535.TP

1536\f[B]\f[CB]--ignore-args\f[B]\f[R]

1537Ignore command-line arguments (for use in wrapper scripts).

1538Regular pandoc options are not ignored.

1539Thus, for example,

1540.RS

1541.IP

1542.nf

1543\f[C]

1544pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1

1545\f[R]

1546.fi

1547.PP

1548is equivalent to

1549.IP

1550.nf

1551\f[C]

1552pandoc -o foo.html -s

1553\f[R]

1554.fi

1555.RE

1556.SH EXIT CODES

1557.PP

1558If pandoc completes successfully, it will return exit code 0.

1559Nonzero exit codes have the following meanings:

1560.PP

1561.TS

1562tab(@);

1563r l.

1564T{

1565Code

1566T}@T{

1567Error

1568T}

1569_

1570T{

15713

1572T}@T{

1573PandocFailOnWarningError

1574T}

1575T{

15764

1577T}@T{

1578PandocAppError

1579T}

1580T{

15815

1582T}@T{

1583PandocTemplateError

1584T}

1585T{

15866

1587T}@T{

1588PandocOptionError

1589T}

1590T{

159121

1592T}@T{

1593PandocUnknownReaderError

1594T}

1595T{

159622

1597T}@T{

1598PandocUnknownWriterError

1599T}

1600T{

160123

1602T}@T{

1603PandocUnsupportedExtensionError

1604T}

1605T{

160624

1607T}@T{

1608PandocCiteprocError

1609T}

1610T{

161131

1612T}@T{

1613PandocEpubSubdirectoryError

1614T}

1615T{

161643

1617T}@T{

1618PandocPDFError

1619T}

1620T{

162147

1622T}@T{

1623PandocPDFProgramNotFoundError

1624T}

1625T{

162661

1627T}@T{

1628PandocHttpError

1629T}

1630T{

163162

1632T}@T{

1633PandocShouldNeverHappenError

1634T}

1635T{

163663

1637T}@T{

1638PandocSomeError

1639T}

1640T{

164164

1642T}@T{

1643PandocParseError

1644T}

1645T{

164665

1647T}@T{

1648PandocParsecError

1649T}

1650T{

165166

1652T}@T{

1653PandocMakePDFError

1654T}

1655T{

165667

1657T}@T{

1658PandocSyntaxMapError

1659T}

1660T{

166183

1662T}@T{

1663PandocFilterError

1664T}

1665T{

166691

1667T}@T{

1668PandocMacroLoop

1669T}

1670T{

167192

1672T}@T{

1673PandocUTF8DecodingError

1674T}

1675T{

167693

1677T}@T{

1678PandocIpynbDecodingError

1679T}

1680T{

168197

1682T}@T{

1683PandocCouldNotFindDataFileError

1684T}

1685T{

168699

1687T}@T{

1688PandocResourceNotFound

1689T}

1690.TE

1691.SH DEFAULT FILES

1692.PP

1693The \f[C]--defaults\f[R] option may be used to specify a package of

1694options.

1695Here is a sample defaults file demonstrating all of the fields that may

1696be used:

1697.IP

1698.nf

1699\f[C]

1700from: markdown+emoji

1701# reader: may be used instead of from:

1702to: html5

1703# writer: may be used instead of to:

1704

1705# leave blank for output to stdout:

1706output-file:

1707# leave blank for input from stdin, use [] for no input:

1708input-files:

1709- preface.md

1710- content.md

1711# or you may use input-file: with a single value

1712

1713template: letter

1714standalone: true

1715self-contained: false

1716

1717# note that structured variables may be specified:

1718variables:

1719 documentclass: book

1720 classoption:

1721 - twosides

1722 - draft

1723

1724# metadata values specified here are parsed as literal

1725# string text, not markdown:

1726metadata:

1727 author:

1728 - Sam Smith

1729 - Julie Liu

1730metadata-files:

1731- boilerplate.yaml

1732# or you may use metadata-file: with a single value

1733

1734# Note that these take files, not their contents:

1735include-before-body: []

1736include-after-body: []

1737include-in-header: []

1738resource-path: [\[dq].\[dq]]

1739

1740# turn on built-in citation processing. Note that if you need

1741# control over when the citeproc processing is done relative

1742# to other filters, you should instead use \[ga]citeproc\[ga] in the

1743# list of \[ga]filters\[ga] (see below).

1744citeproc: true

1745csl: ieee

1746bibliography:

1747- foobar.bib

1748- barbaz.json

1749

1750# Filters will be assumed to be Lua filters if they have

1751# the .lua extension, and json filters otherwise. But

1752# the filter type can also be specified explicitly, as shown.

1753# Filters are run in the order specified.

1754# To include the built-in citeproc filter, use either \[ga]citeproc\[ga]

1755# or \[ga]{type: citeproc}\[ga].

1756filters:

1757- wordcount.lua

1758- type: json

1759 path: foo.lua

1760

1761file-scope: false

1762

1763data-dir:

1764

1765# ERROR, WARNING, or INFO

1766verbosity: INFO

1767log-file: log.json

1768

1769# citeproc, natbib, or biblatex

1770cite-method: citeproc

1771# part, chapter, section, or default:

1772top-level-division: chapter

1773abbreviations:

1774

1775pdf-engine: pdflatex

1776pdf-engine-opts:

1777- \[dq]-shell-escape\[dq]

1778# you may also use pdf-engine-opt: with a single option

1779# pdf-engine-opt: \[dq]-shell-escape\[dq]

1780

1781# auto, preserve, or none

1782wrap: auto

1783columns: 78

1784dpi: 72

1785

1786extract-media: mediadir

1787

1788table-of-contents: true

1789toc-depth: 2

1790number-sections: false

1791# a list of offsets at each heading level

1792number-offset: [0,0,0,0,0,0]

1793# toc: may also be used instead of table-of-contents:

1794shift-heading-level-by: 1

1795section-divs: true

1796identifier-prefix: foo

1797title-prefix: \[dq]\[dq]

1798strip-empty-paragraphs: true

1799# lf, crlf, or native

1800eol: lf

1801strip-comments: false

1802indented-code-classes: []

1803ascii: true

1804default-image-extension: \[dq].jpg\[dq]

1805

1806# either a style name of a style definition file:

1807highlight-style: pygments

1808syntax-definitions:

1809- c.xml

1810# or you may use syntax-definition: with a single value

1811listings: false

1812

1813reference-doc: myref.docx

1814

1815# method is plain, webtex, gladtex, mathml, mathjax, katex

1816# you may specify a url with webtex, mathjax, katex

1817html-math-method:

1818 method: mathjax

1819 url: \[dq]https://cdn.jsdelivr.net/npm/mathjax\[at]3/es5/tex-mml-chtml.js\[dq]

1820# none, references, or javascript

1821email-obfuscation: javascript

1822

1823tab-stop: 8

1824preserve-tabs: true

1825

1826incremental: false

1827slide-level: 2

1828

1829epub-subdirectory: EPUB

1830epub-metadata: meta.xml

1831epub-fonts:

1832- foobar.otf

1833epub-chapter-level: 1

1834epub-cover-image: cover.jpg

1835

1836reference-links: true

1837# block, section, or document

1838reference-location: block

1839atx-headers: false

1840

1841# accept, reject, or all

1842track-changes: accept

1843

1844html-q-tags: false

1845css:

1846- site.css

1847

1848# none, all, or best

1849ipynb-output: best

1850

1851# A list of two-element lists

1852request-headers:

1853- [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]

1854

1855fail-if-warnings: false

1856dump-args: false

1857ignore-args: false

1858trace: false

1859\f[R]

1860.fi

1861.PP

1862Fields that are omitted will just have their regular default values.

1863So a defaults file can be as simple as one line:

1864.IP

1865.nf

1866\f[C]

1867verbosity: INFO

1868\f[R]

1869.fi

1870.PP

1871Default files can be placed in the \f[C]defaults\f[R] subdirectory of

1872the user data directory and used from any directory.

1873For example, one could create a file specifying defaults for writing

1874letters, save it as \f[C]letter.yaml\f[R] in the \f[C]defaults\f[R]

1875subdirectory of the user data directory, and then invoke these defaults

1876from any directory using \f[C]pandoc --defaults letter\f[R] or

1877\f[C]pandoc -dletter\f[R].

1878.PP

1879When multiple defaults are used, their contents will be combined.

1880.PP

1881Note that, where command-line arguments may be repeated

1882(\f[C]--metadata-file\f[R], \f[C]--css\f[R],

1883\f[C]--include-in-header\f[R], \f[C]--include-before-body\f[R],

1884\f[C]--include-after-body\f[R], \f[C]--variable\f[R],

1885\f[C]--metadata\f[R], \f[C]--syntax-definition\f[R]), the values

1886specified on the command line will combine with values specified in the

1887defaults file, rather than replacing them.

1888.SH TEMPLATES

1889.PP

1890When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a

1891template to add header and footer material that is needed for a

1892self-standing document.

1893To see the default template that is used, just type

1894.IP

1895.nf

1896\f[C]

1897pandoc -D *FORMAT*

1898\f[R]

1899.fi

1900.PP

1901where \f[I]FORMAT\f[R] is the name of the output format.

1902A custom template can be specified using the \f[C]--template\f[R]

1903option.

1904You can also override the system default templates for a given output

1905format \f[I]FORMAT\f[R] by putting a file

1906\f[C]templates/default.*FORMAT*\f[R] in the user data directory (see

1907\f[C]--data-dir\f[R], above).

1908\f[I]Exceptions:\f[R]

1909.IP \[bu] 2

1910For \f[C]odt\f[R] output, customize the \f[C]default.opendocument\f[R]

1911template.

1912.IP \[bu] 2

1913For \f[C]pdf\f[R] output, customize the \f[C]default.latex\f[R] template

1914(or the \f[C]default.context\f[R] template, if you use

1915\f[C]-t context\f[R], or the \f[C]default.ms\f[R] template, if you use

1916\f[C]-t ms\f[R], or the \f[C]default.html\f[R] template, if you use

1917\f[C]-t html\f[R]).

1918.IP \[bu] 2

1919\f[C]docx\f[R] and \f[C]pptx\f[R] have no template (however, you can use

1920\f[C]--reference-doc\f[R] to customize the output).

1921.PP

1922Templates contain \f[I]variables\f[R], which allow for the inclusion of

1923arbitrary information at any point in the file.

1924They may be set at the command line using the \f[C]-V/--variable\f[R]

1925option.

1926If a variable is not set, pandoc will look for the key in the

1927document\[cq]s metadata, which can be set using either YAML metadata

1928blocks or with the \f[C]-M/--metadata\f[R] option.

1929In addition, some variables are given default values by pandoc.

1930See Variables below for a list of variables used in pandoc\[cq]s default

1931templates.

1932.PP

1933If you use custom templates, you may need to revise them as pandoc

1934changes.

1935We recommend tracking the changes in the default templates, and

1936modifying your custom templates accordingly.

1937An easy way to do this is to fork the pandoc-templates repository and

1938merge in changes after each pandoc release.

1939.SS Template syntax

1940.SS Comments

1941.PP

1942Anything between the sequence \f[C]$--\f[R] and the end of the line will

1943be treated as a comment and omitted from the output.

1944.SS Delimiters

1945.PP

1946To mark variables and control structures in the template, either

1947\f[C]$\f[R]\&...\f[C]$\f[R] or \f[C]${\f[R]\&...\f[C]}\f[R] may be used

1948as delimiters.

1949The styles may also be mixed in the same template, but the opening and

1950closing delimiter must match in each case.

1951The opening delimiter may be followed by one or more spaces or tabs,

1952which will be ignored.

1953The closing delimiter may be followed by one or more spaces or tabs,

1954which will be ignored.

1955.PP

1956To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].

1957.SS Interpolated variables

1958.PP

1959A slot for an interpolated variable is a variable name surrounded by

1960matched delimiters.

1961Variable names must begin with a letter and can contain letters,

1962numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].

1963The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],

1964\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may

1965not be used as variable names.

1966Examples:

1967.IP

1968.nf

1969\f[C]

1970$foo$

1971$foo.bar.baz$

1972$foo_bar.baz-bim$

1973$ foo $

1974${foo}

1975${foo.bar.baz}

1976${foo_bar.baz-bim}

1977${ foo }

1978\f[R]

1979.fi

1980.PP

1981Variable names with periods are used to get at structured variable

1982values.

1983So, for example, \f[C]employee.salary\f[R] will return the value of the

1984\f[C]salary\f[R] field of the object that is the value of the

1985\f[C]employee\f[R] field.

1986.IP \[bu] 2

1987If the value of the variable is simple value, it will be rendered

1988verbatim.

1989(Note that no escaping is done; the assumption is that the calling

1990program will escape the strings appropriately for the output format.)

1991.IP \[bu] 2

1992If the value is a list, the values will be concatenated.

1993.IP \[bu] 2

1994If the value is a map, the string \f[C]true\f[R] will be rendered.

1995.IP \[bu] 2

1996Every other value will be rendered as the empty string.

1997.SS Conditionals

1998.PP

1999A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched

2000delimiters) and ends with \f[C]endif\f[R] (enclosed in matched

2001delimiters).

2002It may optionally contain an \f[C]else\f[R] (enclosed in matched

2003delimiters).

2004The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty

2005value, otherwise the \f[C]else\f[R] section is used (if present).

2006Examples:

2007.IP

2008.nf

2009\f[C]

2010$if(foo)$bar$endif$

2011

2012$if(foo)$

2013 $foo$

2014$endif$

2015

2016$if(foo)$

2017part one

2018$else$

2019part two

2020$endif$

2021

2022${if(foo)}bar${endif}

2023

2024${if(foo)}

2025 ${foo}

2026${endif}

2027

2028${if(foo)}

2029${ foo.bar }

2030${else}

2031no foo!

2032${endif}

2033\f[R]

2034.fi

2035.PP

2036The keyword \f[C]elseif\f[R] may be used to simplify complex nested

2037conditionals:

2038.IP

2039.nf

2040\f[C]

2041$if(foo)$

2042XXX

2043$elseif(bar)$

2044YYY

2045$else$

2046ZZZ

2047$endif$

2048\f[R]

2049.fi

2050.SS For loops

2051.PP

2052A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched

2053delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched

2054delimiters.

2055.IP \[bu] 2

2056If \f[C]variable\f[R] is an array, the material inside the loop will be

2057evaluated repeatedly, with \f[C]variable\f[R] being set to each value of

2058the array in turn, and concatenated.

2059.IP \[bu] 2

2060If \f[C]variable\f[R] is a map, the material inside will be set to the

2061map.

2062.IP \[bu] 2

2063If the value of the associated variable is not an array or a map, a

2064single iteration will be performed on its value.

2065.PP

2066Examples:

2067.IP

2068.nf

2069\f[C]

2070$for(foo)$$foo$$sep$, $endfor$

2071

2072$for(foo)$

2073 - $foo.last$, $foo.first$

2074$endfor$

2075

2076${ for(foo.bar) }

2077 - ${ foo.bar.last }, ${ foo.bar.first }

2078${ endfor }

2079

2080$for(mymap)$

2081$it.name$: $it.office$

2082$endfor$

2083\f[R]

2084.fi

2085.PP

2086You may optionally specify a separator between consecutive values using

2087\f[C]sep\f[R] (enclosed in matched delimiters).

2088The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the

2089separator.

2090.IP

2091.nf

2092\f[C]

2093${ for(foo) }${ foo }${ sep }, ${ endfor }

2094\f[R]

2095.fi

2096.PP

2097Instead of using \f[C]variable\f[R] inside the loop, the special

2098anaphoric keyword \f[C]it\f[R] may be used.

2099.IP

2100.nf

2101\f[C]

2102${ for(foo.bar) }

2103 - ${ it.last }, ${ it.first }

2104${ endfor }

2105\f[R]

2106.fi

2107.SS Partials

2108.PP

2109Partials (subtemplates stored in different files) may be included by

2110using the name of the partial, followed by \f[C]()\f[R], for example:

2111.IP

2112.nf

2113\f[C]

2114${ styles() }

2115\f[R]

2116.fi

2117.PP

2118Partials will be sought in the directory containing the main template.

2119The file name will be assumed to have the same extension as the main

2120template if it lacks an extension.

2121When calling the partial, the full name including file extension can

2122also be used:

2123.IP

2124.nf

2125\f[C]

2126${ styles.html() }

2127\f[R]

2128.fi

2129.PP

2130(If a partial is not found in the directory of the template, it will

2131also be sought in the \f[C]templates\f[R] subdirectory of the user data

2132directory.)

2133.PP

2134Partials may optionally be applied to variables using a colon:

2135.IP

2136.nf

2137\f[C]

2138${ date:fancy() }

2139

2140${ articles:bibentry() }

2141\f[R]

2142.fi

2143.PP

2144If \f[C]articles\f[R] is an array, this will iterate over its values,

2145applying the partial \f[C]bibentry()\f[R] to each one.

2146So the second example above is equivalent to

2147.IP

2148.nf

2149\f[C]

2150${ for(articles) }

2151${ it:bibentry() }

2152${ endfor }

2153\f[R]

2154.fi

2155.PP

2156Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating

2157over partials.

2158In the above examples, the \f[C]bibentry\f[R] partial should contain

2159\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].

2160.PP

2161Final newlines are omitted from included partials.

2162.PP

2163Partials may include other partials.

2164.PP

2165A separator between values of an array may be specified in square

2166brackets, immediately after the variable name or partial:

2167.IP

2168.nf

2169\f[C]

2170${months[, ]}$

2171

2172${articles:bibentry()[; ]$

2173\f[R]

2174.fi

2175.PP

2176The separator in this case is literal and (unlike with \f[C]sep\f[R] in

2177an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or

2178other template directives.

2179.SS Nesting

2180.PP

2181To ensure that content is \[lq]nested,\[rq] that is, subsequent lines

2182indented, use the \f[C]\[ha]\f[R] directive:

2183.IP

2184.nf

2185\f[C]

2186$item.number$ $\[ha]$$item.description$ ($item.price$)

2187\f[R]

2188.fi

2189.PP

2190In this example, if \f[C]item.description\f[R] has multiple lines, they

2191will all be indented to line up with the first line:

2192.IP

2193.nf

2194\f[C]

219500123 A fine bottle of 18-year old

2196 Oban whiskey. ($148)

2197\f[R]

2198.fi

2199.PP

2200To nest multiple lines to the same level, align them with the

2201\f[C]\[ha]\f[R] directive in the template.

2202For example:

2203.IP

2204.nf

2205\f[C]

2206$item.number$ $\[ha]$$item.description$ ($item.price$)

2207 (Available til $item.sellby$.)

2208\f[R]

2209.fi

2210.PP

2211will produce

2212.IP

2213.nf

2214\f[C]

221500123 A fine bottle of 18-year old

2216 Oban whiskey. ($148)

2217 (Available til March 30, 2020.)

2218\f[R]

2219.fi

2220.PP

2221If a variable occurs by itself on a line, preceded by whitespace and not

2222followed by further text or directives on the same line, and the

2223variable\[cq]s value contains multiple lines, it will be nested

2224automatically.

2225.SS Breakable spaces

2226.PP

2227Normally, spaces in the template itself (as opposed to values of the

2228interpolated variables) are not breakable, but they can be made

2229breakable in part of the template by using the \f[C]\[ti]\f[R] keyword

2230(ended with another \f[C]\[ti]\f[R]).

2231.IP

2232.nf

2233\f[C]

2234$\[ti]$This long line may break if the document is rendered

2235with a short line length.$\[ti]$

2236\f[R]

2237.fi

2238.SS Pipes

2239.PP

2240A pipe transforms the value of a variable or partial.

2241Pipes are specified using a slash (\f[C]/\f[R]) between the variable

2242name (or partial) and the pipe name.

2243Example:

2244.IP

2245.nf

2246\f[C]

2247$for(name)$

2248$name/uppercase$

2249$endfor$

2250

2251$for(metadata/pairs)$

2252- $it.key$: $it.value$

2253$endfor$

2254

2255$employee:name()/uppercase$

2256\f[R]

2257.fi

2258.PP

2259Pipes may be chained:

2260.IP

2261.nf

2262\f[C]

2263$for(employees/pairs)$

2264$it.key/alpha/uppercase$. $it.name$

2265$endfor$

2266\f[R]

2267.fi

2268.PP

2269Some pipes take parameters:

2270.IP

2271.nf

2272\f[C]

2273|----------------------|------------|

2274$for(employee)$

2275$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$

2276$endfor$

2277|----------------------|------------|

2278\f[R]

2279.fi

2280.PP

2281Currently the following pipes are predefined:

2282.IP \[bu] 2

2283\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with

2284\f[C]key\f[R] and \f[C]value\f[R] fields.

2285If the original value was an array, the \f[C]key\f[R] will be the array

2286index, starting with 1.

2287.IP \[bu] 2

2288\f[C]uppercase\f[R]: Converts text to uppercase.

2289.IP \[bu] 2

2290\f[C]lowercase\f[R]: Converts text to lowercase.

2291.IP \[bu] 2

2292\f[C]length\f[R]: Returns the length of the value: number of characters

2293for a textual value, number of elements for a map or array.

2294.IP \[bu] 2

2295\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect

2296on other values.

2297.IP \[bu] 2

2298\f[C]first\f[R]: Returns the first value of an array, if applied to a

2299non-empty array; otherwise returns the original value.

2300.IP \[bu] 2

2301\f[C]last\f[R]: Returns the last value of an array, if applied to a

2302non-empty array; otherwise returns the original value.

2303.IP \[bu] 2

2304\f[C]rest\f[R]: Returns all but the first value of an array, if applied

2305to a non-empty array; otherwise returns the original value.

2306.IP \[bu] 2

2307\f[C]allbutlast\f[R]: Returns all but the last value of an array, if

2308applied to a non-empty array; otherwise returns the original value.

2309.IP \[bu] 2

2310\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).

2311.IP \[bu] 2

2312\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.

2313.IP \[bu] 2

2314\f[C]alpha\f[R]: Converts textual values that can be read as an integer

2315into lowercase alphabetic characters \f[C]a..z\f[R] (mod 26).

2316This can be used to get lettered enumeration from array indices.

2317To get uppercase letters, chain with \f[C]uppercase\f[R].

2318.IP \[bu] 2

2319\f[C]roman\f[R]: Converts textual values that can be read as an integer

2320into lowercase roman numerials.

2321This can be used to get lettered enumeration from array indices.

2322To get uppercase roman, chain with \f[C]uppercase\f[R].

2323.IP \[bu] 2

2324\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2325textual value in a block of width \f[C]n\f[R], aligned to the left, with

2326an optional left and right border.

2327Has no effect on other values.

2328This can be used to align material in tables.

2329Widths are positive integers indicating the number of characters.

2330Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and

2331\f[C]\[rs]\f[R] characters must be backslash-escaped.

2332.IP \[bu] 2

2333\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2334textual value in a block of width \f[C]n\f[R], aligned to the right, and

2335has no effect on other values.

2336.IP \[bu] 2

2337\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2338textual value in a block of width \f[C]n\f[R], aligned to the center,

2339and has no effect on other values.

2340.SS Variables

2341.SS Metadata variables

2342.TP

2343\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]

2344allow identification of basic aspects of the document.

2345Included in PDF metadata through LaTeX and ConTeXt.

2346These can be set through a pandoc title block, which allows for multiple

2347authors, or through a YAML metadata block:

2348.RS

2349.IP

2350.nf

2351\f[C]

2352---

2353author:

2354- Aristotle

2355- Peter Abelard

2356\&...

2357\f[R]

2358.fi

2359.PP

2360Note that if you just want to set PDF or HTML metadata, without

2361including a title block in the document itself, you can set the

2362\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]

2363variables.

2364(By default these are set automatically, based on \f[C]title\f[R],

2365\f[C]author\f[R], and \f[C]date\f[R].)

2366.RE

2367.TP

2368\f[B]\f[CB]subtitle\f[B]\f[R]

2369document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx

2370documents

2371.TP

2372\f[B]\f[CB]abstract\f[B]\f[R]

2373document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx

2374documents

2375.TP

2376\f[B]\f[CB]keywords\f[B]\f[R]

2377list of keywords to be included in HTML, PDF, ODT, pptx, docx and

2378AsciiDoc metadata; repeat as for \f[C]author\f[R], above

2379.TP

2380\f[B]\f[CB]subject\f[B]\f[R]

2381document subject, included in ODT, PDF, docx and pptx metadata

2382.TP

2383\f[B]\f[CB]description\f[B]\f[R]

2384document description, included in ODT, docx and pptx metadata.

2385Some applications show this as \f[C]Comments\f[R] metadata.

2386.TP

2387\f[B]\f[CB]category\f[B]\f[R]

2388document category, included in docx and pptx metadata

2389.PP

2390Additionally, any root-level string metadata, not included in ODT, docx

2391or pptx metadata is added as a \f[I]custom property\f[R].

2392The following YAML metadata block for instance:

2393.IP

2394.nf

2395\f[C]

2396---

2397title: \[aq]This is the title\[aq]

2398subtitle: \[dq]This is the subtitle\[dq]

2399author:

2400- Author One

2401- Author Two

2402description: |

2403 This is a long

2404 description.

2405

2406 It consists of two paragraphs

2407\&...

2408\f[R]

2409.fi

2410.PP

2411will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]

2412as standard document properties and \f[C]subtitle\f[R] as a custom

2413property when converting to docx, ODT or pptx.

2414.SS Language variables

2415.TP

2416\f[B]\f[CB]lang\f[B]\f[R]

2417identifies the main language of the document using IETF language tags

2418(following the BCP 47 standard), such as \f[C]en\f[R] or

2419\f[C]en-GB\f[R].

2420The Language subtag lookup tool can look up or verify these tags.

2421This affects most formats, and controls hyphenation in PDF output when

2422using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or

2423ConTeXt.

2424.RS

2425.PP

2426Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to

2427switch the language:

2428.IP

2429.nf

2430\f[C]

2431---

2432lang: en-GB

2433\&...

2434

2435Text in the main document language (British English).

2436

2437::: {lang=fr-CA}

2438> Cette citation est \['e]crite en fran\[,c]ais canadien.

2439:::

2440

2441More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}

2442\f[R]

2443.fi

2444.RE

2445.TP

2446\f[B]\f[CB]dir\f[B]\f[R]

2447the base script direction, either \f[C]rtl\f[R] (right-to-left) or

2448\f[C]ltr\f[R] (left-to-right).

2449.RS

2450.PP

2451For bidirectional documents, native pandoc \f[C]span\f[R]s and

2452\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or

2453\f[C]ltr\f[R]) can be used to override the base direction in some output

2454formats.

2455This may not always be necessary if the final renderer (e.g.\ the

2456browser, when generating HTML) supports the Unicode Bidirectional

2457Algorithm.

2458.PP

2459When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]

2460engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).

2461.RE

2462.SS Variables for HTML

2463.TP

2464\f[B]\f[CB]document-css\f[B]\f[R]

2465Enables inclusion of most of the CSS in the \f[C]styles.html\f[R]

2466partial (have a look with

2467\f[C]pandoc --print-default-data-file=templates/styles.html\f[R]).

2468Unless you use \f[C]--css\f[R], this variable is set to \f[C]true\f[R]

2469by default.

2470You can disable it with e.g.\ \f[C]pandoc -M document-css=false\f[R].

2471.TP

2472\f[B]\f[CB]mainfont\f[B]\f[R]

2473sets the CSS \f[C]font-family\f[R] property on the \f[C]html\f[R]

2474element.

2475.TP

2476\f[B]\f[CB]fontsize\f[B]\f[R]

2477sets the base CSS \f[C]font-size\f[R], which you\[cq]d usually set to

2478e.g.\ \f[C]20px\f[R], but it also accepts \f[C]pt\f[R] (12pt = 16px in

2479most browsers).

2480.TP

2481\f[B]\f[CB]fontcolor\f[B]\f[R]

2482sets the CSS \f[C]color\f[R] property on the \f[C]html\f[R] element.

2483.TP

2484\f[B]\f[CB]linkcolor\f[B]\f[R]

2485sets the CSS \f[C]color\f[R] property on all links.

2486.TP

2487\f[B]\f[CB]monofont\f[B]\f[R]

2488sets the CSS \f[C]font-family\f[R] property on \f[C]code\f[R] elements.

2489.TP

2490\f[B]\f[CB]linestretch\f[B]\f[R]

2491sets the CSS \f[C]line-height\f[R] property on the \f[C]html\f[R]

2492element, which is preferred to be unitless.

2493.TP

2494\f[B]\f[CB]backgroundcolor\f[B]\f[R]

2495sets the CSS \f[C]background-color\f[R] property on the \f[C]html\f[R]

2496element.

2497.TP

2498\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]

2499sets the corresponding CSS \f[C]padding\f[R] properties on the

2500\f[C]body\f[R] element.

2501.SS Variables for HTML math

2502.TP

2503\f[B]\f[CB]classoption\f[B]\f[R]

2504when using KaTeX, you can render display math equations flush left using

2505YAML metadata or with \f[C]-M classoption=fleqn\f[R].

2506.SS Variables for HTML slides

2507.PP

2508These affect HTML output when [producing slide shows with pandoc].

2509.PP

2510All reveal.js configuration options are available as variables.

2511To turn off boolean flags that default to true in reveal.js, use

2512\f[C]0\f[R].

2513.TP

2514\f[B]\f[CB]revealjs-url\f[B]\f[R]

2515base URL for reveal.js documents (defaults to

2516\f[C]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R])

2517.TP

2518\f[B]\f[CB]s5-url\f[B]\f[R]

2519base URL for S5 documents (defaults to \f[C]s5/default\f[R])

2520.TP

2521\f[B]\f[CB]slidy-url\f[B]\f[R]

2522base URL for Slidy documents (defaults to

2523\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])

2524.TP

2525\f[B]\f[CB]slideous-url\f[B]\f[R]

2526base URL for Slideous documents (defaults to \f[C]slideous\f[R])

2527.TP

2528\f[B]\f[CB]title-slide-attributes\f[B]\f[R]

2529additional attributes for the title slide of reveal.js slide shows.

2530See background in reveal.js and beamer for an example.

2531.SS Variables for Beamer slides

2532.PP

2533These variables change the appearance of PDF slides using

2534\f[C]beamer\f[R].

2535.TP

2536\f[B]\f[CB]aspectratio\f[B]\f[R]

2537slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for

253816:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]

2539for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)

2540.TP

2541\f[B]\f[CB]beamerarticle\f[B]\f[R]

2542produce an article from Beamer slides

2543.TP

2544\f[B]\f[CB]beameroption\f[B]\f[R]

2545add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]

2546.TP

2547\f[B]\f[CB]institute\f[B]\f[R]

2548author affiliations: can be a list when there are multiple authors

2549.TP

2550\f[B]\f[CB]logo\f[B]\f[R]

2551logo image for slides

2552.TP

2553\f[B]\f[CB]navigation\f[B]\f[R]

2554controls navigation symbols (default is \f[C]empty\f[R] for no

2555navigation symbols; other valid values are \f[C]frame\f[R],

2556\f[C]vertical\f[R], and \f[C]horizontal\f[R])

2557.TP

2558\f[B]\f[CB]section-titles\f[B]\f[R]

2559enables \[lq]title pages\[rq] for new sections (default is true)

2560.TP

2561\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]

2562beamer themes

2563.TP

2564\f[B]\f[CB]themeoptions\f[B]\f[R]

2565options for LaTeX beamer themes (a list).

2566.TP

2567\f[B]\f[CB]titlegraphic\f[B]\f[R]

2568image for title slide

2569.SS Variables for PowerPoint

2570.PP

2571These variables control the visual aspects of a slide show that are not

2572easily controlled via templates.

2573.TP

2574\f[B]\f[CB]monofont\f[B]\f[R]

2575font to use for code.

2576.SS Variables for LaTeX

2577.PP

2578Pandoc uses these variables when creating a PDF with a LaTeX engine.

2579.SS Layout

2580.TP

2581\f[B]\f[CB]block-headings\f[B]\f[R]

2582make \f[C]\[rs]paragraph\f[R] and \f[C]\[rs]subparagraph\f[R] (fourth-

2583and fifth-level headings, or fifth- and sixth-level with book classes)

2584free-standing rather than run-in; requires further formatting to

2585distinguish from \f[C]\[rs]subsubsection\f[R] (third- or fourth-level

2586headings).

2587Instead of using this option, KOMA-Script can adjust headings more

2588extensively:

2589.RS

2590.IP

2591.nf

2592\f[C]

2593---

2594documentclass: scrartcl

2595header-includes: |

2596 \[rs]RedeclareSectionCommand[

2597 beforeskip=-10pt plus -2pt minus -1pt,

2598 afterskip=1sp plus -1sp minus 1sp,

2599 font=\[rs]normalfont\[rs]itshape]{paragraph}

2600 \[rs]RedeclareSectionCommand[

2601 beforeskip=-10pt plus -2pt minus -1pt,

2602 afterskip=1sp plus -1sp minus 1sp,

2603 font=\[rs]normalfont\[rs]scshape,

2604 indent=0pt]{subparagraph}

2605\&...

2606\f[R]

2607.fi

2608.RE

2609.TP

2610\f[B]\f[CB]classoption\f[B]\f[R]

2611option for document class, e.g.\ \f[C]oneside\f[R]; repeat for multiple

2612options:

2613.RS

2614.IP

2615.nf

2616\f[C]

2617---

2618classoption:

2619- twocolumn

2620- landscape

2621\&...

2622\f[R]

2623.fi

2624.RE

2625.TP

2626\f[B]\f[CB]documentclass\f[B]\f[R]

2627document class: usually one of the standard classes, \f[C]article\f[R],

2628\f[C]book\f[R], and \f[C]report\f[R]; the KOMA-Script equivalents,

2629\f[C]scrartcl\f[R], \f[C]scrbook\f[R], and \f[C]scrreprt\f[R], which

2630default to smaller margins; or \f[C]memoir\f[R]

2631.TP

2632\f[B]\f[CB]geometry\f[B]\f[R]

2633option for \f[C]geometry\f[R] package, e.g.\ \f[C]margin=1in\f[R];

2634repeat for multiple options:

2635.RS

2636.IP

2637.nf

2638\f[C]

2639---

2640geometry:

2641- top=30mm

2642- left=20mm

2643- heightrounded

2644\&...

2645\f[R]

2646.fi

2647.RE

2648.TP

2649\f[B]\f[CB]hyperrefoptions\f[B]\f[R]

2650option for \f[C]hyperref\f[R] package, e.g.\ \f[C]linktoc=all\f[R];

2651repeat for multiple options:

2652.RS

2653.IP

2654.nf

2655\f[C]

2656---

2657hyperrefoptions:

2658- linktoc=all

2659- pdfwindowui

2660- pdfpagemode=FullScreen

2661\&...

2662\f[R]

2663.fi

2664.RE

2665.TP

2666\f[B]\f[CB]indent\f[B]\f[R]

2667uses document class settings for indentation (the default LaTeX template

2668otherwise removes indentation and adds space between paragraphs)

2669.TP

2670\f[B]\f[CB]linestretch\f[B]\f[R]

2671adjusts line spacing using the \f[C]setspace\f[R] package,

2672e.g.\ \f[C]1.25\f[R], \f[C]1.5\f[R]

2673.TP

2674\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]

2675sets margins if \f[C]geometry\f[R] is not used (otherwise

2676\f[C]geometry\f[R] overrides these)

2677.TP

2678\f[B]\f[CB]pagestyle\f[B]\f[R]

2679control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports

2680\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page

2681numbers), and \f[C]headings\f[R] (section titles in running heads)

2682.TP

2683\f[B]\f[CB]papersize\f[B]\f[R]

2684paper size, e.g.\ \f[C]letter\f[R], \f[C]a4\f[R]

2685.TP

2686\f[B]\f[CB]secnumdepth\f[B]\f[R]

2687numbering depth for sections (with \f[C]--number-sections\f[R] option or

2688\f[C]numbersections\f[R] variable)

2689.SS Fonts

2690.TP

2691\f[B]\f[CB]fontenc\f[B]\f[R]

2692allows font encoding to be specified through \f[C]fontenc\f[R] package

2693(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font

2694encodings guide)

2695.TP

2696\f[B]\f[CB]fontfamily\f[B]\f[R]

2697font package for use with \f[C]pdflatex\f[R]: TeX Live includes many

2698options, documented in the LaTeX Font Catalogue.

2699The default is Latin Modern.

2700.TP

2701\f[B]\f[CB]fontfamilyoptions\f[B]\f[R]

2702options for package used as \f[C]fontfamily\f[R]; repeat for multiple

2703options.

2704For example, to use the Libertine font with proportional lowercase

2705(old-style) figures through the \f[C]libertinus\f[R] package:

2706.RS

2707.IP

2708.nf

2709\f[C]

2710---

2711fontfamily: libertinus

2712fontfamilyoptions:

2713- osf

2714- p

2715\&...

2716\f[R]

2717.fi

2718.RE

2719.TP

2720\f[B]\f[CB]fontsize\f[B]\f[R]

2721font size for body text.

2722The standard classes allow 10pt, 11pt, and 12pt.

2723To use another size, set \f[C]documentclass\f[R] to one of the

2724KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].

2725.TP

2726\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]

2727font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take

2728the name of any system font, using the \f[C]fontspec\f[R] package.

2729\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.

2730.TP

2731\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]

2732options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],

2733\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in

2734\f[C]xelatex\f[R] and \f[C]lualatex\f[R].

2735Allow for any choices available through \f[C]fontspec\f[R]; repeat for

2736multiple options.

2737For example, to use the TeX Gyre version of Palatino with lowercase

2738figures:

2739.RS

2740.IP

2741.nf

2742\f[C]

2743---

2744mainfont: TeX Gyre Pagella

2745mainfontoptions:

2746- Numbers=Lowercase

2747- Numbers=Proportional

2748\&...

2749\f[R]

2750.fi

2751.RE

2752.TP

2753\f[B]\f[CB]microtypeoptions\f[B]\f[R]

2754options to pass to the microtype package

2755.SS Links

2756.TP

2757\f[B]\f[CB]colorlinks\f[B]\f[R]

2758add color to link text; automatically enabled if any of

2759\f[C]linkcolor\f[R], \f[C]filecolor\f[R], \f[C]citecolor\f[R],

2760\f[C]urlcolor\f[R], or \f[C]toccolor\f[R] are set

2761.TP

2762\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]

2763color for internal links, external links, citation links, linked URLs,

2764and links in table of contents, respectively: uses options allowed by

2765\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],

2766\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists

2767.TP

2768\f[B]\f[CB]links-as-notes\f[B]\f[R]

2769causes links to be printed as footnotes

2770.SS Front matter

2771.TP

2772\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]

2773include list of figures, list of tables

2774.TP

2775\f[B]\f[CB]thanks\f[B]\f[R]

2776contents of acknowledgments footnote after document title

2777.TP

2778\f[B]\f[CB]toc\f[B]\f[R]

2779include table of contents (can also be set using

2780\f[C]--toc/--table-of-contents\f[R])

2781.TP

2782\f[B]\f[CB]toc-depth\f[B]\f[R]

2783level of section to include in table of contents

2784.SS BibLaTeX Bibliographies

2785.PP

2786These variables function when using BibLaTeX for citation rendering.

2787.TP

2788\f[B]\f[CB]biblatexoptions\f[B]\f[R]

2789list of options for biblatex

2790.TP

2791\f[B]\f[CB]biblio-style\f[B]\f[R]

2792bibliography style, when used with \f[C]--natbib\f[R] and

2793\f[C]--biblatex\f[R].

2794.TP

2795\f[B]\f[CB]biblio-title\f[B]\f[R]

2796bibliography title, when used with \f[C]--natbib\f[R] and

2797\f[C]--biblatex\f[R].

2798.TP

2799\f[B]\f[CB]bibliography\f[B]\f[R]

2800bibliography to use for resolving references

2801.TP

2802\f[B]\f[CB]natbiboptions\f[B]\f[R]

2803list of options for natbib

2804.SS Variables for ConTeXt

2805.PP

2806Pandoc uses these variables when creating a PDF with ConTeXt.

2807.TP

2808\f[B]\f[CB]fontsize\f[B]\f[R]

2809font size for body text (e.g.\ \f[C]10pt\f[R], \f[C]12pt\f[R])

2810.TP

2811\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]

2812text to be placed in running header or footer (see ConTeXt Headers and

2813Footers); repeat up to four times for different placement

2814.TP

2815\f[B]\f[CB]indenting\f[B]\f[R]

2816controls indentation of paragraphs, e.g.\ \f[C]yes,small,next\f[R] (see

2817ConTeXt Indentation); repeat for multiple options

2818.TP

2819\f[B]\f[CB]interlinespace\f[B]\f[R]

2820adjusts line spacing, e.g.\ \f[C]4ex\f[R] (using

2821\f[C]setupinterlinespace\f[R]); repeat for multiple options

2822.TP

2823\f[B]\f[CB]layout\f[B]\f[R]

2824options for page margins and text arrangement (see ConTeXt Layout);

2825repeat for multiple options

2826.TP

2827\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]

2828color for links outside and inside a page, e.g.\ \f[C]red\f[R],

2829\f[C]blue\f[R] (see ConTeXt Color)

2830.TP

2831\f[B]\f[CB]linkstyle\f[B]\f[R]

2832typeface style for links, e.g.\ \f[C]normal\f[R], \f[C]bold\f[R],

2833\f[C]slanted\f[R], \f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R],

2834\f[C]small\f[R]

2835.TP

2836\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]

2837include list of figures, list of tables

2838.TP

2839\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]

2840font families: take the name of any system font (see ConTeXt Font

2841Switching)

2842.TP

2843\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]

2844sets margins, if \f[C]layout\f[R] is not used (otherwise

2845\f[C]layout\f[R] overrides these)

2846.TP

2847\f[B]\f[CB]pagenumbering\f[B]\f[R]

2848page number style and location (using \f[C]setuppagenumbering\f[R]);

2849repeat for multiple options

2850.TP

2851\f[B]\f[CB]papersize\f[B]\f[R]

2852paper size, e.g.\ \f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R]

2853(see ConTeXt Paper Setup); repeat for multiple options

2854.TP

2855\f[B]\f[CB]pdfa\f[B]\f[R]

2856adds to the preamble the setup necessary to generate PDF/A of the type

2857specified, e.g.\ \f[C]1a:2005\f[R], \f[C]2a\f[R].

2858If no type is specified (i.e.\ the value is set to True, by

2859e.g.\ \f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML

2860metadata block), \f[C]1b:2005\f[R] will be used as default, for reasons

2861of backwards compatibility.

2862Using \f[C]--variable=pdfa\f[R] without specified value is not

2863supported.

2864To successfully generate PDF/A the required ICC color profiles have to

2865be available and the content and all included files (such as images)

2866have to be standard conforming.

2867The ICC profiles and output intent may be specified using the variables

2868\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].

2869See also ConTeXt PDFA for more details.

2870.TP

2871\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]

2872when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile

2873to use in the PDF, e.g.\ \f[C]default.cmyk\f[R].

2874If left unspecified, \f[C]sRGB.icc\f[R] is used as default.

2875May be repeated to include multiple profiles.

2876Note that the profiles have to be available on the system.

2877They can be obtained from ConTeXt ICC Profiles.

2878.TP

2879\f[B]\f[CB]pdfaintent\f[B]\f[R]

2880when used in conjunction with \f[C]pdfa\f[R], specifies the output

2881intent for the colors,

2882e.g.\ \f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If

2883left unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.

2884.TP

2885\f[B]\f[CB]toc\f[B]\f[R]

2886include table of contents (can also be set using

2887\f[C]--toc/--table-of-contents\f[R])

2888.TP

2889\f[B]\f[CB]whitespace\f[B]\f[R]

2890spacing between paragraphs, e.g.\ \f[C]none\f[R], \f[C]small\f[R] (using

2891\f[C]setupwhitespace\f[R])

2892.TP

2893\f[B]\f[CB]includesource\f[B]\f[R]

2894include all source documents as file attachments in the PDF file

2895.SS Variables for \f[C]wkhtmltopdf\f[R]

2896.PP

2897Pandoc uses these variables when creating a PDF with

2898\f[C]wkhtmltopdf\f[R].

2899The \f[C]--css\f[R] option also affects the output.

2900.TP

2901\f[B]\f[CB]footer-html\f[B]\f[R], \f[B]\f[CB]header-html\f[B]\f[R]

2902add information to the header and footer

2903.TP

2904\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]

2905set the page margins

2906.TP

2907\f[B]\f[CB]papersize\f[B]\f[R]

2908sets the PDF paper size

2909.SS Variables for man pages

2910.TP

2911\f[B]\f[CB]adjusting\f[B]\f[R]

2912adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center

2913(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins

2914.TP

2915\f[B]\f[CB]footer\f[B]\f[R]

2916footer in man pages

2917.TP

2918\f[B]\f[CB]header\f[B]\f[R]

2919header in man pages

2920.TP

2921\f[B]\f[CB]hyphenate\f[B]\f[R]

2922if \f[C]true\f[R] (the default), hyphenation will be used

2923.TP

2924\f[B]\f[CB]section\f[B]\f[R]

2925section number in man pages

2926.SS Variables for ms

2927.TP

2928\f[B]\f[CB]fontfamily\f[B]\f[R]

2929font family (e.g.\ \f[C]T\f[R] or \f[C]P\f[R])

2930.TP

2931\f[B]\f[CB]indent\f[B]\f[R]

2932paragraph indent (e.g.\ \f[C]2m\f[R])

2933.TP

2934\f[B]\f[CB]lineheight\f[B]\f[R]

2935line height (e.g.\ \f[C]12p\f[R])

2936.TP

2937\f[B]\f[CB]pointsize\f[B]\f[R]

2938point size (e.g.\ \f[C]10p\f[R])

2939.SS Variables set automatically

2940.PP

2941Pandoc sets these variables automatically in response to options or

2942document contents; users can also modify them.

2943These vary depending on the output format, and include the following:

2944.TP

2945\f[B]\f[CB]body\f[B]\f[R]

2946body of document

2947.TP

2948\f[B]\f[CB]date-meta\f[B]\f[R]

2949the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included

2950in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,

2951s5, slideous, slidy).

2952The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],

2953\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),

2954\f[C]dd MM yyyy\f[R] (e.g.\ either \f[C]02 Apr 2018\f[R] or

2955\f[C]02 April 2018\f[R]), \f[C]MM dd, yyyy\f[R]

2956(e.g.\ \f[C]Apr. 02, 2018\f[R] or

2957\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,

2958\f[C]201804\f[R] or \f[C]2018\f[R]).

2959.TP

2960\f[B]\f[CB]header-includes\f[B]\f[R]

2961contents specified by \f[C]-H/--include-in-header\f[R] (may have

2962multiple values)

2963.TP

2964\f[B]\f[CB]include-before\f[B]\f[R]

2965contents specified by \f[C]-B/--include-before-body\f[R] (may have

2966multiple values)

2967.TP

2968\f[B]\f[CB]include-after\f[B]\f[R]

2969contents specified by \f[C]-A/--include-after-body\f[R] (may have

2970multiple values)

2971.TP

2972\f[B]\f[CB]meta-json\f[B]\f[R]

2973JSON representation of all of the document\[cq]s metadata.

2974Field values are transformed to the selected output format.

2975.TP

2976\f[B]\f[CB]numbersections\f[B]\f[R]

2977non-null value if \f[C]-N/--number-sections\f[R] was specified

2978.TP

2979\f[B]\f[CB]sourcefile\f[B]\f[R], \f[B]\f[CB]outputfile\f[B]\f[R]

2980source and destination filenames, as given on the command line.

2981\f[C]sourcefile\f[R] can also be a list if input comes from multiple

2982files, or empty if input is from stdin.

2983You can use the following snippet in your template to distinguish them:

2984.RS

2985.IP

2986.nf

2987\f[C]

2988$if(sourcefile)$

2989$for(sourcefile)$

2990$sourcefile$

2991$endfor$

2992$else$

2993(stdin)

2994$endif$

2995\f[R]

2996.fi

2997.PP

2998Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the

2999terminal.

3000.PP

3001If you need absolute paths, use e.g.\ \f[C]$curdir$/$sourcefile$\f[R].

3002.RE

3003.TP

3004\f[B]\f[CB]curdir\f[B]\f[R]

3005working directory from which pandoc is run.

3006.TP

3007\f[B]\f[CB]toc\f[B]\f[R]

3008non-null value if \f[C]--toc/--table-of-contents\f[R] was specified

3009.TP

3010\f[B]\f[CB]toc-title\f[B]\f[R]

3011title of table of contents (works only with EPUB, HTML, opendocument,

3012odt, docx, pptx, beamer, LaTeX)

3013.SH EXTENSIONS

3014.PP

3015The behavior of some of the readers and writers can be adjusted by

3016enabling or disabling various extensions.

3017.PP

3018An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format

3019name and disabled by adding \f[C]-EXTENSION\f[R].

3020For example, \f[C]--from markdown_strict+footnotes\f[R] is strict

3021Markdown with footnotes enabled, while

3022\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s Markdown

3023without footnotes or pipe tables.

3024.PP

3025The markdown reader and writer make by far the most use of extensions.

3026Extensions only used by them are therefore covered in the section

3027Pandoc\[cq]s Markdown below (See Markdown variants for

3028\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions

3029that also work for other formats are covered.

3030.PP

3031Note that markdown extensions added to the \f[C]ipynb\f[R] format affect

3032Markdown cells in Jupyter notebooks (as do command-line options like

3033\f[C]--atx-headers\f[R]).

3034.SS Typography

3035.SS Extension: \f[C]smart\f[R]

3036.PP

3037Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,

3038\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.

3039Nonbreaking spaces are inserted after certain abbreviations, such as

3040\[lq]Mr.\[rq]

3041.PP

3042This extension can be enabled/disabled for the following formats:

3043.TP

3044input formats

3045\f[C]markdown\f[R], \f[C]commonmark\f[R], \f[C]latex\f[R],

3046\f[C]mediawiki\f[R], \f[C]org\f[R], \f[C]rst\f[R], \f[C]twiki\f[R]

3047.TP

3048output formats

3049\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R], \f[C]rst\f[R]

3050.TP

3051enabled by default in

3052\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R] (both input and

3053output)

3054.PP

3055Note: If you are \f[I]writing\f[R] Markdown, then the \f[C]smart\f[R]

3056extension has the reverse effect: what would have been curly quotes

3057comes out straight.

3058.PP

3059In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for

3060quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for

3061double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)

3062and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).

3063If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse

3064these characters literally.

3065In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the

3066ligatures when possible; if \f[C]smart\f[R] is disabled pandoc will use

3067unicode quotation mark and dash characters.

3068.SS Headings and sections

3069.SS Extension: \f[C]auto_identifiers\f[R]

3070.PP

3071A heading without an explicitly specified identifier will be

3072automatically assigned a unique identifier based on the heading text.

3073.PP

3074This extension can be enabled/disabled for the following formats:

3075.TP

3076input formats

3077\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]rst\f[R], \f[C]mediawiki\f[R],

3078\f[C]textile\f[R]

3079.TP

3080output formats

3081\f[C]markdown\f[R], \f[C]muse\f[R]

3082.TP

3083enabled by default in

3084\f[C]markdown\f[R], \f[C]muse\f[R]

3085.PP

3086The default algorithm used to derive the identifier from the heading

3087text is:

3088.IP \[bu] 2

3089Remove all formatting, links, etc.

3090.IP \[bu] 2

3091Remove all footnotes.

3092.IP \[bu] 2

3093Remove all non-alphanumeric characters, except underscores, hyphens, and

3094periods.

3095.IP \[bu] 2

3096Replace all spaces and newlines with hyphens.

3097.IP \[bu] 2

3098Convert all alphabetic characters to lowercase.

3099.IP \[bu] 2

3100Remove everything up to the first letter (identifiers may not begin with

3101a number or punctuation mark).

3102.IP \[bu] 2

3103If nothing is left after this, use the identifier \f[C]section\f[R].

3104.PP

3105Thus, for example,

3106.PP

3107.TS

3108tab(@);

3109l l.

3110T{

3111Heading

3112T}@T{

3113Identifier

3114T}

3115_

3116T{

3117\f[C]Heading identifiers in HTML\f[R]

3118T}@T{

3119\f[C]heading-identifiers-in-html\f[R]

3120T}

3121T{

3122\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]

3123T}@T{

3124\f[C]ma\[^i]tre-dh\[^o]tel\f[R]

3125T}

3126T{

3127\f[C]*Dogs*?--in *my* house?\f[R]

3128T}@T{

3129\f[C]dogs--in-my-house\f[R]

3130T}

3131T{

3132\f[C][HTML], [S5], or [RTF]?\f[R]

3133T}@T{

3134\f[C]html-s5-or-rtf\f[R]

3135T}

3136T{

3137\f[C]3. Applications\f[R]

3138T}@T{

3139\f[C]applications\f[R]

3140T}

3141T{

3142\f[C]33\f[R]

3143T}@T{

3144\f[C]section\f[R]

3145T}

3146.TE

3147.PP

3148These rules should, in most cases, allow one to determine the identifier

3149from the heading text.

3150The exception is when several headings have the same text; in this case,

3151the first will get an identifier as described above; the second will get

3152the same identifier with \f[C]-1\f[R] appended; the third with

3153\f[C]-2\f[R]; and so on.

3154.PP

3155(However, a different algorithm is used if

3156\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)

3157.PP

3158These identifiers are used to provide link targets in the table of

3159contents generated by the \f[C]--toc|--table-of-contents\f[R] option.

3160They also make it easy to provide links from one section of a document

3161to another.

3162A link to this section, for example, might look like this:

3163.IP

3164.nf

3165\f[C]

3166See the section on

3167[heading identifiers](#heading-identifiers-in-html-latex-and-context).

3168\f[R]

3169.fi

3170.PP

3171Note, however, that this method of providing links to sections works

3172only in HTML, LaTeX, and ConTeXt formats.

3173.PP

3174If the \f[C]--section-divs\f[R] option is specified, then each section

3175will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if

3176\f[C]html4\f[R] was specified), and the identifier will be attached to

3177the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than

3178the heading itself.

3179This allows entire sections to be manipulated using JavaScript or

3180treated differently in CSS.

3181.SS Extension: \f[C]ascii_identifiers\f[R]

3182.PP

3183Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure

3184ASCII.

3185Accents are stripped off of accented Latin letters, and non-Latin

3186letters are omitted.

3187.SS Extension: \f[C]gfm_auto_identifiers\f[R]

3188.PP

3189Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to

3190GitHub\[cq]s method.

3191Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to

3192lowercase characters, and punctuation characters other than \f[C]-\f[R]

3193and \f[C]_\f[R] are removed.

3194Emojis are replaced by their names.

3195.SS Math Input

3196.PP

3197The extensions \f[C]tex_math_dollars\f[R],

3198\f[C]tex_math_single_backslash\f[R], and

3199\f[C]tex_math_double_backslash\f[R] are described in the section about

3200Pandoc\[cq]s Markdown.

3201.PP

3202However, they can also be used with HTML input.

3203This is handy for reading web pages formatted using MathJax, for

3204example.

3205.SS Raw HTML/TeX

3206.PP

3207The following extensions are described in more detail in their

3208respective sections of Pandoc\[cq]s Markdown:

3209.IP \[bu] 2

3210\f[C]raw_html\f[R] allows HTML elements which are not representable in

3211pandoc\[cq]s AST to be parsed as raw HTML.

3212By default, this is disabled for HTML input.

3213.IP \[bu] 2

3214\f[C]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a

3215document.

3216This extension can be enabled/disabled for the following formats (in

3217addition to \f[C]markdown\f[R]):

3218.RS 2

3219.TP

3220input formats

3221\f[C]latex\f[R], \f[C]org\f[R], \f[C]textile\f[R], \f[C]html\f[R]

3222(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only),

3223\f[C]ipynb\f[R]

3224.TP

3225output formats

3226\f[C]textile\f[R], \f[C]commonmark\f[R]

3227.PP

3228Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and

3229\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data

3230with mime type \f[C]text/html\f[R] in output cells.

3231Since the \f[C]ipynb\f[R] reader attempts to preserve the richest

3232possible outputs when several options are given, you will get best

3233results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when

3234converting to formats like \f[C]docx\f[R] which don\[cq]t allow raw

3235\f[C]html\f[R] or \f[C]tex\f[R].

3236.RE

3237.IP \[bu] 2

3238\f[C]native_divs\f[R] causes HTML \f[C]div\f[R] elements to be parsed as

3239native pandoc Div blocks.

3240If you want them to be parsed as raw HTML, use

3241\f[C]-f html-native_divs+raw_html\f[R].

3242.IP \[bu] 2

3243\f[C]native_spans\f[R] causes HTML \f[C]span\f[R] elements to be parsed

3244as native pandoc Span inlines.

3245If you want them to be parsed as raw HTML, use

3246\f[C]-f html-native_spans+raw_html\f[R].

3247If you want to drop all \f[C]div\f[R]s and \f[C]span\f[R]s when

3248converting HTML to Markdown, you can use

3249\f[C]pandoc -f html-native_divs-native_spans -t markdown\f[R].

3250.SS Literate Haskell support

3251.SS Extension: \f[C]literate_haskell\f[R]

3252.PP

3253Treat the document as literate Haskell source.

3254.PP

3255This extension can be enabled/disabled for the following formats:

3256.TP

3257input formats

3258\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R]

3259.TP

3260output formats

3261\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R], \f[C]html\f[R]

3262.PP

3263If you append \f[C]+lhs\f[R] (or \f[C]+literate_haskell\f[R]) to one of

3264the formats above, pandoc will treat the document as literate Haskell

3265source.

3266This means that

3267.IP \[bu] 2

3268In Markdown input, \[lq]bird track\[rq] sections will be parsed as

3269Haskell code rather than block quotations.

3270Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]

3271will also be treated as Haskell code.

3272For ATX-style headings the character `=' will be used instead of `#'.

3273.IP \[bu] 2

3274In Markdown output, code blocks with classes \f[C]haskell\f[R] and

3275\f[C]literate\f[R] will be rendered using bird tracks, and block

3276quotations will be indented one space, so they will not be treated as

3277Haskell code.

3278In addition, headings will be rendered setext-style (with underlines)

3279rather than ATX-style (with `#' characters).

3280(This is because ghc treats `#' characters in column 1 as introducing

3281line numbers.)

3282.IP \[bu] 2

3283In restructured text input, \[lq]bird track\[rq] sections will be parsed

3284as Haskell code.

3285.IP \[bu] 2

3286In restructured text output, code blocks with class \f[C]haskell\f[R]

3287will be rendered using bird tracks.

3288.IP \[bu] 2

3289In LaTeX input, text in \f[C]code\f[R] environments will be parsed as

3290Haskell code.

3291.IP \[bu] 2

3292In LaTeX output, code blocks with class \f[C]haskell\f[R] will be

3293rendered inside \f[C]code\f[R] environments.

3294.IP \[bu] 2

3295In HTML output, code blocks with class \f[C]haskell\f[R] will be

3296rendered with class \f[C]literatehaskell\f[R] and bird tracks.

3297.PP

3298Examples:

3299.IP

3300.nf

3301\f[C]

3302pandoc -f markdown+lhs -t html

3303\f[R]

3304.fi

3305.PP

3306reads literate Haskell source formatted with Markdown conventions and

3307writes ordinary HTML (without bird tracks).

3308.IP

3309.nf

3310\f[C]

3311pandoc -f markdown+lhs -t html+lhs

3312\f[R]

3313.fi

3314.PP

3315writes HTML with the Haskell code in bird tracks, so it can be copied

3316and pasted as literate Haskell source.

3317.PP

3318Note that GHC expects the bird tracks in the first column, so indented

3319literate code blocks (e.g.\ inside an itemized environment) will not be

3320picked up by the Haskell compiler.

3321.SS Other extensions

3322.SS Extension: \f[C]empty_paragraphs\f[R]

3323.PP

3324Allows empty paragraphs.

3325By default empty paragraphs are omitted.

3326.PP

3327This extension can be enabled/disabled for the following formats:

3328.TP

3329input formats

3330\f[C]docx\f[R], \f[C]html\f[R]

3331.TP

3332output formats

3333\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]

3334.SS Extension: \f[C]native_numbering\f[R]

3335.PP

3336Enables native numbering of figures and tables.

3337Enumeration starts at 1.

3338.PP

3339This extension can be enabled/disabled for the following formats:

3340.TP

3341output formats

3342\f[C]odt\f[R], \f[C]opendocument\f[R]

3343.SS Extension: \f[C]styles\f[R]

3344.PP

3345When converting from docx, read all docx styles as divs (for paragraph

3346styles) and spans (for character styles) regardless of whether pandoc

3347understands the meaning of these styles.

3348This can be used with docx custom styles.

3349Disabled by default.

3350.TP

3351input formats

3352\f[C]docx\f[R]

3353.SS Extension: \f[C]amuse\f[R]

3354.PP

3355In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions

3356to Emacs Muse markup.

3357.SS Extension: \f[C]raw_markdown\f[R]

3358.PP

3359In the \f[C]ipynb\f[R] input format, this causes Markdown cells to be

3360included as raw Markdown blocks (allowing lossless round-tripping)

3361rather than being parsed.

3362Use this only when you are targeting \f[C]ipynb\f[R] or a markdown-based

3363output format.

3364.SS Extension: \f[C]citations\f[R]

3365.PP

3366Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted

3367in \f[C]org\f[R] input.

3368.SS Extension: \f[C]ntb\f[R]

3369.PP

3370In the \f[C]context\f[R] output format this enables the use of Natural

3371Tables (TABLE) instead of the default Extreme Tables (xtables).

3372Natural tables allow more fine-grained global customization but come at

3373a performance penalty compared to extreme tables.

3374.SH PANDOC\[cq]S MARKDOWN

3375.PP

3376Pandoc understands an extended and slightly revised version of John

3377Gruber\[cq]s Markdown syntax.

3378This document explains the syntax, noting differences from standard

3379Markdown.

3380Except where noted, these differences can be suppressed by using the

3381\f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R].

3382Extensions can be enabled or disabled to specify the behavior more

3383granularly.

3384They are described in the following.

3385See also Extensions above, for extensions that work also on other

3386formats.

3387.SS Philosophy

3388.PP

3389Markdown is designed to be easy to write, and, even more importantly,

3390easy to read:

3391.RS

3392.PP

3393A Markdown-formatted document should be publishable as-is, as plain

3394text, without looking like it\[cq]s been marked up with tags or

3395formatting instructions.

3396\[en] John Gruber

3397.RE

3398.PP

3399This principle has guided pandoc\[cq]s decisions in finding syntax for

3400tables, footnotes, and other extensions.

3401.PP

3402There is, however, one respect in which pandoc\[cq]s aims are different

3403from the original aims of Markdown.

3404Whereas Markdown was originally designed with HTML generation in mind,

3405pandoc is designed for multiple output formats.

3406Thus, while pandoc allows the embedding of raw HTML, it discourages it,

3407and provides other, non-HTMLish ways of representing important document

3408elements like definition lists, tables, mathematics, and footnotes.

3409.SS Paragraphs

3410.PP

3411A paragraph is one or more lines of text followed by one or more blank

3412lines.

3413Newlines are treated as spaces, so you can reflow your paragraphs as you

3414like.

3415If you need a hard line break, put two or more spaces at the end of a

3416line.

3417.SS Extension: \f[C]escaped_line_breaks\f[R]

3418.PP

3419A backslash followed by a newline is also a hard line break.

3420Note: in multiline and grid table cells, this is the only way to create

3421a hard line break, since trailing spaces in the cells are ignored.

3422.SS Headings

3423.PP

3424There are two kinds of headings: Setext and ATX.

3425.SS Setext-style headings

3426.PP

3427A setext-style heading is a line of text \[lq]underlined\[rq] with a row

3428of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for

3429a level-two heading):

3430.IP

3431.nf

3432\f[C]

3433A level-one heading

3434===================

3435

3436A level-two heading

3437-------------------

3438\f[R]

3439.fi

3440.PP

3441The heading text can contain inline formatting, such as emphasis (see

3442Inline formatting, below).

3443.SS ATX-style headings

3444.PP

3445An ATX-style heading consists of one to six \f[C]#\f[R] signs and a line

3446of text, optionally followed by any number of \f[C]#\f[R] signs.

3447The number of \f[C]#\f[R] signs at the beginning of the line is the

3448heading level:

3449.IP

3450.nf

3451\f[C]

3452## A level-two heading

3453

3454### A level-three heading ###

3455\f[R]

3456.fi

3457.PP

3458As with setext-style headings, the heading text can contain formatting:

3459.IP

3460.nf

3461\f[C]

3462# A level-one heading with a [link](/url) and *emphasis*

3463\f[R]

3464.fi

3465.SS Extension: \f[C]blank_before_header\f[R]

3466.PP

3467Standard Markdown syntax does not require a blank line before a heading.

3468Pandoc does require this (except, of course, at the beginning of the

3469document).

3470The reason for the requirement is that it is all too easy for a

3471\f[C]#\f[R] to end up at the beginning of a line by accident (perhaps

3472through line wrapping).

3473Consider, for example:

3474.IP

3475.nf

3476\f[C]

3477I like several of their flavors of ice cream:

3478#22, for example, and #5.

3479\f[R]

3480.fi

3481.SS Extension: \f[C]space_in_atx_header\f[R]

3482.PP

3483Many Markdown implementations do not require a space between the opening

3484\f[C]#\f[R]s of an ATX heading and the heading text, so that

3485\f[C]#5 bolt\f[R] and \f[C]#hashtag\f[R] count as headings.

3486With this extension, pandoc does require the space.

3487.SS Heading identifiers

3488.PP

3489See also the \f[C]auto_identifiers\f[R] extension above.

3490.SS Extension: \f[C]header_attributes\f[R]

3491.PP

3492Headings can be assigned attributes using this syntax at the end of the

3493line containing the heading text:

3494.IP

3495.nf

3496\f[C]

3497{#identifier .class .class key=value key=value}

3498\f[R]

3499.fi

3500.PP

3501Thus, for example, the following headings will all be assigned the

3502identifier \f[C]foo\f[R]:

3503.IP

3504.nf

3505\f[C]

3506# My heading {#foo}

3507

3508## My heading ## {#foo}

3509

3510My other heading {#foo}

3511---------------

3512\f[R]

3513.fi

3514.PP

3515(This syntax is compatible with PHP Markdown Extra.)

3516.PP

3517Note that although this syntax allows assignment of classes and

3518key/value attributes, writers generally don\[cq]t use all of this

3519information.

3520Identifiers, classes, and key/value attributes are used in HTML and

3521HTML-based formats such as EPUB and slidy.

3522Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,

3523Textile, Jira markup, and AsciiDoc writers.

3524.PP

3525Headings with the class \f[C]unnumbered\f[R] will not be numbered, even

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

3527A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to

3528\f[C].unnumbered\f[R], and preferable in non-English documents.

3529So,

3530.IP

3531.nf

3532\f[C]

3533# My heading {-}

3534\f[R]

3535.fi

3536.PP

3537is just the same as

3538.IP

3539.nf

3540\f[C]

3541# My heading {.unnumbered}

3542\f[R]

3543.fi

3544.PP

3545If the \f[C]unlisted\f[R] class is present in addition to

3546\f[C]unnumbered\f[R], the heading will not be included in a table of

3547contents.

3548(Currently this feature is only implemented for certain formats: those

3549based on LaTeX and HTML, PowerPoint, and RTF.)

3550.SS Extension: \f[C]implicit_header_references\f[R]

3551.PP

3552Pandoc behaves as if reference links have been defined for each heading.

3553So, to link to a heading

3554.IP

3555.nf

3556\f[C]

3557# Heading identifiers in HTML

3558\f[R]

3559.fi

3560.PP

3561you can simply write

3562.IP

3563.nf

3564\f[C]

3565[Heading identifiers in HTML]

3566\f[R]

3567.fi

3568.PP

3569or

3570.IP

3571.nf

3572\f[C]

3573[Heading identifiers in HTML][]

3574\f[R]

3575.fi

3576.PP

3577or

3578.IP

3579.nf

3580\f[C]

3581[the section on heading identifiers][heading identifiers in

3582HTML]

3583\f[R]

3584.fi

3585.PP

3586instead of giving the identifier explicitly:

3587.IP

3588.nf

3589\f[C]

3590[Heading identifiers in HTML](#heading-identifiers-in-html)

3591\f[R]

3592.fi

3593.PP

3594If there are multiple headings with identical text, the corresponding

3595reference will link to the first one only, and you will need to use

3596explicit links to link to the others, as described above.

3597.PP

3598Like regular reference links, these references are case-insensitive.

3599.PP

3600Explicit link reference definitions always take priority over implicit

3601heading references.

3602So, in the following example, the link will point to \f[C]bar\f[R], not

3603to \f[C]#foo\f[R]:

3604.IP

3605.nf

3606\f[C]

3607# Foo

3608

3609[foo]: bar

3610

3611See [foo]

3612\f[R]

3613.fi

3614.SS Block quotations

3615.PP

3616Markdown uses email conventions for quoting blocks of text.

3617A block quotation is one or more paragraphs or other block elements

3618(such as lists or headings), with each line preceded by a \f[C]>\f[R]

3619character and an optional space.

3620(The \f[C]>\f[R] need not start at the left margin, but it should not be

3621indented more than three spaces.)

3622.IP

3623.nf

3624\f[C]

3625> This is a block quote. This

3626> paragraph has two lines.

3627>

3628> 1. This is a list inside a block quote.

3629> 2. Second item.

3630\f[R]

3631.fi

3632.PP

3633A \[lq]lazy\[rq] form, which requires the \f[C]>\f[R] character only on

3634the first line of each block, is also allowed:

3635.IP

3636.nf

3637\f[C]

3638> This is a block quote. This

3639paragraph has two lines.

3640

3641> 1. This is a list inside a block quote.

36422. Second item.

3643\f[R]

3644.fi

3645.PP

3646Among the block elements that can be contained in a block quote are

3647other block quotes.

3648That is, block quotes can be nested:

3649.IP

3650.nf

3651\f[C]

3652> This is a block quote.

3653>

3654> > A block quote within a block quote.

3655\f[R]

3656.fi

3657.PP

3658If the \f[C]>\f[R] character is followed by an optional space, that

3659space will be considered part of the block quote marker and not part of

3660the indentation of the contents.

3661Thus, to put an indented code block in a block quote, you need five

3662spaces after the \f[C]>\f[R]:

3663.IP

3664.nf

3665\f[C]

3666> code

3667\f[R]

3668.fi

3669.SS Extension: \f[C]blank_before_blockquote\f[R]

3670.PP

3671Standard Markdown syntax does not require a blank line before a block

3672quote.

3673Pandoc does require this (except, of course, at the beginning of the

3674document).

3675The reason for the requirement is that it is all too easy for a

3676\f[C]>\f[R] to end up at the beginning of a line by accident (perhaps

3677through line wrapping).

3678So, unless the \f[C]markdown_strict\f[R] format is used, the following

3679does not produce a nested block quote in pandoc:

3680.IP

3681.nf

3682\f[C]

3683> This is a block quote.

3684>> Nested.

3685\f[R]

3686.fi

3687.SS Verbatim (code) blocks

3688.SS Indented code blocks

3689.PP

3690A block of text indented four spaces (or one tab) is treated as verbatim

3691text: that is, special characters do not trigger special formatting, and

3692all spaces and line breaks are preserved.

3693For example,

3694.IP

3695.nf

3696\f[C]

3697 if (a > 3) {

3698 moveShip(5 * gravity, DOWN);

3699 }

3700\f[R]

3701.fi

3702.PP

3703The initial (four space or one tab) indentation is not considered part

3704of the verbatim text, and is removed in the output.

3705.PP

3706Note: blank lines in the verbatim text need not begin with four spaces.

3707.SS Fenced code blocks

3708.SS Extension: \f[C]fenced_code_blocks\f[R]

3709.PP

3710In addition to standard indented code blocks, pandoc supports

3711\f[I]fenced\f[R] code blocks.

3712These begin with a row of three or more tildes (\f[C]\[ti]\f[R]) and end

3713with a row of tildes that must be at least as long as the starting row.

3714Everything between these lines is treated as code.

3715No indentation is necessary:

3716.IP

3717.nf

3718\f[C]

3719\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3720if (a > 3) {

3721 moveShip(5 * gravity, DOWN);

3722}

3723\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3724\f[R]

3725.fi

3726.PP

3727Like regular code blocks, fenced code blocks must be separated from

3728surrounding text by blank lines.

3729.PP

3730If the code itself contains a row of tildes or backticks, just use a

3731longer row of tildes or backticks at the start and end:

3732.IP

3733.nf

3734\f[C]

3735\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3736\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3737code including tildes

3738\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3739\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3740\f[R]

3741.fi

3742.SS Extension: \f[C]backtick_code_blocks\f[R]

3743.PP

3744Same as \f[C]fenced_code_blocks\f[R], but uses backticks

3745(\f[C]\[ga]\f[R]) instead of tildes (\f[C]\[ti]\f[R]).

3746.SS Extension: \f[C]fenced_code_attributes\f[R]

3747.PP

3748Optionally, you may attach attributes to fenced or backtick code block

3749using this syntax:

3750.IP

3751.nf

3752\f[C]

3753\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}

3754qsort [] = []

3755qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++

3756 qsort (filter (>= x) xs)

3757\[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]

3758\f[R]

3759.fi

3760.PP

3761Here \f[C]mycode\f[R] is an identifier, \f[C]haskell\f[R] and

3762\f[C]numberLines\f[R] are classes, and \f[C]startFrom\f[R] is an

3763attribute with value \f[C]100\f[R].

3764Some output formats can use this information to do syntax highlighting.

3765Currently, the only output formats that uses this information are HTML,

3766LaTeX, Docx, Ms, and PowerPoint.

3767If highlighting is supported for your output format and language, then

3768the code block above will appear highlighted, with numbered lines.

3769(To see which languages are supported, type