man/pandoc.1 · typeable/pandoc

git.iko.soy/typeable/pandoc

on 2.10 help sign in

typeable/pandoc/man/pandoc.1

7193 lines 216 kB history raw

1.\"t

2.\" Automatically generated by Pandoc 2.10

3.\"

4.TH "Pandoc User\[aq]s Guide" "" "June 29, 2020" "pandoc 2.10" ""

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\[aq]s enhanced version of Markdown includes syntax for tables,

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

25more.

26See below under Pandoc\[aq]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\[aq]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\[aq]s simple document model.

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

44perfect, conversions from formats more expressive than pandoc\[aq]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.

61a valid HTML file including \f[C]<head>\f[R] and \f[C]<body>\f[R]), use

62the \f[C]-s\f[R] or \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\[aq]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\[aq] 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]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),

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

186set).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

201tables).

202.SS Reading from the Web

203.PP

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

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

206.IP

207.nf

208\f[C]

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

210\f[R]

211.fi

212.PP

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

214requesting a document from a URL:

215.IP

216.nf

217\f[C]

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

219 https://www.fsf.org

220\f[R]

221.fi

222.SH OPTIONS

223.SS General options

224.TP

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

226Specify input format.

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

228.RS

229.IP \[bu] 2

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

231.IP \[bu] 2

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

233.IP \[bu] 2

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

235.IP \[bu] 2

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

237.IP \[bu] 2

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

239.IP \[bu] 2

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

241.IP \[bu] 2

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

243.IP \[bu] 2

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

245.IP \[bu] 2

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

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

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

249.IP \[bu] 2

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

251.IP \[bu] 2

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

253.IP \[bu] 2

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

255.IP \[bu] 2

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

257.IP \[bu] 2

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

259.IP \[bu] 2

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

261.IP \[bu] 2

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

263.IP \[bu] 2

264\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)

265.IP \[bu] 2

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

267.IP \[bu] 2

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

269.IP \[bu] 2

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

271.IP \[bu] 2

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

273.IP \[bu] 2

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

275.IP \[bu] 2

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

277.IP \[bu] 2

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

279.IP \[bu] 2

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

281.IP \[bu] 2

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

283.IP \[bu] 2

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

285.IP \[bu] 2

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

287.IP \[bu] 2

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

289.IP \[bu] 2

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

291.IP \[bu] 2

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

293.IP \[bu] 2

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

295.IP \[bu] 2

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

297.PP

298Extensions can be individually enabled or disabled by appending

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

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

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

302below.

303.RE

304.TP

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

306Specify output format.

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

308.RS

309.IP \[bu] 2

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

311.IP \[bu] 2

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

313.IP \[bu] 2

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

315.IP \[bu] 2

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

317.IP \[bu] 2

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

319.IP \[bu] 2

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

321.IP \[bu] 2

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

323.IP \[bu] 2

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

325.IP \[bu] 2

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

327.IP \[bu] 2

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

329.IP \[bu] 2

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

331.IP \[bu] 2

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

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

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

335.IP \[bu] 2

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

337.IP \[bu] 2

338\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.

339HTML5/XHTML polyglot markup)

340.IP \[bu] 2

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

342.IP \[bu] 2

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

344.IP \[bu] 2

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

346.IP \[bu] 2

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

348.IP \[bu] 2

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

350.IP \[bu] 2

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

352.IP \[bu] 2

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

354.IP \[bu] 2

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

356.IP \[bu] 2

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

358.IP \[bu] 2

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

360.IP \[bu] 2

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

362.IP \[bu] 2

363\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)

364.IP \[bu] 2

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

366.IP \[bu] 2

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

368.IP \[bu] 2

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

370.IP \[bu] 2

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

372.IP \[bu] 2

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

374.IP \[bu] 2

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

376.IP \[bu] 2

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

378.IP \[bu] 2

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

380.IP \[bu] 2

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

382.IP \[bu] 2

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

384.IP \[bu] 2

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

386.IP \[bu] 2

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

388.IP \[bu] 2

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

390.IP \[bu] 2

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

392.IP \[bu] 2

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

394.IP \[bu] 2

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

396.IP \[bu] 2

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

398.IP \[bu] 2

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

400.IP \[bu] 2

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

402.IP \[bu] 2

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

404.IP \[bu] 2

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

406.IP \[bu] 2

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

408.IP \[bu] 2

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

410.IP \[bu] 2

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

412.IP \[bu] 2

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

414.IP \[bu] 2

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

416.IP \[bu] 2

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

418.PP

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

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

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

422.PP

423Extensions can be individually enabled or disabled by appending

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

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

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

427below.

428.RE

429.TP

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

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

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

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

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

435.TP

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

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

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

439used.

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

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

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

443variable).

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

445(for backwards compatibility).

446In Windows the default user data directory is

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

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

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

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

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

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

453pandoc\[aq]s normal defaults.

454.TP

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

456Specify a set of default option settings.

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

458option settings.

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

460can be set using a defaults file.

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

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

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

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

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

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

467subsequent options on the command line.

468.TP

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

470Generate a bash completion script.

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

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

473.RS

474.IP

475.nf

476\f[C]

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

478\f[R]

479.fi

480.RE

481.TP

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

483Give verbose debugging output.

484.TP

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

486Suppress warning messages.

487.TP

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

489Exit with error status if there are any warnings.

490.TP

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

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

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

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

495.TP

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

497List supported input formats, one per line.

498.TP

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

500List supported output formats, one per line.

501.TP

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

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

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

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

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

507are given.

508.TP

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

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

511.TP

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

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

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

515.TP

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

517Print version.

518.TP

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

520Show usage message.

521.SS Reader options

522.TP

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

524Shift heading levels by a positive or negative integer.

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

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

527headings.

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

529shifted below level 1 becomes a regular paragraph.

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

531document replaces the metadata title.

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

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

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

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

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

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

538.TP

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

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

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

542to 1).

543.TP

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

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

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

547This option is useful for converting word processing documents where

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

549.TP

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

551Specify classes to use for indented code blocks--for example,

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

553Multiple classes may be separated by spaces or commas.

554.TP

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

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

557extension.

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

559different kinds of images.

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

561.TP

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

563Parse each file individually before combining for multifile documents.

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

565to work as expected.

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

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

568.TP

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

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

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

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

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

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

575argument.

576Hence,

577.RS

578.IP

579.nf

580\f[C]

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

582\f[R]

583.fi

584.PP

585is equivalent to

586.IP

587.nf

588\f[C]

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

590\f[R]

591.fi

592.PP

593The latter form may be useful for debugging filters.

594.PP

595Filters may be written in any language.

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

597writing filters in Haskell.

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

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

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

601JavaScript/node.js.

602.PP

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

604.IP "1." 3

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

606.IP "2." 3

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

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

609above).

610.IP "3." 3

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

612.PP

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

614command line.

615.RE

616.TP

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

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

619\f[C]--filter\f[R]), but use pandoc\[aq]s build-in Lua filtering system.

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

621will be applied in order.

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

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

624applied.

625.RS

626.PP

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

628creation.

629It is always loaded into the script\[aq]s Lua environment.

630.PP

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

632.IP

633.nf

634\f[C]

635function expand_hello_world(inline)

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

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

638 else

639 return inline

640 end

641end

642

643return {{Str = expand_hello_world}}

644\f[R]

645.fi

646.PP

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

648.IP "1." 3

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

650.IP "2." 3

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

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

653above).

654.RE

655.TP

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

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

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

659document using YAML metadata blocks.

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

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

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

663variables to be set.

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

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

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

667escaped when inserted into the template.

668.TP

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

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

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

672the YAML file will always be parsed as Markdown.

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

674blocks.

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

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

677over those specified in earlier files.

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

679overwrite values specified with this option.

680.TP

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

682Preserve tabs instead of converting them to spaces.

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

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

685blocks.

686Tabs in regular text are always treated as spaces.

687.TP

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

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

690.TP

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

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

693by the MS Word \[dq]Track Changes\[dq] feature.

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

695deletions.

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

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

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

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

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

701respectively.

702The author and time of change is included.

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

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

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

706produces a span with the class

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

708affected paragraph break.

709This option only affects the docx reader.

710.TP

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

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

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

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

715files.

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

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

718used.

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

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

721.TP

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

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

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

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

726system default.

727To see the system default, use

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

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

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

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

732sentence-ending space in formats like LaTeX.

733.SS General writer options

734.TP

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

736Produce output with an appropriate header and footer (e.g.

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

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

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

740output.

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

742otherwise, metadata is suppressed.

743.TP

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

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

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

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

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

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

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

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

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

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

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

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

756.TP

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

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

759rendering the document in standalone mode.

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

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

762.TP

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

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

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

766in the user data directory are ignored.

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

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

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

770.RS

771.PP

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

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

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

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

776.RE

777.TP

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

779Print a system default data file.

780Files in the user data directory are ignored.

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

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

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

784.TP

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

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

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

788OS on which pandoc is being run).

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

790.TP

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

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

793to inch/centimeters and vice versa.

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

795default is 96dpi.

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

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

798.TP

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

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

801rendered version).

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

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

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

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

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

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

808well).

809Automatic wrapping does not currently work in HTML output.

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

811of markdown cells.

812.TP

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

814Specify length of lines in characters.

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

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

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

818Tables below).

819.TP

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

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

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

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

824to create one) in the output document.

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

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

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

828.RS

829.PP

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

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

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

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

834.RE

835.TP

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

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

838contents.

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

840listed in the contents).

841.TP

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

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

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

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

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

847.TP

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

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

850language attribute is given.

851.TP

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

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

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

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

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

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

858highlighting, below.

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

860.RS

861.PP

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

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

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

865used as the highlighting style.

866.PP

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

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

869.RE

870.TP

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

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

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

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

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

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

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

878.TP

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

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

881used for syntax highlighting of appropriately marked code blocks.

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

883syntax definitions for existing languages.

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

885.TP

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

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

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

889HTML documents.

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

891header.

892They will be included in the order specified.

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

894.TP

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

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

897document body (e.g.

898after the \f[C]<body>\f[R] tag in HTML, or the

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

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

901documents.

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

903They will be included in the order specified.

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

905.TP

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

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

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

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

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

911They will be included in the order specified.

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

913.TP

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

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

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

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

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

919is the working directory.

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

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

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

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

924.RS

925.PP

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

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

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

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

930.RE

931.TP

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

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

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

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

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

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

938.TP

939\[ga]--no-check-certificate

940Disable the certificate verification to allow access to unsecure HTTP

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

942signed).

943.SS Options affecting specific writers

944.TP

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

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

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

948stylesheets, images, and videos.

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

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

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

952a browser.

953This option works only with HTML output formats, including

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

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

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

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

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

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

960first source file is remote).

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

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

963document.

964Limitation: resources that are loaded dynamically through JavaScript

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

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

967zoom or speaker notes) may not work in an offline

968\[dq]self-contained\[dq] \f[C]reveal.js\f[R] slide show.

969.TP

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

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

972.TP

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

974Use only ASCII characters in output.

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

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

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

978limited degree LaTeX (which uses standard commands for accented

979characters when possible).

980roff man output uses ASCII by default.

981.TP

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

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

984or reStructuredText.

985By default inline links are used.

986The placement of link references is affected by the

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

988.TP

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

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

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

992current section, or the document.

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

994Currently only affects the markdown writer.

995.TP

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

997Use ATX-style headings in Markdown output.

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

999ATX headings.

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

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

1002.TP

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

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

1005DocBook, and TEI output.

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

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

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

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

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

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

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

1013option.

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

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

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

1017their default type.

1018.TP

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

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

1021By default, sections are not numbered.

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

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

1024.TP

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

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

1027formats).

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

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

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

1031document to be numbered \[dq]6\[dq], specify

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

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

1034numbered \[dq]1.5\[dq], specify \f[C]--number-offset=1,4\f[R].

1035Offsets are 0 by default.

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

1037.TP

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

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

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

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

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

1043package.

1044.TP

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

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

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

1048.TP

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

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

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

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

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

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

1055slide.

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

1057not appear in the slide show.

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

1059document; see Structuring the slide show.

1060.TP

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

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

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

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

1065See Heading identifiers, below.

1066.TP

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

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

1069documents.

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

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

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

1073decimal or hexadecimal character references.

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

1075.TP

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

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

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

1079output.

1080This is useful for preventing duplicate identifiers when generating

1081fragments to be included in other pages.

1082.TP

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

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

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

1086beginning of the HTML body).

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

1088.TP

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

1090Link to a CSS style sheet.

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

1092They will be included in the order specified.

1093.RS

1094.PP

1095A stylesheet is required for generating EPUB.

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

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

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

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

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

1101.RE

1102.TP

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

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

1105file.

1106.RS

1107.TP

1108Docx

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

1110docx file produced using pandoc.

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

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

1113are used in the new docx.

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

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

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

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

1118.RS

1119.PP

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

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

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

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

1124you wish, and save the file.

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

1126the styles used by pandoc:

1127.PP

1128Paragraph styles:

1129.IP \[bu] 2

1130Normal

1131.IP \[bu] 2

1132Body Text

1133.IP \[bu] 2

1134First Paragraph

1135.IP \[bu] 2

1136Compact

1137.IP \[bu] 2

1138Title

1139.IP \[bu] 2

1140Subtitle

1141.IP \[bu] 2

1142Author

1143.IP \[bu] 2

1144Date

1145.IP \[bu] 2

1146Abstract

1147.IP \[bu] 2

1148Bibliography

1149.IP \[bu] 2

1150Heading 1

1151.IP \[bu] 2

1152Heading 2

1153.IP \[bu] 2

1154Heading 3

1155.IP \[bu] 2

1156Heading 4

1157.IP \[bu] 2

1158Heading 5

1159.IP \[bu] 2

1160Heading 6

1161.IP \[bu] 2

1162Heading 7

1163.IP \[bu] 2

1164Heading 8

1165.IP \[bu] 2

1166Heading 9

1167.IP \[bu] 2

1168Block Text

1169.IP \[bu] 2

1170Footnote Text

1171.IP \[bu] 2

1172Definition Term

1173.IP \[bu] 2

1174Definition

1175.IP \[bu] 2

1176Caption

1177.IP \[bu] 2

1178Table Caption

1179.IP \[bu] 2

1180Image Caption

1181.IP \[bu] 2

1182Figure

1183.IP \[bu] 2

1184Captioned Figure

1185.IP \[bu] 2

1186TOC Heading

1187.PP

1188Character styles:

1189.IP \[bu] 2

1190Default Paragraph Font

1191.IP \[bu] 2

1192Body Text Char

1193.IP \[bu] 2

1194Verbatim Char

1195.IP \[bu] 2

1196Footnote Reference

1197.IP \[bu] 2

1198Hyperlink

1199.PP

1200Table style:

1201.IP \[bu] 2

1202Table

1203.RE

1204.TP

1205ODT

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

1207ODT produced using pandoc.

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

1209used in the new ODT.

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

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

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

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

1214.RS

1215.PP

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

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

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

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

1220styles as you wish, and save the file.

1221.RE

1222.TP

1223PowerPoint

1224Templates included with Microsoft PowerPoint 2013 (either with

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

1226most templates derived from these.

1227.RS

1228.PP

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

1230following first four layouts:

1231.IP "1." 3

1232Title Slide

1233.IP "2." 3

1234Title and Content

1235.IP "3." 3

1236Section Header

1237.IP "4." 3

1238Two Content

1239.PP

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

1241these criteria.

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

1243check.)

1244.PP

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

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

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

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

1249.RE

1250.RE

1251.TP

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

1253Use the specified image as the EPUB cover.

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

1255height.

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

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

1258below).

1259.TP

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

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

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

1263For example:

1264.RS

1265.IP

1266.nf

1267\f[C]

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

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

1270\f[R]

1271.fi

1272.PP

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

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

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

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

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

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

1279UUID).

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

1281.PP

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

1283document can be used instead.

1284See below under EPUB Metadata.

1285.RE

1286.TP

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

1288Embed the specified font in the EPUB.

1289This option can be repeated to embed multiple fonts.

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

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

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

1293being interpreted by the shell.

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

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

1296.RS

1297.IP

1298.nf

1299\f[C]

1300\[at]font-face {

1301font-family: DejaVuSans;

1302font-style: normal;

1303font-weight: normal;

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

1305}

1306\[at]font-face {

1307font-family: DejaVuSans;

1308font-style: normal;

1309font-weight: bold;

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

1311}

1312\[at]font-face {

1313font-family: DejaVuSans;

1314font-style: italic;

1315font-weight: normal;

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

1317}

1318\[at]font-face {

1319font-family: DejaVuSans;

1320font-style: italic;

1321font-weight: bold;

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

1323}

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

1325\f[R]

1326.fi

1327.RE

1328.TP

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

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

1331\[dq]chapter\[dq] files.

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

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

1334way chapters and sections are displayed to users.

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

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

1337chapter level of 2 or 3.

1338.TP

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

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

1341EPUB-specific contents.

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

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

1344.TP

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

1346Determines how ipynb output cells are treated.

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

1348original are preserved.

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

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

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

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

1353.TP

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

1355Use the specified engine when producing PDF output.

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

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

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

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

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

1361specified here.

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

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

1364.RS

1365.IP \[bu] 2

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

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

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

1369.IP \[bu] 2

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

1371.IP \[bu] 2

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

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

1374introduction to PDF generation from HTML/CSS.)

1375.IP \[bu] 2

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

1377.RE

1378.TP

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

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

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

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

1383\f[C]latexmk\f[R]\[aq]s auxiliary files, use

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

1385Note that no check for duplicate options is done.

1386.SS Citation rendering

1387.TP

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

1389Set the \f[C]bibliography\f[R] field in the document\[aq]s metadata to

1390\f[I]FILE\f[R], overriding any value set in the metadata, and process

1391citations using \f[C]pandoc-citeproc\f[R].

1392(This is equivalent to

1393\f[C]--metadata bibliography=FILE --filter pandoc-citeproc\f[R].) If

1394\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] is also supplied,

1395\f[C]pandoc-citeproc\f[R] is not used, making this equivalent to

1396\f[C]--metadata bibliography=FILE\f[R].

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

1398added to bibliography.

1399.TP

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

1401Set the \f[C]csl\f[R] field in the document\[aq]s metadata to

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

1403(This is equivalent to \f[C]--metadata csl=FILE\f[R].) This option is

1404only relevant with \f[C]pandoc-citeproc\f[R].

1405.TP

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

1407Set the \f[C]citation-abbreviations\f[R] field in the document\[aq]s

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

1409(This is equivalent to

1410\f[C]--metadata citation-abbreviations=FILE\f[R].) This option is only

1411relevant with \f[C]pandoc-citeproc\f[R].

1412.TP

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

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

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

1416with PDF output.

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

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

1419.TP

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

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

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

1423with PDF output.

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

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

1426.SS Math rendering in HTML

1427.PP

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

1429characters.

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

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

1432from the surrounding text if needed.

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

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

1435options.

1436.TP

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

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

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

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

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

1442Then the MathJax JavaScript will render it.

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

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

1445inserted.

1446.TP

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

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

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

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

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

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

1453natively support MathML.

1454.TP

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

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

1457script that converts formulas to images.

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

1459For SVG images you can for example use

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

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

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

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

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

1465without native math support.

1466.TP

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

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

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

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

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

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

1473inserted.

1474.TP

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

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

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

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

1479So, the procedure is:

1480.RS

1481.IP

1482.nf

1483\f[C]

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

1485gladtex -d myfile-images myfile.htex

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

1487\f[R]

1488.fi

1489.RE

1490.SS Options for wrapper scripts

1491.TP

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

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

1494exit.

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

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

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

1498no output file was specified.

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

1500the order they appear.

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

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

1503of the line.

1504.TP

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

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

1507Regular pandoc options are not ignored.

1508Thus, for example,

1509.RS

1510.IP

1511.nf

1512\f[C]

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

1514\f[R]

1515.fi

1516.PP

1517is equivalent to

1518.IP

1519.nf

1520\f[C]

1521pandoc -o foo.html -s

1522\f[R]

1523.fi

1524.RE

1525.SH EXIT CODES

1526.PP

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

1528Nonzero exit codes have the following meanings:

1529.PP

1530.TS

1531tab(@);

1532r l.

1533T{

1534Code

1535T}@T{

1536Error

1537T}

1538_

1539T{

15403

1541T}@T{

1542PandocFailOnWarningError

1543T}

1544T{

15454

1546T}@T{

1547PandocAppError

1548T}

1549T{

15505

1551T}@T{

1552PandocTemplateError

1553T}

1554T{

15556

1556T}@T{

1557PandocOptionError

1558T}

1559T{

156021

1561T}@T{

1562PandocUnknownReaderError

1563T}

1564T{

156522

1566T}@T{

1567PandocUnknownWriterError

1568T}

1569T{

157023

1571T}@T{

1572PandocUnsupportedExtensionError

1573T}

1574T{

157531

1576T}@T{

1577PandocEpubSubdirectoryError

1578T}

1579T{

158043

1581T}@T{

1582PandocPDFError

1583T}

1584T{

158547

1586T}@T{

1587PandocPDFProgramNotFoundError

1588T}

1589T{

159061

1591T}@T{

1592PandocHttpError

1593T}

1594T{

159562

1596T}@T{

1597PandocShouldNeverHappenError

1598T}

1599T{

160063

1601T}@T{

1602PandocSomeError

1603T}

1604T{

160564

1606T}@T{

1607PandocParseError

1608T}

1609T{

161065

1611T}@T{

1612PandocParsecError

1613T}

1614T{

161566

1616T}@T{

1617PandocMakePDFError

1618T}

1619T{

162067

1621T}@T{

1622PandocSyntaxMapError

1623T}

1624T{

162583

1626T}@T{

1627PandocFilterError

1628T}

1629T{

163091

1631T}@T{

1632PandocMacroLoop

1633T}

1634T{

163592

1636T}@T{

1637PandocUTF8DecodingError

1638T}

1639T{

164093

1641T}@T{

1642PandocIpynbDecodingError

1643T}

1644T{

164597

1646T}@T{

1647PandocCouldNotFindDataFileError

1648T}

1649T{

165099

1651T}@T{

1652PandocResourceNotFound

1653T}

1654.TE

1655.SH DEFAULT FILES

1656.PP

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

1658options.

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

1660be used:

1661.IP

1662.nf

1663\f[C]

1664from: markdown+emoji

1665# reader: may be used instead of from:

1666to: html5

1667# writer: may be used instead of to:

1668

1669# leave blank for output to stdout:

1670output-file:

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

1672input-files:

1673- preface.md

1674- content.md

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

1676

1677template: letter

1678standalone: true

1679self-contained: false

1680

1681# note that structured variables may be specified:

1682variables:

1683 documentclass: book

1684 classoption:

1685 - twosides

1686 - draft

1687

1688# metadata values specified here are parsed as literal

1689# string text, not markdown:

1690metadata:

1691 author:

1692 - Sam Smith

1693 - Julie Liu

1694metadata-files:

1695- boilerplate.yaml

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

1697

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

1699include-before-body: []

1700include-after-body: []

1701include-in-header: []

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

1703

1704# filters will be assumed to be Lua filters if they have

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

1706# the filter type can also be specified explicitly, as shown:

1707filters:

1708- pandoc-citeproc

1709- wordcount.lua

1710- type: json

1711 path: foo.lua

1712

1713file-scope: false

1714

1715data-dir:

1716

1717# ERROR, WARNING, or INFO

1718verbosity: INFO

1719log-file: log.json

1720

1721# citeproc, natbib, or biblatex

1722cite-method: citeproc

1723# part, chapter, section, or default:

1724top-level-division: chapter

1725abbreviations:

1726

1727pdf-engine: pdflatex

1728pdf-engine-opts:

1729- \[dq]-shell-escape\[dq]

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

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

1732

1733# auto, preserve, or none

1734wrap: auto

1735columns: 78

1736dpi: 72

1737

1738extract-media: mediadir

1739

1740table-of-contents: true

1741toc-depth: 2

1742number-sections: false

1743# a list of offsets at each heading level

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

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

1746shift-heading-level-by: 1

1747section-divs: true

1748identifier-prefix: foo

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

1750strip-empty-paragraphs: true

1751# lf, crlf, or native

1752eol: lf

1753strip-comments: false

1754indented-code-classes: []

1755ascii: true

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

1757

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

1759highlight-style: pygments

1760syntax-definitions:

1761- c.xml

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

1763listings: false

1764

1765reference-doc: myref.docx

1766

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

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

1769html-math-method:

1770 method: mathjax

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

1772# none, references, or javascript

1773email-obfuscation: javascript

1774

1775tab-stop: 8

1776preserve-tabs: true

1777

1778incremental: false

1779slide-level: 2

1780

1781epub-subdirectory: EPUB

1782epub-metadata: meta.xml

1783epub-fonts:

1784- foobar.otf

1785epub-chapter-level: 1

1786epub-cover-image: cover.jpg

1787

1788reference-links: true

1789# block, section, or document

1790reference-location: block

1791atx-headers: false

1792

1793# accept, reject, or all

1794track-changes: accept

1795

1796html-q-tags: false

1797css:

1798- site.css

1799

1800# none, all, or best

1801ipynb-output: best

1802

1803# A list of two-element lists

1804request-headers:

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

1806

1807fail-if-warnings: false

1808dump-args: false

1809ignore-args: false

1810trace: false

1811\f[R]

1812.fi

1813.PP

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

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

1816.IP

1817.nf

1818\f[C]

1819verbosity: INFO

1820\f[R]

1821.fi

1822.PP

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

1824the user data directory and used from any directory.

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

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

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

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

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

1830.PP

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

1832.PP

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

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

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

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

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

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

1839defaults file, rather than replacing them.

1840.SH TEMPLATES

1841.PP

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

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

1844self-standing document.

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

1846.IP

1847.nf

1848\f[C]

1849pandoc -D *FORMAT*

1850\f[R]

1851.fi

1852.PP

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

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

1855option.

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

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

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

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

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

1861.IP \[bu] 2

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

1863template.

1864.IP \[bu] 2

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

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

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

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

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

1870.IP \[bu] 2

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

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

1873.PP

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

1875arbitrary information at any point in the file.

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

1877option.

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

1879document\[aq]s metadata, which can be set using either YAML metadata

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

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

1882See Variables below for a list of variables used in pandoc\[aq]s default

1883templates.

1884.PP

1885If you use custom templates, you may need to revise them as pandoc

1886changes.

1887We recommend tracking the changes in the default templates, and

1888modifying your custom templates accordingly.

1889An easy way to do this is to fork the pandoc-templates repository and

1890merge in changes after each pandoc release.

1891.SS Template syntax

1892.SS Comments

1893.PP

1894Anything between the sequence \f[C]$--\f[R] and the end of the line will

1895be treated as a comment and omitted from the output.

1896.SS Delimiters

1897.PP

1898To mark variables and control structures in the template, either

1899\f[C]$\f[R]...\f[C]$\f[R] or \f[C]${\f[R]...\f[C]}\f[R] may be used as

1900delimiters.

1901The styles may also be mixed in the same template, but the opening and

1902closing delimiter must match in each case.

1903The opening delimiter may be followed by one or more spaces or tabs,

1904which will be ignored.

1905The closing delimiter may be followed by one or more spaces or tabs,

1906which will be ignored.

1907.PP

1908To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].

1909.SS Interpolated variables

1910.PP

1911A slot for an interpolated variable is a variable name surrounded by

1912matched delimiters.

1913Variable names must begin with a letter and can contain letters,

1914numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].

1915The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],

1916\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may

1917not be used as variable names.

1918Examples:

1919.IP

1920.nf

1921\f[C]

1922$foo$

1923$foo.bar.baz$

1924$foo_bar.baz-bim$

1925$ foo $

1926${foo}

1927${foo.bar.baz}

1928${foo_bar.baz-bim}

1929${ foo }

1930\f[R]

1931.fi

1932.PP

1933Variable names with periods are used to get at structured variable

1934values.

1935So, for example, \f[C]employee.salary\f[R] will return the value of the

1936\f[C]salary\f[R] field of the object that is the value of the

1937\f[C]employee\f[R] field.

1938.IP \[bu] 2

1939If the value of the variable is simple value, it will be rendered

1940verbatim.

1941(Note that no escaping is done; the assumption is that the calling

1942program will escape the strings appropriately for the output format.)

1943.IP \[bu] 2

1944If the value is a list, the values will be concatenated.

1945.IP \[bu] 2

1946If the value is a map, the string \f[C]true\f[R] will be rendered.

1947.IP \[bu] 2

1948Every other value will be rendered as the empty string.

1949.SS Conditionals

1950.PP

1951A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched

1952delimiters) and ends with \f[C]endif\f[R] (enclosed in matched

1953delimiters).

1954It may optionally contain an \f[C]else\f[R] (enclosed in matched

1955delimiters).

1956The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty

1957value, otherwise the \f[C]else\f[R] section is used (if present).

1958Examples:

1959.IP

1960.nf

1961\f[C]

1962$if(foo)$bar$endif$

1963

1964$if(foo)$

1965 $foo$

1966$endif$

1967

1968$if(foo)$

1969part one

1970$else$

1971part two

1972$endif$

1973

1974${if(foo)}bar${endif}

1975

1976${if(foo)}

1977 ${foo}

1978${endif}

1979

1980${if(foo)}

1981${ foo.bar }

1982${else}

1983no foo!

1984${endif}

1985\f[R]

1986.fi

1987.PP

1988The keyword \f[C]elseif\f[R] may be used to simplify complex nested

1989conditionals:

1990.IP

1991.nf

1992\f[C]

1993$if(foo)$

1994XXX

1995$elseif(bar)$

1996YYY

1997$else$

1998ZZZ

1999$endif$

2000\f[R]

2001.fi

2002.SS For loops

2003.PP

2004A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched

2005delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched

2006delimiters.

2007.IP \[bu] 2

2008If \f[C]variable\f[R] is an array, the material inside the loop will be

2009evaluated repeatedly, with \f[C]variable\f[R] being set to each value of

2010the array in turn, and concatenated.

2011.IP \[bu] 2

2012If \f[C]variable\f[R] is a map, the material inside will be set to the

2013map.

2014.IP \[bu] 2

2015If the value of the associated variable is not an array or a map, a

2016single iteration will be performed on its value.

2017.PP

2018Examples:

2019.IP

2020.nf

2021\f[C]

2022$for(foo)$$foo$$sep$, $endfor$

2023

2024$for(foo)$

2025 - $foo.last$, $foo.first$

2026$endfor$

2027

2028${ for(foo.bar) }

2029 - ${ foo.bar.last }, ${ foo.bar.first }

2030${ endfor }

2031

2032$for(mymap)$

2033$it.name$: $it.office$

2034$endfor$

2035\f[R]

2036.fi

2037.PP

2038You may optionally specify a separator between consecutive values using

2039\f[C]sep\f[R] (enclosed in matched delimiters).

2040The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the

2041separator.

2042.IP

2043.nf

2044\f[C]

2045${ for(foo) }${ foo }${ sep }, ${ endfor }

2046\f[R]

2047.fi

2048.PP

2049Instead of using \f[C]variable\f[R] inside the loop, the special

2050anaphoric keyword \f[C]it\f[R] may be used.

2051.IP

2052.nf

2053\f[C]

2054${ for(foo.bar) }

2055 - ${ it.last }, ${ it.first }

2056${ endfor }

2057\f[R]

2058.fi

2059.SS Partials

2060.PP

2061Partials (subtemplates stored in different files) may be included by

2062using the name of the partial, followed by \f[C]()\f[R], for example:

2063.IP

2064.nf

2065\f[C]

2066${ styles() }

2067\f[R]

2068.fi

2069.PP

2070Partials will be sought in the directory containing the main template.

2071The file name will be assumed to have the same extension as the main

2072template if it lacks an extension.

2073When calling the partial, the full name including file extension can

2074also be used:

2075.IP

2076.nf

2077\f[C]

2078${ styles.html() }

2079\f[R]

2080.fi

2081.PP

2082(If a partial is not found in the directory of the template, it will

2083also be sought in the \f[C]templates\f[R] subdirectory of the user data

2084directory.)

2085.PP

2086Partials may optionally be applied to variables using a colon:

2087.IP

2088.nf

2089\f[C]

2090${ date:fancy() }

2091

2092${ articles:bibentry() }

2093\f[R]

2094.fi

2095.PP

2096If \f[C]articles\f[R] is an array, this will iterate over its values,

2097applying the partial \f[C]bibentry()\f[R] to each one.

2098So the second example above is equivalent to

2099.IP

2100.nf

2101\f[C]

2102${ for(articles) }

2103${ it:bibentry() }

2104${ endfor }

2105\f[R]

2106.fi

2107.PP

2108Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating

2109over partials.

2110In the above examples, the \f[C]bibentry\f[R] partial should contain

2111\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].

2112.PP

2113Final newlines are omitted from included partials.

2114.PP

2115Partials may include other partials.

2116.PP

2117A separator between values of an array may be specified in square

2118brackets, immediately after the variable name or partial:

2119.IP

2120.nf

2121\f[C]

2122${months[, ]}$

2123

2124${articles:bibentry()[; ]$

2125\f[R]

2126.fi

2127.PP

2128The separator in this case is literal and (unlike with \f[C]sep\f[R] in

2129an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or

2130other template directives.

2131.SS Nesting

2132.PP

2133To ensure that content is \[dq]nested,\[dq] that is, subsequent lines

2134indented, use the \f[C]\[ha]\f[R] directive:

2135.IP

2136.nf

2137\f[C]

2138$item.number$ $\[ha]$$item.description$ ($item.price$)

2139\f[R]

2140.fi

2141.PP

2142In this example, if \f[C]item.description\f[R] has multiple lines, they

2143will all be indented to line up with the first line:

2144.IP

2145.nf

2146\f[C]

214700123 A fine bottle of 18-year old

2148 Oban whiskey. ($148)

2149\f[R]

2150.fi

2151.PP

2152To nest multiple lines to the same level, align them with the

2153\f[C]\[ha]\f[R] directive in the template.

2154For example:

2155.IP

2156.nf

2157\f[C]

2158$item.number$ $\[ha]$$item.description$ ($item.price$)

2159 (Available til $item.sellby$.)

2160\f[R]

2161.fi

2162.PP

2163will produce

2164.IP

2165.nf

2166\f[C]

216700123 A fine bottle of 18-year old

2168 Oban whiskey. ($148)

2169 (Available til March 30, 2020.)

2170\f[R]

2171.fi

2172.PP

2173If a variable occurs by itself on a line, preceded by whitespace and not

2174followed by further text or directives on the same line, and the

2175variable\[aq]s value contains multiple lines, it will be nested

2176automatically.

2177.SS Breakable spaces

2178.PP

2179Normally, spaces in the template itself (as opposed to values of the

2180interpolated variables) are not breakable, but they can be made

2181breakable in part of the template by using the \f[C]\[ti]\f[R] keyword

2182(ended with another \f[C]\[ti]\f[R]).

2183.IP

2184.nf

2185\f[C]

2186$\[ti]$This long line may break if the document is rendered

2187with a short line length.$\[ti]$

2188\f[R]

2189.fi

2190.SS Pipes

2191.PP

2192A pipe transforms the value of a variable or partial.

2193Pipes are specified using a slash (\f[C]/\f[R]) between the variable

2194name (or partial) and the pipe name.

2195Example:

2196.IP

2197.nf

2198\f[C]

2199$for(name)$

2200$name/uppercase$

2201$endfor$

2202

2203$for(metadata/pairs)$

2204- $it.key$: $it.value$

2205$endfor$

2206

2207$employee:name()/uppercase$

2208\f[R]

2209.fi

2210.PP

2211Pipes may be chained:

2212.IP

2213.nf

2214\f[C]

2215$for(employees/pairs)$

2216$it.key/alpha/uppercase$. $it.name$

2217$endfor$

2218\f[R]

2219.fi

2220.PP

2221Some pipes take parameters:

2222.IP

2223.nf

2224\f[C]

2225|----------------------|------------|

2226$for(employee)$

2227$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$

2228$endfor$

2229|----------------------|------------|

2230\f[R]

2231.fi

2232.PP

2233Currently the following pipes are predefined:

2234.IP \[bu] 2

2235\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with

2236\f[C]key\f[R] and \f[C]value\f[R] fields.

2237If the original value was an array, the \f[C]key\f[R] will be the array

2238index, starting with 1.

2239.IP \[bu] 2

2240\f[C]uppercase\f[R]: Converts text to uppercase.

2241.IP \[bu] 2

2242\f[C]lowercase\f[R]: Converts text to lowercase.

2243.IP \[bu] 2

2244\f[C]length\f[R]: Returns the length of the value: number of characters

2245for a textual value, number of elements for a map or array.

2246.IP \[bu] 2

2247\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect

2248on other values.

2249.IP \[bu] 2

2250\f[C]first\f[R]: Returns the first value of an array, if applied to a

2251non-empty array; otherwise returns the original value.

2252.IP \[bu] 2

2253\f[C]last\f[R]: Returns the last value of an array, if applied to a

2254non-empty array; otherwise returns the original value.

2255.IP \[bu] 2

2256\f[C]rest\f[R]: Returns all but the first value of an array, if applied

2257to a non-empty array; otherwise returns the original value.

2258.IP \[bu] 2

2259\f[C]allbutlast\f[R]: Returns all but the last value of an array, if

2260applied to a non-empty array; otherwise returns the original value.

2261.IP \[bu] 2

2262\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).

2263.IP \[bu] 2

2264\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.

2265.IP \[bu] 2

2266\f[C]alpha\f[R]: Converts textual values that can be read as an integer

2267into lowercase alphabetic characters \f[C]a..z\f[R] (mod 26).

2268This can be used to get lettered enumeration from array indices.

2269To get uppercase letters, chain with \f[C]uppercase\f[R].

2270.IP \[bu] 2

2271\f[C]roman\f[R]: Converts textual values that can be read as an integer

2272into lowercase roman numerials.

2273This can be used to get lettered enumeration from array indices.

2274To get uppercase roman, chain with \f[C]uppercase\f[R].

2275.IP \[bu] 2

2276\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2277textual value in a block of width \f[C]n\f[R], aligned to the left, with

2278an optional left and right border.

2279Has no effect on other values.

2280This can be used to align material in tables.

2281Widths are positive integers indicating the number of characters.

2282Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and

2283\f[C]\[rs]\f[R] characters must be backslash-escaped.

2284.IP \[bu] 2

2285\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2286textual value in a block of width \f[C]n\f[R], aligned to the right, and

2287has no effect on other values.

2288.IP \[bu] 2

2289\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a

2290textual value in a block of width \f[C]n\f[R], aligned to the center,

2291and has no effect on other values.

2292.SS Variables

2293.SS Metadata variables

2294.TP

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

2296allow identification of basic aspects of the document.

2297Included in PDF metadata through LaTeX and ConTeXt.

2298These can be set through a pandoc title block, which allows for multiple

2299authors, or through a YAML metadata block:

2300.RS

2301.IP

2302.nf

2303\f[C]

2304---

2305author:

2306- Aristotle

2307- Peter Abelard

2308\&...

2309\f[R]

2310.fi

2311.PP

2312Note that if you just want to set PDF or HTML metadata, without

2313including a title block in the document itself, you can set the

2314\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]

2315variables.

2316(By default these are set automatically, based on \f[C]title\f[R],

2317\f[C]author\f[R], and \f[C]date\f[R].)

2318.RE

2319.TP

2320\f[B]\f[CB]subtitle\f[B]\f[R]

2321document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx

2322documents

2323.TP

2324\f[B]\f[CB]abstract\f[B]\f[R]

2325document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx

2326documents

2327.TP

2328\f[B]\f[CB]keywords\f[B]\f[R]

2329list of keywords to be included in HTML, PDF, ODT, pptx, docx and

2330AsciiDoc metadata; repeat as for \f[C]author\f[R], above

2331.TP

2332\f[B]\f[CB]subject\f[B]\f[R]

2333document subject, included in ODT, PDF, docx and pptx metadata

2334.TP

2335\f[B]\f[CB]description\f[B]\f[R]

2336document description, included in ODT, docx and pptx metadata.

2337Some applications show this as \f[C]Comments\f[R] metadata.

2338.TP

2339\f[B]\f[CB]category\f[B]\f[R]

2340document category, included in docx and pptx metadata

2341.PP

2342Additionally, any root-level string metadata, not included in ODT, docx

2343or pptx metadata is added as a \f[I]custom property\f[R].

2344The following YAML metadata block for instance:

2345.IP

2346.nf

2347\f[C]

2348---

2349title: \[aq]This is the title\[aq]

2350subtitle: \[dq]This is the subtitle\[dq]

2351author:

2352- Author One

2353- Author Two

2354description: |

2355 This is a long

2356 description.

2357

2358 It consists of two paragraphs

2359\&...

2360\f[R]

2361.fi

2362.PP

2363will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]

2364as standard document properties and \f[C]subtitle\f[R] as a custom

2365property when converting to docx, ODT or pptx.

2366.SS Language variables

2367.TP

2368\f[B]\f[CB]lang\f[B]\f[R]

2369identifies the main language of the document using IETF language tags

2370(following the BCP 47 standard), such as \f[C]en\f[R] or

2371\f[C]en-GB\f[R].

2372The Language subtag lookup tool can look up or verify these tags.

2373This affects most formats, and controls hyphenation in PDF output when

2374using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or

2375ConTeXt.

2376.RS

2377.PP

2378Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to

2379switch the language:

2380.IP

2381.nf

2382\f[C]

2383---

2384lang: en-GB

2385\&...

2386

2387Text in the main document language (British English).

2388

2389::: {lang=fr-CA}

2390> Cette citation est \['e]crite en fran\[,c]ais canadien.

2391:::

2392

2393More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}

2394\f[R]

2395.fi

2396.RE

2397.TP

2398\f[B]\f[CB]dir\f[B]\f[R]

2399the base script direction, either \f[C]rtl\f[R] (right-to-left) or

2400\f[C]ltr\f[R] (left-to-right).

2401.RS

2402.PP

2403For bidirectional documents, native pandoc \f[C]span\f[R]s and

2404\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or

2405\f[C]ltr\f[R]) can be used to override the base direction in some output

2406formats.

2407This may not always be necessary if the final renderer (e.g.

2408the browser, when generating HTML) supports the Unicode Bidirectional

2409Algorithm.

2410.PP

2411When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]

2412engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).

2413.RE

2414.SS Variables for HTML math

2415.TP

2416\f[B]\f[CB]classoption\f[B]\f[R]

2417when using KaTeX, you can render display math equations flush left using

2418YAML metadata or with \f[C]-M classoption=fleqn\f[R].

2419.SS Variables for HTML slides

2420.PP

2421These affect HTML output when producing slide shows with pandoc.

2422.PP

2423All reveal.js configuration options are available as variables.

2424To turn off boolean flags that default to true in reveal.js, use

2425\f[C]0\f[R].

2426.TP

2427\f[B]\f[CB]revealjs-url\f[B]\f[R]

2428base URL for reveal.js documents (defaults to

2429\f[C]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R])

2430.TP

2431\f[B]\f[CB]s5-url\f[B]\f[R]

2432base URL for S5 documents (defaults to \f[C]s5/default\f[R])

2433.TP

2434\f[B]\f[CB]slidy-url\f[B]\f[R]

2435base URL for Slidy documents (defaults to

2436\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])

2437.TP

2438\f[B]\f[CB]slideous-url\f[B]\f[R]

2439base URL for Slideous documents (defaults to \f[C]slideous\f[R])

2440.TP

2441\f[B]\f[CB]title-slide-attributes\f[B]\f[R]

2442additional attributes for the title slide of reveal.js slide shows.

2443See background in reveal.js and beamer for an example.

2444.SS Variables for Beamer slides

2445.PP

2446These variables change the appearance of PDF slides using

2447\f[C]beamer\f[R].

2448.TP

2449\f[B]\f[CB]aspectratio\f[B]\f[R]

2450slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for

245116:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]

2452for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)

2453.TP

2454\f[B]\f[CB]beamerarticle\f[B]\f[R]

2455produce an article from Beamer slides

2456.TP

2457\f[B]\f[CB]beameroption\f[B]\f[R]

2458add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]

2459.TP

2460\f[B]\f[CB]institute\f[B]\f[R]

2461author affiliations: can be a list when there are multiple authors

2462.TP

2463\f[B]\f[CB]logo\f[B]\f[R]

2464logo image for slides

2465.TP

2466\f[B]\f[CB]navigation\f[B]\f[R]

2467controls navigation symbols (default is \f[C]empty\f[R] for no

2468navigation symbols; other valid values are \f[C]frame\f[R],

2469\f[C]vertical\f[R], and \f[C]horizontal\f[R])

2470.TP

2471\f[B]\f[CB]section-titles\f[B]\f[R]

2472enables \[dq]title pages\[dq] for new sections (default is true)

2473.TP

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

2475beamer themes

2476.TP

2477\f[B]\f[CB]themeoptions\f[B]\f[R]

2478options for LaTeX beamer themes (a list).

2479.TP

2480\f[B]\f[CB]titlegraphic\f[B]\f[R]

2481image for title slide

2482.SS Variables for PowerPoint

2483.PP

2484These variables control the visual aspects of a slide show that are not

2485easily controlled via templates.

2486.TP

2487\f[B]\f[CB]monofont\f[B]\f[R]

2488font to use for code.

2489.SS Variables for LaTeX

2490.PP

2491Pandoc uses these variables when creating a PDF with a LaTeX engine.

2492.SS Layout

2493.TP

2494\f[B]\f[CB]block-headings\f[B]\f[R]

2495make \f[C]\[rs]paragraph\f[R] and \f[C]\[rs]subparagraph\f[R] (fourth-

2496and fifth-level headings, or fifth- and sixth-level with book classes)

2497free-standing rather than run-in; requires further formatting to

2498distinguish from \f[C]\[rs]subsubsection\f[R] (third- or fourth-level

2499headings).

2500Instead of using this option, KOMA-Script can adjust headings more

2501extensively:

2502.RS

2503.IP

2504.nf

2505\f[C]

2506---

2507documentclass: scrartcl

2508header-includes: |

2509 \[rs]RedeclareSectionCommand[

2510 beforeskip=-10pt plus -2pt minus -1pt,

2511 afterskip=1sp plus -1sp minus 1sp,

2512 font=\[rs]normalfont\[rs]itshape]{paragraph}

2513 \[rs]RedeclareSectionCommand[

2514 beforeskip=-10pt plus -2pt minus -1pt,

2515 afterskip=1sp plus -1sp minus 1sp,

2516 font=\[rs]normalfont\[rs]scshape,

2517 indent=0pt]{subparagraph}

2518\&...

2519\f[R]

2520.fi

2521.RE

2522.TP

2523\f[B]\f[CB]classoption\f[B]\f[R]

2524option for document class, e.g.

2525\f[C]oneside\f[R]; repeat for multiple options:

2526.RS

2527.IP

2528.nf

2529\f[C]

2530---

2531classoption:

2532- twocolumn

2533- landscape

2534\&...

2535\f[R]

2536.fi

2537.RE

2538.TP

2539\f[B]\f[CB]documentclass\f[B]\f[R]

2540document class: usually one of the standard classes, \f[C]article\f[R],

2541\f[C]book\f[R], and \f[C]report\f[R]; the KOMA-Script equivalents,

2542\f[C]scrartcl\f[R], \f[C]scrbook\f[R], and \f[C]scrreprt\f[R], which

2543default to smaller margins; or \f[C]memoir\f[R]

2544.TP

2545\f[B]\f[CB]geometry\f[B]\f[R]

2546option for \f[C]geometry\f[R] package, e.g.

2547\f[C]margin=1in\f[R]; repeat for multiple options:

2548.RS

2549.IP

2550.nf

2551\f[C]

2552---

2553geometry:

2554- top=30mm

2555- left=20mm

2556- heightrounded

2557\&...

2558\f[R]

2559.fi

2560.RE

2561.TP

2562\f[B]\f[CB]hyperrefoptions\f[B]\f[R]

2563option for \f[C]hyperref\f[R] package, e.g.

2564\f[C]linktoc=all\f[R]; repeat for multiple options:

2565.RS

2566.IP

2567.nf

2568\f[C]

2569---

2570hyperrefoptions:

2571- linktoc=all

2572- pdfwindowui

2573- pdfpagemode=FullScreen

2574\&...

2575\f[R]

2576.fi

2577.RE

2578.TP

2579\f[B]\f[CB]indent\f[B]\f[R]

2580uses document class settings for indentation (the default LaTeX template

2581otherwise removes indentation and adds space between paragraphs)

2582.TP

2583\f[B]\f[CB]linestretch\f[B]\f[R]

2584adjusts line spacing using the \f[C]setspace\f[R] package, e.g.

2585\f[C]1.25\f[R], \f[C]1.5\f[R]

2586.TP

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

2588sets margins if \f[C]geometry\f[R] is not used (otherwise

2589\f[C]geometry\f[R] overrides these)

2590.TP

2591\f[B]\f[CB]pagestyle\f[B]\f[R]

2592control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports

2593\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page

2594numbers), and \f[C]headings\f[R] (section titles in running heads)

2595.TP

2596\f[B]\f[CB]papersize\f[B]\f[R]

2597paper size, e.g.

2598\f[C]letter\f[R], \f[C]a4\f[R]

2599.TP

2600\f[B]\f[CB]secnumdepth\f[B]\f[R]

2601numbering depth for sections (with \f[C]--number-sections\f[R] option or

2602\f[C]numbersections\f[R] variable)

2603.SS Fonts

2604.TP

2605\f[B]\f[CB]fontenc\f[B]\f[R]

2606allows font encoding to be specified through \f[C]fontenc\f[R] package

2607(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font

2608encodings guide)

2609.TP

2610\f[B]\f[CB]fontfamily\f[B]\f[R]

2611font package for use with \f[C]pdflatex\f[R]: TeX Live includes many

2612options, documented in the LaTeX Font Catalogue.

2613The default is Latin Modern.

2614.TP

2615\f[B]\f[CB]fontfamilyoptions\f[B]\f[R]

2616options for package used as \f[C]fontfamily\f[R]; repeat for multiple

2617options.

2618For example, to use the Libertine font with proportional lowercase

2619(old-style) figures through the \f[C]libertinus\f[R] package:

2620.RS

2621.IP

2622.nf

2623\f[C]

2624---

2625fontfamily: libertinus

2626fontfamilyoptions:

2627- osf

2628- p

2629\&...

2630\f[R]

2631.fi

2632.RE

2633.TP

2634\f[B]\f[CB]fontsize\f[B]\f[R]

2635font size for body text.

2636The standard classes allow 10pt, 11pt, and 12pt.

2637To use another size, set \f[C]documentclass\f[R] to one of the

2638KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].

2639.TP

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

2641font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take

2642the name of any system font, using the \f[C]fontspec\f[R] package.

2643\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.

2644.TP

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

2646options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],

2647\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in

2648\f[C]xelatex\f[R] and \f[C]lualatex\f[R].

2649Allow for any choices available through \f[C]fontspec\f[R]; repeat for

2650multiple options.

2651For example, to use the TeX Gyre version of Palatino with lowercase

2652figures:

2653.RS

2654.IP

2655.nf

2656\f[C]

2657---

2658mainfont: TeX Gyre Pagella

2659mainfontoptions:

2660- Numbers=Lowercase

2661- Numbers=Proportional

2662\&...

2663\f[R]

2664.fi

2665.RE

2666.TP

2667\f[B]\f[CB]microtypeoptions\f[B]\f[R]

2668options to pass to the microtype package

2669.SS Links

2670.TP

2671\f[B]\f[CB]colorlinks\f[B]\f[R]

2672add color to link text; automatically enabled if any of

2673\f[C]linkcolor\f[R], \f[C]filecolor\f[R], \f[C]citecolor\f[R],

2674\f[C]urlcolor\f[R], or \f[C]toccolor\f[R] are set

2675.TP

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

2677color for internal links, external links, citation links, linked URLs,

2678and links in table of contents, respectively: uses options allowed by

2679\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],

2680\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists

2681.TP

2682\f[B]\f[CB]links-as-notes\f[B]\f[R]

2683causes links to be printed as footnotes

2684.SS Front matter

2685.TP

2686\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]

2687include list of figures, list of tables

2688.TP

2689\f[B]\f[CB]thanks\f[B]\f[R]

2690contents of acknowledgments footnote after document title

2691.TP

2692\f[B]\f[CB]toc\f[B]\f[R]

2693include table of contents (can also be set using

2694\f[C]--toc/--table-of-contents\f[R])

2695.TP

2696\f[B]\f[CB]toc-depth\f[B]\f[R]

2697level of section to include in table of contents

2698.SS BibLaTeX Bibliographies

2699.PP

2700These variables function when using BibLaTeX for citation rendering.

2701.TP

2702\f[B]\f[CB]biblatexoptions\f[B]\f[R]

2703list of options for biblatex

2704.TP

2705\f[B]\f[CB]biblio-style\f[B]\f[R]

2706bibliography style, when used with \f[C]--natbib\f[R] and

2707\f[C]--biblatex\f[R].

2708.TP

2709\f[B]\f[CB]biblio-title\f[B]\f[R]

2710bibliography title, when used with \f[C]--natbib\f[R] and

2711\f[C]--biblatex\f[R].

2712.TP

2713\f[B]\f[CB]bibliography\f[B]\f[R]

2714bibliography to use for resolving references

2715.TP

2716\f[B]\f[CB]natbiboptions\f[B]\f[R]

2717list of options for natbib

2718.SS Variables for ConTeXt

2719.PP

2720Pandoc uses these variables when creating a PDF with ConTeXt.

2721.TP

2722\f[B]\f[CB]fontsize\f[B]\f[R]

2723font size for body text (e.g.

2724\f[C]10pt\f[R], \f[C]12pt\f[R])

2725.TP

2726\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]

2727text to be placed in running header or footer (see ConTeXt Headers and

2728Footers); repeat up to four times for different placement

2729.TP

2730\f[B]\f[CB]indenting\f[B]\f[R]

2731controls indentation of paragraphs, e.g.

2732\f[C]yes,small,next\f[R] (see ConTeXt Indentation); repeat for multiple

2733options

2734.TP

2735\f[B]\f[CB]interlinespace\f[B]\f[R]

2736adjusts line spacing, e.g.

2737\f[C]4ex\f[R] (using \f[C]setupinterlinespace\f[R]); repeat for multiple

2738options

2739.TP

2740\f[B]\f[CB]layout\f[B]\f[R]

2741options for page margins and text arrangement (see ConTeXt Layout);

2742repeat for multiple options

2743.TP

2744\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]

2745color for links outside and inside a page, e.g.

2746\f[C]red\f[R], \f[C]blue\f[R] (see ConTeXt Color)

2747.TP

2748\f[B]\f[CB]linkstyle\f[B]\f[R]

2749typeface style for links, e.g.

2750\f[C]normal\f[R], \f[C]bold\f[R], \f[C]slanted\f[R],

2751\f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R], \f[C]small\f[R]

2752.TP

2753\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]

2754include list of figures, list of tables

2755.TP

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

2757font families: take the name of any system font (see ConTeXt Font

2758Switching)

2759.TP

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

2761sets margins, if \f[C]layout\f[R] is not used (otherwise

2762\f[C]layout\f[R] overrides these)

2763.TP

2764\f[B]\f[CB]pagenumbering\f[B]\f[R]

2765page number style and location (using \f[C]setuppagenumbering\f[R]);

2766repeat for multiple options

2767.TP

2768\f[B]\f[CB]papersize\f[B]\f[R]

2769paper size, e.g.

2770\f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R] (see ConTeXt Paper

2771Setup); repeat for multiple options

2772.TP

2773\f[B]\f[CB]pdfa\f[B]\f[R]

2774adds to the preamble the setup necessary to generate PDF/A of the type

2775specified, e.g.

2776\f[C]1a:2005\f[R], \f[C]2a\f[R].

2777If no type is specified (i.e.

2778the value is set to True, by e.g.

2779\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata

2780block), \f[C]1b:2005\f[R] will be used as default, for reasons of

2781backwards compatibility.

2782Using \f[C]--variable=pdfa\f[R] without specified value is not

2783supported.

2784To successfully generate PDF/A the required ICC color profiles have to

2785be available and the content and all included files (such as images)

2786have to be standard conforming.

2787The ICC profiles and output intent may be specified using the variables

2788\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].

2789See also ConTeXt PDFA for more details.

2790.TP

2791\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]

2792when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile

2793to use in the PDF, e.g.

2794\f[C]default.cmyk\f[R].

2795If left unspecified, \f[C]sRGB.icc\f[R] is used as default.

2796May be repeated to include multiple profiles.

2797Note that the profiles have to be available on the system.

2798They can be obtained from ConTeXt ICC Profiles.

2799.TP

2800\f[B]\f[CB]pdfaintent\f[B]\f[R]

2801when used in conjunction with \f[C]pdfa\f[R], specifies the output

2802intent for the colors, e.g.

2803\f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If left

2804unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.

2805.TP

2806\f[B]\f[CB]toc\f[B]\f[R]

2807include table of contents (can also be set using

2808\f[C]--toc/--table-of-contents\f[R])

2809.TP

2810\f[B]\f[CB]whitespace\f[B]\f[R]

2811spacing between paragraphs, e.g.

2812\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])

2813.TP

2814\f[B]\f[CB]includesource\f[B]\f[R]

2815include all source documents as file attachments in the PDF file

2816.SS Variables for \f[C]wkhtmltopdf\f[R]

2817.PP

2818Pandoc uses these variables when creating a PDF with

2819\f[C]wkhtmltopdf\f[R].

2820The \f[C]--css\f[R] option also affects the output.

2821.TP

2822\f[B]\f[CB]footer-html\f[B]\f[R], \f[B]\f[CB]header-html\f[B]\f[R]

2823add information to the header and footer

2824.TP

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

2826set the page margins

2827.TP

2828\f[B]\f[CB]papersize\f[B]\f[R]

2829sets the PDF paper size

2830.SS Variables for man pages

2831.TP

2832\f[B]\f[CB]adjusting\f[B]\f[R]

2833adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center

2834(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins

2835.TP

2836\f[B]\f[CB]footer\f[B]\f[R]

2837footer in man pages

2838.TP

2839\f[B]\f[CB]header\f[B]\f[R]

2840header in man pages

2841.TP

2842\f[B]\f[CB]hyphenate\f[B]\f[R]

2843if \f[C]true\f[R] (the default), hyphenation will be used

2844.TP

2845\f[B]\f[CB]section\f[B]\f[R]

2846section number in man pages

2847.SS Variables for ms

2848.TP

2849\f[B]\f[CB]fontfamily\f[B]\f[R]

2850font family (e.g.

2851\f[C]T\f[R] or \f[C]P\f[R])

2852.TP

2853\f[B]\f[CB]indent\f[B]\f[R]

2854paragraph indent (e.g.

2855\f[C]2m\f[R])

2856.TP

2857\f[B]\f[CB]lineheight\f[B]\f[R]

2858line height (e.g.

2859\f[C]12p\f[R])

2860.TP

2861\f[B]\f[CB]pointsize\f[B]\f[R]

2862point size (e.g.

2863\f[C]10p\f[R])

2864.SS Variables set automatically

2865.PP

2866Pandoc sets these variables automatically in response to options or

2867document contents; users can also modify them.

2868These vary depending on the output format, and include the following:

2869.TP

2870\f[B]\f[CB]body\f[B]\f[R]

2871body of document

2872.TP

2873\f[B]\f[CB]date-meta\f[B]\f[R]

2874the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included

2875in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,

2876s5, slideous, slidy).

2877The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],

2878\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),

2879\f[C]dd MM yyyy\f[R] (e.g.

2880either \f[C]02 Apr 2018\f[R] or \f[C]02 April 2018\f[R]),

2881\f[C]MM dd, yyyy\f[R] (e.g.

2882\f[C]Apr. 02, 2018\f[R] or

2883\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,

2884\f[C]201804\f[R] or \f[C]2018\f[R]).

2885.TP

2886\f[B]\f[CB]header-includes\f[B]\f[R]

2887contents specified by \f[C]-H/--include-in-header\f[R] (may have

2888multiple values)

2889.TP

2890\f[B]\f[CB]include-before\f[B]\f[R]

2891contents specified by \f[C]-B/--include-before-body\f[R] (may have

2892multiple values)

2893.TP

2894\f[B]\f[CB]include-after\f[B]\f[R]

2895contents specified by \f[C]-A/--include-after-body\f[R] (may have

2896multiple values)

2897.TP

2898\f[B]\f[CB]meta-json\f[B]\f[R]

2899JSON representation of all of the document\[aq]s metadata.

2900Field values are transformed to the selected output format.

2901.TP

2902\f[B]\f[CB]numbersections\f[B]\f[R]

2903non-null value if \f[C]-N/--number-sections\f[R] was specified

2904.TP

2905\f[B]\f[CB]sourcefile\f[B]\f[R], \f[B]\f[CB]outputfile\f[B]\f[R]

2906source and destination filenames, as given on the command line.

2907\f[C]sourcefile\f[R] can also be a list if input comes from multiple

2908files, or empty if input is from stdin.

2909You can use the following snippet in your template to distinguish them:

2910.RS

2911.IP

2912.nf

2913\f[C]

2914$if(sourcefile)$

2915$for(sourcefile)$

2916$sourcefile$

2917$endfor$

2918$else$

2919(stdin)

2920$endif$

2921\f[R]

2922.fi

2923.PP

2924Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the

2925terminal.

2926.PP

2927If you need absolute paths, use e.g.

2928\f[C]$curdir$/$sourcefile$\f[R].

2929.RE

2930.TP

2931\f[B]\f[CB]curdir\f[B]\f[R]

2932working directory from which pandoc is run.

2933.TP

2934\f[B]\f[CB]toc\f[B]\f[R]

2935non-null value if \f[C]--toc/--table-of-contents\f[R] was specified

2936.TP

2937\f[B]\f[CB]toc-title\f[B]\f[R]

2938title of table of contents (works only with EPUB, HTML, opendocument,

2939odt, docx, pptx, beamer, LaTeX)

2940.SH EXTENSIONS

2941.PP

2942The behavior of some of the readers and writers can be adjusted by

2943enabling or disabling various extensions.

2944.PP

2945An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format

2946name and disabled by adding \f[C]-EXTENSION\f[R].

2947For example, \f[C]--from markdown_strict+footnotes\f[R] is strict

2948Markdown with footnotes enabled, while

2949\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[aq]s Markdown

2950without footnotes or pipe tables.

2951.PP

2952The markdown reader and writer make by far the most use of extensions.

2953Extensions only used by them are therefore covered in the section

2954Pandoc\[aq]s Markdown below (See Markdown variants for

2955\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions

2956that also work for other formats are covered.

2957.PP

2958Note that markdown extensions added to the \f[C]ipynb\f[R] format affect

2959Markdown cells in Jupyter notebooks (as do command-line options like

2960\f[C]--atx-headers\f[R]).

2961.SS Typography

2962.SS Extension: \f[C]smart\f[R]

2963.PP

2964Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,

2965\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.

2966Nonbreaking spaces are inserted after certain abbreviations, such as

2967\[dq]Mr.\[dq]

2968.PP

2969This extension can be enabled/disabled for the following formats:

2970.TP

2971input formats

2972\f[C]markdown\f[R], \f[C]commonmark\f[R], \f[C]latex\f[R],

2973\f[C]mediawiki\f[R], \f[C]org\f[R], \f[C]rst\f[R], \f[C]twiki\f[R]

2974.TP

2975output formats

2976\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R], \f[C]rst\f[R]

2977.TP

2978enabled by default in

2979\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R] (both input and

2980output)

2981.PP

2982Note: If you are \f[I]writing\f[R] Markdown, then the \f[C]smart\f[R]

2983extension has the reverse effect: what would have been curly quotes

2984comes out straight.

2985.PP

2986In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for

2987quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for

2988double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)

2989and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).

2990If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse

2991these characters literally.

2992In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the

2993ligatures when possible; if \f[C]smart\f[R] is disabled pandoc will use

2994unicode quotation mark and dash characters.

2995.SS Headings and sections

2996.SS Extension: \f[C]auto_identifiers\f[R]

2997.PP

2998A heading without an explicitly specified identifier will be

2999automatically assigned a unique identifier based on the heading text.

3000.PP

3001This extension can be enabled/disabled for the following formats:

3002.TP

3003input formats

3004\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]rst\f[R], \f[C]mediawiki\f[R],

3005\f[C]textile\f[R]

3006.TP

3007output formats

3008\f[C]markdown\f[R], \f[C]muse\f[R]

3009.TP

3010enabled by default in

3011\f[C]markdown\f[R], \f[C]muse\f[R]

3012.PP

3013The default algorithm used to derive the identifier from the heading

3014text is:

3015.IP \[bu] 2

3016Remove all formatting, links, etc.

3017.IP \[bu] 2

3018Remove all footnotes.

3019.IP \[bu] 2

3020Remove all non-alphanumeric characters, except underscores, hyphens, and

3021periods.

3022.IP \[bu] 2

3023Replace all spaces and newlines with hyphens.

3024.IP \[bu] 2

3025Convert all alphabetic characters to lowercase.

3026.IP \[bu] 2

3027Remove everything up to the first letter (identifiers may not begin with

3028a number or punctuation mark).

3029.IP \[bu] 2

3030If nothing is left after this, use the identifier \f[C]section\f[R].

3031.PP

3032Thus, for example,

3033.PP

3034.TS

3035tab(@);

3036l l.

3037T{

3038Heading

3039T}@T{

3040Identifier

3041T}

3042_

3043T{

3044\f[C]Heading identifiers in HTML\f[R]

3045T}@T{

3046\f[C]heading-identifiers-in-html\f[R]

3047T}

3048T{

3049\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]

3050T}@T{

3051\f[C]ma\[^i]tre-dh\[^o]tel\f[R]

3052T}

3053T{

3054\f[C]*Dogs*?--in *my* house?\f[R]

3055T}@T{

3056\f[C]dogs--in-my-house\f[R]

3057T}

3058T{

3059\f[C][HTML], [S5], or [RTF]?\f[R]

3060T}@T{

3061\f[C]html-s5-or-rtf\f[R]

3062T}

3063T{

3064\f[C]3. Applications\f[R]

3065T}@T{

3066\f[C]applications\f[R]

3067T}

3068T{

3069\f[C]33\f[R]

3070T}@T{

3071\f[C]section\f[R]

3072T}

3073.TE

3074.PP

3075These rules should, in most cases, allow one to determine the identifier

3076from the heading text.

3077The exception is when several headings have the same text; in this case,

3078the first will get an identifier as described above; the second will get

3079the same identifier with \f[C]-1\f[R] appended; the third with

3080\f[C]-2\f[R]; and so on.

3081.PP

3082(However, a different algorithm is used if

3083\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)

3084.PP

3085These identifiers are used to provide link targets in the table of

3086contents generated by the \f[C]--toc|--table-of-contents\f[R] option.

3087They also make it easy to provide links from one section of a document

3088to another.

3089A link to this section, for example, might look like this:

3090.IP

3091.nf

3092\f[C]

3093See the section on

3094[heading identifiers](#heading-identifiers-in-html-latex-and-context).

3095\f[R]

3096.fi

3097.PP

3098Note, however, that this method of providing links to sections works

3099only in HTML, LaTeX, and ConTeXt formats.

3100.PP

3101If the \f[C]--section-divs\f[R] option is specified, then each section

3102will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if

3103\f[C]html4\f[R] was specified), and the identifier will be attached to

3104the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than

3105the heading itself.

3106This allows entire sections to be manipulated using JavaScript or

3107treated differently in CSS.

3108.SS Extension: \f[C]ascii_identifiers\f[R]

3109.PP

3110Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure

3111ASCII.

3112Accents are stripped off of accented Latin letters, and non-Latin

3113letters are omitted.

3114.SS Extension: \f[C]gfm_auto_identifiers\f[R]

3115.PP

3116Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to

3117GitHub\[aq]s method.

3118Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to

3119lowercase characters, and punctuation characters other than \f[C]-\f[R]

3120and \f[C]_\f[R] are removed.

3121Emojis are replaced by their names.

3122.SS Math Input

3123.PP

3124The extensions \f[C]tex_math_dollars\f[R],

3125\f[C]tex_math_single_backslash\f[R], and

3126\f[C]tex_math_double_backslash\f[R] are described in the section about

3127Pandoc\[aq]s Markdown.

3128.PP

3129However, they can also be used with HTML input.

3130This is handy for reading web pages formatted using MathJax, for

3131example.

3132.SS Raw HTML/TeX

3133.PP

3134The following extensions (especially how they affect Markdown

3135input/output) are also described in more detail in their respective

3136sections of Pandoc\[aq]s Markdown.

3137.SS Extension: \f[C]raw_html\f[R]

3138.PP

3139When converting from HTML, parse elements to raw HTML which are not

3140representable in pandoc\[aq]s AST.

3141By default, this is disabled for HTML input.

3142.SS Extension: \f[C]raw_tex\f[R]

3143.PP

3144Allows raw LaTeX, TeX, and ConTeXt to be included in a document.

3145.PP

3146This extension can be enabled/disabled for the following formats (in

3147addition to \f[C]markdown\f[R]):

3148.TP

3149input formats

3150\f[C]latex\f[R], \f[C]org\f[R], \f[C]textile\f[R], \f[C]html\f[R]

3151(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only),

3152\f[C]ipynb\f[R]

3153.TP

3154output formats

3155\f[C]textile\f[R], \f[C]commonmark\f[R]

3156.PP

3157Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and

3158\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data

3159with mime type \f[C]text/html\f[R] in output cells.

3160Since the \f[C]ipynb\f[R] reader attempts to preserve the richest

3161possible outputs when several options are given, you will get best

3162results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when

3163converting to formats like \f[C]docx\f[R] which don\[aq]t allow raw

3164\f[C]html\f[R] or \f[C]tex\f[R].

3165.SS Extension: \f[C]native_divs\f[R]

3166.PP

3167This extension is enabled by default for HTML input.

3168This means that \f[C]div\f[R]s are parsed to pandoc native elements.

3169(Alternatively, you can parse them to raw HTML using

3170\f[C]-f html-native_divs+raw_html\f[R].)

3171.PP

3172When converting HTML to Markdown, for example, you may want to drop all

3173\f[C]div\f[R]s and \f[C]span\f[R]s:

3174.IP

3175.nf

3176\f[C]

3177pandoc -f html-native_divs-native_spans -t markdown

3178\f[R]

3179.fi

3180.SS Extension: \f[C]native_spans\f[R]

3181.PP

3182Analogous to \f[C]native_divs\f[R] above.

3183.SS Literate Haskell support

3184.SS Extension: \f[C]literate_haskell\f[R]

3185.PP

3186Treat the document as literate Haskell source.

3187.PP

3188This extension can be enabled/disabled for the following formats:

3189.TP

3190input formats

3191\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R]

3192.TP

3193output formats

3194\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R], \f[C]html\f[R]

3195.PP

3196If you append \f[C]+lhs\f[R] (or \f[C]+literate_haskell\f[R]) to one of

3197the formats above, pandoc will treat the document as literate Haskell

3198source.

3199This means that

3200.IP \[bu] 2

3201In Markdown input, \[dq]bird track\[dq] sections will be parsed as

3202Haskell code rather than block quotations.

3203Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]

3204will also be treated as Haskell code.

3205For ATX-style headings the character \[aq]=\[aq] will be used instead of

3206\[aq]#\[aq].

3207.IP \[bu] 2

3208In Markdown output, code blocks with classes \f[C]haskell\f[R] and

3209\f[C]literate\f[R] will be rendered using bird tracks, and block

3210quotations will be indented one space, so they will not be treated as

3211Haskell code.

3212In addition, headings will be rendered setext-style (with underlines)

3213rather than ATX-style (with \[aq]#\[aq] characters).

3214(This is because ghc treats \[aq]#\[aq] characters in column 1 as

3215introducing line numbers.)

3216.IP \[bu] 2

3217In restructured text input, \[dq]bird track\[dq] sections will be parsed

3218as Haskell code.

3219.IP \[bu] 2

3220In restructured text output, code blocks with class \f[C]haskell\f[R]

3221will be rendered using bird tracks.

3222.IP \[bu] 2

3223In LaTeX input, text in \f[C]code\f[R] environments will be parsed as

3224Haskell code.

3225.IP \[bu] 2

3226In LaTeX output, code blocks with class \f[C]haskell\f[R] will be

3227rendered inside \f[C]code\f[R] environments.

3228.IP \[bu] 2

3229In HTML output, code blocks with class \f[C]haskell\f[R] will be

3230rendered with class \f[C]literatehaskell\f[R] and bird tracks.

3231.PP

3232Examples:

3233.IP

3234.nf

3235\f[C]

3236pandoc -f markdown+lhs -t html

3237\f[R]

3238.fi

3239.PP

3240reads literate Haskell source formatted with Markdown conventions and

3241writes ordinary HTML (without bird tracks).

3242.IP

3243.nf

3244\f[C]

3245pandoc -f markdown+lhs -t html+lhs

3246\f[R]

3247.fi

3248.PP

3249writes HTML with the Haskell code in bird tracks, so it can be copied

3250and pasted as literate Haskell source.

3251.PP

3252Note that GHC expects the bird tracks in the first column, so indented

3253literate code blocks (e.g.

3254inside an itemized environment) will not be picked up by the Haskell

3255compiler.

3256.SS Other extensions

3257.SS Extension: \f[C]empty_paragraphs\f[R]

3258.PP

3259Allows empty paragraphs.

3260By default empty paragraphs are omitted.

3261.PP

3262This extension can be enabled/disabled for the following formats:

3263.TP

3264input formats

3265\f[C]docx\f[R], \f[C]html\f[R]

3266.TP

3267output formats

3268\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]

3269.SS Extension: \f[C]native_numbering\f[R]

3270.PP

3271Enables native numbering of figures and tables.

3272Enumeration starts at 1.

3273.PP

3274This extension can be enabled/disabled for the following formats:

3275.TP

3276output formats

3277\f[C]odt\f[R], \f[C]opendocument\f[R]

3278.SS Extension: \f[C]styles\f[R] {#ext-styles}

3279.PP

3280When converting from docx, read all docx styles as divs (for paragraph

3281styles) and spans (for character styles) regardless of whether pandoc

3282understands the meaning of these styles.

3283This can be used with docx custom styles.

3284Disabled by default.

3285.TP

3286input formats

3287\f[C]docx\f[R]

3288.SS Extension: \f[C]amuse\f[R]

3289.PP

3290In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions

3291to Emacs Muse markup.

3292.SS Extension: \f[C]citations\f[R]

3293.PP

3294Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted

3295in \f[C]org\f[R] input.

3296.SS Extension: \f[C]ntb\f[R]

3297.PP

3298In the \f[C]context\f[R] output format this enables the use of Natural

3299Tables (TABLE) instead of the default Extreme Tables (xtables).

3300Natural tables allow more fine-grained global customization but come at

3301a performance penalty compared to extreme tables.

3302.SH PANDOC\[aq]S MARKDOWN

3303.PP

3304Pandoc understands an extended and slightly revised version of John

3305Gruber\[aq]s Markdown syntax.

3306This document explains the syntax, noting differences from standard

3307Markdown.

3308Except where noted, these differences can be suppressed by using the

3309\f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R].

3310Extensions can be enabled or disabled to specify the behavior more

3311granularly.

3312They are described in the following.

3313See also Extensions above, for extensions that work also on other

3314formats.

3315.SS Philosophy

3316.PP

3317Markdown is designed to be easy to write, and, even more importantly,

3318easy to read:

3319.RS

3320.PP

3321A Markdown-formatted document should be publishable as-is, as plain

3322text, without looking like it\[aq]s been marked up with tags or

3323formatting instructions.

3324-- John Gruber

3325.RE

3326.PP

3327This principle has guided pandoc\[aq]s decisions in finding syntax for

3328tables, footnotes, and other extensions.

3329.PP

3330There is, however, one respect in which pandoc\[aq]s aims are different

3331from the original aims of Markdown.

3332Whereas Markdown was originally designed with HTML generation in mind,

3333pandoc is designed for multiple output formats.

3334Thus, while pandoc allows the embedding of raw HTML, it discourages it,

3335and provides other, non-HTMLish ways of representing important document

3336elements like definition lists, tables, mathematics, and footnotes.

3337.SS Paragraphs

3338.PP

3339A paragraph is one or more lines of text followed by one or more blank

3340lines.

3341Newlines are treated as spaces, so you can reflow your paragraphs as you

3342like.

3343If you need a hard line break, put two or more spaces at the end of a

3344line.

3345.SS Extension: \f[C]escaped_line_breaks\f[R]

3346.PP

3347A backslash followed by a newline is also a hard line break.

3348Note: in multiline and grid table cells, this is the only way to create

3349a hard line break, since trailing spaces in the cells are ignored.

3350.SS Headings

3351.PP

3352There are two kinds of headings: Setext and ATX.

3353.SS Setext-style headings

3354.PP

3355A setext-style heading is a line of text \[dq]underlined\[dq] with a row

3356of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for

3357a level-two heading):

3358.IP

3359.nf

3360\f[C]

3361A level-one heading

3362===================

3363

3364A level-two heading

3365-------------------

3366\f[R]

3367.fi

3368.PP

3369The heading text can contain inline formatting, such as emphasis (see

3370Inline formatting, below).

3371.SS ATX-style headings

3372.PP

3373An ATX-style heading consists of one to six \f[C]#\f[R] signs and a line

3374of text, optionally followed by any number of \f[C]#\f[R] signs.

3375The number of \f[C]#\f[R] signs at the beginning of the line is the

3376heading level:

3377.IP

3378.nf

3379\f[C]

3380## A level-two heading

3381

3382### A level-three heading ###

3383\f[R]

3384.fi

3385.PP

3386As with setext-style headings, the heading text can contain formatting:

3387.IP

3388.nf

3389\f[C]

3390# A level-one heading with a [link](/url) and *emphasis*

3391\f[R]

3392.fi

3393.SS Extension: \f[C]blank_before_header\f[R]

3394.PP

3395Standard Markdown syntax does not require a blank line before a heading.

3396Pandoc does require this (except, of course, at the beginning of the

3397document).

3398The reason for the requirement is that it is all too easy for a

3399\f[C]#\f[R] to end up at the beginning of a line by accident (perhaps

3400through line wrapping).

3401Consider, for example:

3402.IP

3403.nf

3404\f[C]

3405I like several of their flavors of ice cream:

3406#22, for example, and #5.

3407\f[R]

3408.fi

3409.SS Extension: \f[C]space_in_atx_header\f[R]

3410.PP

3411Many Markdown implementations do not require a space between the opening

3412\f[C]#\f[R]s of an ATX heading and the heading text, so that

3413\f[C]#5 bolt\f[R] and \f[C]#hashtag\f[R] count as headings.

3414With this extension, pandoc does require the space.

3415.SS Heading identifiers

3416.PP

3417See also the \f[C]auto_identifiers\f[R] extension above.

3418.SS Extension: \f[C]header_attributes\f[R]

3419.PP

3420Headings can be assigned attributes using this syntax at the end of the

3421line containing the heading text:

3422.IP

3423.nf

3424\f[C]

3425{#identifier .class .class key=value key=value}

3426\f[R]

3427.fi

3428.PP

3429Thus, for example, the following headings will all be assigned the

3430identifier \f[C]foo\f[R]:

3431.IP

3432.nf

3433\f[C]

3434# My heading {#foo}

3435

3436## My heading ## {#foo}

3437

3438My other heading {#foo}

3439---------------

3440\f[R]

3441.fi

3442.PP

3443(This syntax is compatible with PHP Markdown Extra.)

3444.PP

3445Note that although this syntax allows assignment of classes and

3446key/value attributes, writers generally don\[aq]t use all of this

3447information.

3448Identifiers, classes, and key/value attributes are used in HTML and

3449HTML-based formats such as EPUB and slidy.

3450Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,

3451Textile, Jira markup, and AsciiDoc writers.

3452.PP

3453Headings with the class \f[C]unnumbered\f[R] will not be numbered, even

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

3455A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to

3456\f[C].unnumbered\f[R], and preferable in non-English documents.

3457So,

3458.IP

3459.nf

3460\f[C]

3461# My heading {-}

3462\f[R]

3463.fi

3464.PP

3465is just the same as

3466.IP

3467.nf

3468\f[C]

3469# My heading {.unnumbered}

3470\f[R]

3471.fi

3472.PP

3473If the \f[C]unlisted\f[R] class is present in addition to

3474\f[C]unnumbered\f[R], the heading will not be included in a table of

3475contents.

3476(Currently this feature is only implemented for certain formats: those

3477based on LaTeX and HTML, PowerPoint, and RTF.)

3478.SS Extension: \f[C]implicit_header_references\f[R]

3479.PP

3480Pandoc behaves as if reference links have been defined for each heading.

3481So, to link to a heading

3482.IP

3483.nf

3484\f[C]

3485# Heading identifiers in HTML

3486\f[R]

3487.fi

3488.PP

3489you can simply write

3490.IP

3491.nf

3492\f[C]

3493[Heading identifiers in HTML]

3494\f[R]

3495.fi

3496.PP

3497or

3498.IP

3499.nf

3500\f[C]

3501[Heading identifiers in HTML][]

3502\f[R]

3503.fi

3504.PP

3505or

3506.IP

3507.nf

3508\f[C]

3509[the section on heading identifiers][heading identifiers in

3510HTML]

3511\f[R]

3512.fi

3513.PP

3514instead of giving the identifier explicitly:

3515.IP

3516.nf

3517\f[C]

3518[Heading identifiers in HTML](#heading-identifiers-in-html)

3519\f[R]

3520.fi

3521.PP

3522If there are multiple headings with identical text, the corresponding

3523reference will link to the first one only, and you will need to use

3524explicit links to link to the others, as described above.

3525.PP

3526Like regular reference links, these references are case-insensitive.

3527.PP

3528Explicit link reference definitions always take priority over implicit

3529heading references.

3530So, in the following example, the link will point to \f[C]bar\f[R], not

3531to \f[C]#foo\f[R]:

3532.IP

3533.nf

3534\f[C]

3535# Foo

3536

3537[foo]: bar

3538

3539See [foo]

3540\f[R]

3541.fi

3542.SS Block quotations

3543.PP

3544Markdown uses email conventions for quoting blocks of text.

3545A block quotation is one or more paragraphs or other block elements

3546(such as lists or headings), with each line preceded by a \f[C]>\f[R]

3547character and an optional space.

3548(The \f[C]>\f[R] need not start at the left margin, but it should not be

3549indented more than three spaces.)

3550.IP

3551.nf

3552\f[C]

3553> This is a block quote. This

3554> paragraph has two lines.

3555>

3556> 1. This is a list inside a block quote.

3557> 2. Second item.

3558\f[R]

3559.fi

3560.PP

3561A \[dq]lazy\[dq] form, which requires the \f[C]>\f[R] character only on

3562the first line of each block, is also allowed:

3563.IP

3564.nf

3565\f[C]

3566> This is a block quote. This

3567paragraph has two lines.

3568

3569> 1. This is a list inside a block quote.

35702. Second item.

3571\f[R]

3572.fi

3573.PP

3574Among the block elements that can be contained in a block quote are

3575other block quotes.

3576That is, block quotes can be nested:

3577.IP

3578.nf

3579\f[C]

3580> This is a block quote.

3581>

3582> > A block quote within a block quote.

3583\f[R]

3584.fi

3585.PP

3586If the \f[C]>\f[R] character is followed by an optional space, that

3587space will be considered part of the block quote marker and not part of

3588the indentation of the contents.

3589Thus, to put an indented code block in a block quote, you need five

3590spaces after the \f[C]>\f[R]:

3591.IP

3592.nf

3593\f[C]

3594> code

3595\f[R]

3596.fi

3597.SS Extension: \f[C]blank_before_blockquote\f[R]

3598.PP

3599Standard Markdown syntax does not require a blank line before a block

3600quote.

3601Pandoc does require this (except, of course, at the beginning of the

3602document).

3603The reason for the requirement is that it is all too easy for a

3604\f[C]>\f[R] to end up at the beginning of a line by accident (perhaps

3605through line wrapping).

3606So, unless the \f[C]markdown_strict\f[R] format is used, the following

3607does not produce a nested block quote in pandoc:

3608.IP

3609.nf

3610\f[C]

3611> This is a block quote.

3612>> Nested.

3613\f[R]

3614.fi

3615.SS Verbatim (code) blocks

3616.SS Indented code blocks

3617.PP

3618A block of text indented four spaces (or one tab) is treated as verbatim

3619text: that is, special characters do not trigger special formatting, and

3620all spaces and line breaks are preserved.

3621For example,

3622.IP

3623.nf

3624\f[C]

3625 if (a > 3) {

3626 moveShip(5 * gravity, DOWN);

3627 }

3628\f[R]

3629.fi

3630.PP

3631The initial (four space or one tab) indentation is not considered part

3632of the verbatim text, and is removed in the output.

3633.PP

3634Note: blank lines in the verbatim text need not begin with four spaces.

3635.SS Fenced code blocks

3636.SS Extension: \f[C]fenced_code_blocks\f[R]

3637.PP

3638In addition to standard indented code blocks, pandoc supports

3639\f[I]fenced\f[R] code blocks.

3640These begin with a row of three or more tildes (\f[C]\[ti]\f[R]) and end

3641with a row of tildes that must be at least as long as the starting row.

3642Everything between these lines is treated as code.

3643No indentation is necessary:

3644.IP

3645.nf

3646\f[C]

3647\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3648if (a > 3) {

3649 moveShip(5 * gravity, DOWN);

3650}

3651\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3652\f[R]

3653.fi

3654.PP

3655Like regular code blocks, fenced code blocks must be separated from

3656surrounding text by blank lines.

3657.PP

3658If the code itself contains a row of tildes or backticks, just use a

3659longer row of tildes or backticks at the start and end:

3660.IP

3661.nf

3662\f[C]

3663\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3664\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3665code including tildes

3666\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3667\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]

3668\f[R]

3669.fi

3670.SS Extension: \f[C]backtick_code_blocks\f[R]

3671.PP

3672Same as \f[C]fenced_code_blocks\f[R], but uses backticks

3673(\f[C]\[ga]\f[R]) instead of tildes (\f[C]\[ti]\f[R]).

3674.SS Extension: \f[C]fenced_code_attributes\f[R]

3675.PP

3676Optionally, you may attach attributes to fenced or backtick code block

3677using this syntax:

3678.IP

3679.nf

3680\f[C]

3681\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}

3682qsort [] = []

3683qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++

3684 qsort (filter (>= x) xs)

3685\[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]

3686\f[R]

3687.fi

3688.PP

3689Here \f[C]mycode\f[R] is an identifier, \f[C]haskell\f[R] and

3690\f[C]numberLines\f[R] are classes, and \f[C]startFrom\f[R] is an

3691attribute with value \f[C]100\f[R].

3692Some output formats can use this information to do syntax highlighting.

3693Currently, the only output formats that uses this information are HTML,

3694LaTeX, Docx, Ms, and PowerPoint.

3695If highlighting is supported for your output format and language, then

3696the code block above will appear highlighted, with numbered lines.

3697(To see which languages are supported, type