From d241f8e37d53648e05c0df27f9c3ebf41875c718 Mon Sep 17 00:00:00 2001 From: federico Date: Sat, 4 Sep 2021 09:45:25 +0200 Subject: [PATCH] =?UTF-8?q?ajout=20du=20manuel=20de=20pandoc=20en=20format?= =?UTF-8?q?=20textuel=20format=C3=A9=20par=20man?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manuel-pandoc.txt | 6411 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 6411 insertions(+) create mode 100644 manuel-pandoc.txt diff --git a/manuel-pandoc.txt b/manuel-pandoc.txt new file mode 100644 index 0000000..e0317c9 --- /dev/null +++ b/manuel-pandoc.txt @@ -0,0 +1,6411 @@ +Pandoc User’s Guide() Pandoc User’s Guide() + + + +NNAAMMEE + pandoc - general markup converter + +SSYYNNOOPPSSIISS + pandoc [_o_p_t_i_o_n_s] [_i_n_p_u_t_-_f_i_l_e]... + +DDEESSCCRRIIPPTTIIOONN + Pandoc is a Haskell library for converting from one markup format to + another, and a command-line tool that uses this library. + + Pandoc can convert between numerous markup and word processing formats, + including, but not limited to, various flavors of Markdown, HTML, LaTeX + and Word docx. For the full lists of input and output formats, see the + --from and --to options below. Pandoc can also produce PDF output: see + creating a PDF, below. + + Pandoc’s enhanced version of Markdown includes syntax for tables, + definition lists, metadata blocks, footnotes, citations, math, and much + more. See below under Pandoc’s Markdown. + + Pandoc has a modular design: it consists of a set of readers, which + parse text in a given format and produce a native representation of the + document (an _a_b_s_t_r_a_c_t _s_y_n_t_a_x _t_r_e_e or AST), and a set of writers, which + convert this native representation into a target format. Thus, adding + an input or output format requires only adding a reader or writer. + Users can also run custom pandoc filters to modify the intermediate + AST. + + Because pandoc’s intermediate representation of a document is less + expressive than many of the formats it converts between, one should not + expect perfect conversions between every format and every other. + Pandoc attempts to preserve the structural elements of a document, but + not formatting details such as margin size. And some document + elements, such as complex tables, may not fit into pandoc’s simple + document model. While conversions from pandoc’s Markdown to all + formats aspire to be perfect, conversions from formats more expressive + than pandoc’s Markdown can be expected to be lossy. + + UUssiinngg ppaannddoocc + If no _i_n_p_u_t_-_f_i_l_e_s are specified, input is read from _s_t_d_i_n. Output goes + to _s_t_d_o_u_t by default. For output to a file, use the -o option: + + + pandoc -o output.html input.txt + + + By default, pandoc produces a document fragment. To produce a + standalone document (e.g. a valid HTML file including and + ), use the -s or --standalone flag: + + + pandoc -s -o output.html input.txt + + + For more information on how standalone documents are produced, see + Templates below. + + If multiple input files are given, pandoc will concatenate them all + (with blank lines between them) before parsing. (Use --file-scope to + parse files individually.) + + SSppeecciiffyyiinngg ffoorrmmaattss + The format of the input and output can be specified explicitly using + command-line options. The input format can be specified using the + -f/--from option, the output format using the -t/--to option. Thus, to + convert hello.txt from Markdown to LaTeX, you could type: + + + pandoc -f markdown -t latex hello.txt + + + To convert hello.html from HTML to Markdown: + + + pandoc -f html -t markdown hello.html + + + Supported input and output formats are listed below under Options (see + -f for input formats and -t for output formats). You can also use + pandoc --list-input-formats and pandoc --list-output-formats to print + lists of supported formats. + + If the input or output format is not specified explicitly, pandoc will + attempt to guess it from the extensions of the filenames. Thus, for + example, + + + pandoc -o hello.tex hello.txt + + + will convert hello.txt from Markdown to LaTeX. If no output file is + specified (so that output goes to _s_t_d_o_u_t), or if the output file’s + extension is unknown, the output format will default to HTML. If no + input file is specified (so that input comes from _s_t_d_i_n), or if the + input files’ extensions are unknown, the input format will be assumed + to be Markdown. + + CChhaarraacctteerr eennccooddiinngg + Pandoc uses the UTF-8 character encoding for both input and output. If + your local character encoding is not UTF-8, you should pipe input and + output through iconv: + + + iconv -t utf-8 input.txt | pandoc | iconv -f utf-8 + + + Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF, + OPML, DocBook, and Texinfo), information about the character encoding + is included in the document header, which will only be included if you + use the -s/--standalone option. + + CCrreeaattiinngg aa PPDDFF + To produce a PDF, specify an output file with a .pdf extension: + + + pandoc test.txt -o test.pdf + + + By default, pandoc will use LaTeX to create the PDF, which requires + that a LaTeX engine be installed (see --pdf-engine below). + Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an + intermediate format. To do this, specify an output file with a .pdf + extension, as before, but add the --pdf-engine option or -t context, -t + html, or -t ms to the command line. The tool used to generate the PDF + from the intermediate format may be specified using --pdf-engine. + + You can control the PDF style using variables, depending on the + intermediate format used: see variables for LaTeX, variables for + ConTeXt, variables for wkhtmltopdf, variables for ms. When HTML is + used as an intermediate format, the output can be styled using --css. + + To debug the PDF creation, it can be useful to look at the intermediate + representation: instead of -o test.pdf, use for example -s -o test.tex + to output the generated LaTeX. You can then test it with pdflatex + test.tex. + + When using LaTeX, the following packages need to be available (they are + included with all recent versions of TeX Live): amsfonts, amsmath, lm, + unicode-math, iftex, listings (if the --listings option is used), + fancyvrb, longtable, booktabs, graphicx (if the document contains + images), hyperref, xcolor, ulem, geometry (with the geometry variable + set), setspace (with linestretch), and babel (with lang). The use of + xelatex or lualatex as the PDF engine requires fontspec. lualatex uses + selnolig. xelatex uses polyglossia (with lang), xecjk, and bidi (with + the dir variable set). If the mathspec variable is set, xelatex will + use mathspec instead of unicode-math. The upquote and microtype + packages are used if available, and csquotes will be used for + typography if the csquotes variable or metadata field is set to a true + value. The natbib, biblatex, bibtex, and biber packages can optionally + be used for citation rendering. The following packages will be used to + improve output quality if present, but pandoc does not require them to + be present: upquote (for straight quotes in verbatim environments), + microtype (for better spacing adjustments), parskip (for better inter- + paragraph spaces), xurl (for better line breaks in URLs), bookmark (for + better PDF bookmarks), and footnotehyper or footnote (to allow + footnotes in tables). + + RReeaaddiinngg ffrroomm tthhee WWeebb + Instead of an input file, an absolute URI may be given. In this case + pandoc will fetch the content using HTTP: + + + pandoc -f html -t markdown https://www.fsf.org + + + It is possible to supply a custom User-Agent string or other header + when requesting a document from a URL: + + + pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \ + https://www.fsf.org + + +OOPPTTIIOONNSS + GGeenneerraall ooppttiioonnss + --ff _F_O_R_M_A_T, --rr _F_O_R_M_A_T, ----ffrroomm==_F_O_R_M_A_T, ----rreeaadd==_F_O_R_M_A_T + Specify input format. _F_O_R_M_A_T can be: + + • bibtex (BibTeX bibliography) + + • biblatex (BibLaTeX bibliography) + + • commonmark (CommonMark Markdown) + + • commonmark_x (CommonMark Markdown with extensions) + + • creole (Creole 1.0) + + • csljson (CSL JSON bibliography) + + • csv (CSV table) + + • docbook (DocBook) + + • docx (Word docx) + + • dokuwiki (DokuWiki markup) + + • epub (EPUB) + + • fb2 (FictionBook2 e-book) + + • gfm (GitHub-Flavored Markdown), or the deprecated and less + accurate markdown_github; use markdown_github only if you need + extensions not supported in gfm. + + • haddock (Haddock markup) + + • html (HTML) + + • ipynb (Jupyter notebook) + + • jats (JATS XML) + + • jira (Jira/Confluence wiki markup) + + • json (JSON version of native AST) + + • latex (LaTeX) + + • markdown (Pandoc’s Markdown) + + • markdown_mmd (MultiMarkdown) + + • markdown_phpextra (PHP Markdown Extra) + + • markdown_strict (original unextended Markdown) + + • mediawiki (MediaWiki markup) + + • man (roff man) + + • muse (Muse) + + • native (native Haskell) + + • odt (ODT) + + • opml (OPML) + + • org (Emacs Org mode) + + • rst (reStructuredText) + + • t2t (txt2tags) + + • textile (Textile) + + • tikiwiki (TikiWiki markup) + + • twiki (TWiki markup) + + • vimwiki (Vimwiki) + + Extensions can be individually enabled or disabled by appending + +EXTENSION or -EXTENSION to the format name. See Extensions + below, for a list of extensions and their names. See + --list-input-formats and --list-extensions, below. + + --tt _F_O_R_M_A_T, --ww _F_O_R_M_A_T, ----ttoo==_F_O_R_M_A_T, ----wwrriittee==_F_O_R_M_A_T + Specify output format. _F_O_R_M_A_T can be: + + • asciidoc (AsciiDoc) or asciidoctor (AsciiDoctor) + + • beamer (LaTeX beamer slide show) + + • bibtex (BibTeX bibliography) + + • biblatex (BibLaTeX bibliography) + + • commonmark (CommonMark Markdown) + + • commonmark_x (CommonMark Markdown with extensions) + + • context (ConTeXt) + + • csljson (CSL JSON bibliography) + + • docbook or docbook4 (DocBook 4) + + • docbook5 (DocBook 5) + + • docx (Word docx) + + • dokuwiki (DokuWiki markup) + + • epub or epub3 (EPUB v3 book) + + • epub2 (EPUB v2) + + • fb2 (FictionBook2 e-book) + + • gfm (GitHub-Flavored Markdown), or the deprecated and less + accurate markdown_github; use markdown_github only if you need + extensions not supported in gfm. + + • haddock (Haddock markup) + + • html or html5 (HTML, i.e. HTML5/XHTML polyglot markup) + + • html4 (XHTML 1.0 Transitional) + + • icml (InDesign ICML) + + • ipynb (Jupyter notebook) + + • jats_archiving (JATS XML, Archiving and Interchange Tag Set) + + • jats_articleauthoring (JATS XML, Article Authoring Tag Set) + + • jats_publishing (JATS XML, Journal Publishing Tag Set) + + • jats (alias for jats_archiving) + + • jira (Jira/Confluence wiki markup) + + • json (JSON version of native AST) + + • latex (LaTeX) + + • man (roff man) + + • markdown (Pandoc’s Markdown) + + • markdown_mmd (MultiMarkdown) + + • markdown_phpextra (PHP Markdown Extra) + + • markdown_strict (original unextended Markdown) + + • mediawiki (MediaWiki markup) + + • ms (roff ms) + + • muse (Muse), + + • native (native Haskell), + + • odt (OpenOffice text document) + + • opml (OPML) + + • opendocument (OpenDocument) + + • org (Emacs Org mode) + + • pdf (PDF) + + • plain (plain text), + + • pptx (PowerPoint slide show) + + • rst (reStructuredText) + + • rtf (Rich Text Format) + + • texinfo (GNU Texinfo) + + • textile (Textile) + + • slideous (Slideous HTML and JavaScript slide show) + + • slidy (Slidy HTML and JavaScript slide show) + + • dzslides (DZSlides HTML5 + JavaScript slide show), + + • revealjs (reveal.js HTML5 + JavaScript slide show) + + • s5 (S5 HTML and JavaScript slide show) + + • tei (TEI Simple) + + • xwiki (XWiki markup) + + • zimwiki (ZimWiki markup) + + • the path of a custom Lua writer, see Custom writers below + + Note that odt, docx, epub, and pdf output will not be directed + to _s_t_d_o_u_t unless forced with -o -. + + Extensions can be individually enabled or disabled by appending + +EXTENSION or -EXTENSION to the format name. See Extensions + below, for a list of extensions and their names. See + --list-output-formats and --list-extensions, below. + + --oo _F_I_L_E, ----oouuttppuutt==_F_I_L_E + Write output to _F_I_L_E instead of _s_t_d_o_u_t. If _F_I_L_E is -, output + will go to _s_t_d_o_u_t, even if a non-textual format (docx, odt, + epub2, epub3) is specified. + + ----ddaattaa--ddiirr==_D_I_R_E_C_T_O_R_Y + Specify the user data directory to search for pandoc data files. + If this option is not specified, the default user data directory + will be used. On *nix and macOS systems this will be the pandoc + subdirectory of the XDG data directory (by default, + $HOME/.local/share, overridable by setting the XDG_DATA_HOME + environment variable). If that directory does not exist and + $HOME/.pandoc exists, it will be used (for backwards + compatibility). On Windows the default user data directory is + C:\Users\USERNAME\AppData\Roaming\pandoc. You can find the + default user data directory on your system by looking at the + output of pandoc --version. Data files placed in this directory + (for example, reference.odt, reference.docx, epub.css, + templates) will override pandoc’s normal defaults. + + --dd _F_I_L_E, ----ddeeffaauullttss==_F_I_L_E + Specify a set of default option settings. _F_I_L_E is a YAML file + whose fields correspond to command-line option settings. All + options for document conversion, including input and output + files, can be set using a defaults file. The file will be + searched for first in the working directory, and then in the + defaults subdirectory of the user data directory (see + --data-dir). The .yaml extension may be omitted. See the + section Default files for more information on the file format. + Settings from the defaults file may be overridden or extended by + subsequent options on the command line. + + ----bbaasshh--ccoommpplleettiioonn + Generate a bash completion script. To enable bash completion + with pandoc, add this to your .bashrc: + + + eval "$(pandoc --bash-completion)" + + + ----vveerrbboossee + Give verbose debugging output. + + ----qquuiieett + Suppress warning messages. + + ----ffaaiill--iiff--wwaarrnniinnggss + Exit with error status if there are any warnings. + + ----lloogg==_F_I_L_E + Write log messages in machine-readable JSON format to _F_I_L_E. All + messages above DEBUG level will be written, regardless of + verbosity settings (--verbose, --quiet). + + ----lliisstt--iinnppuutt--ffoorrmmaattss + List supported input formats, one per line. + + ----lliisstt--oouuttppuutt--ffoorrmmaattss + List supported output formats, one per line. + + ----lliisstt--eexxtteennssiioonnss[==_F_O_R_M_A_T] + List supported extensions for _F_O_R_M_A_T, one per line, preceded by + a + or - indicating whether it is enabled by default in _F_O_R_M_A_T. + If _F_O_R_M_A_T is not specified, defaults for pandoc’s Markdown are + given. + + ----lliisstt--hhiigghhlliigghhtt--llaanngguuaaggeess + List supported languages for syntax highlighting, one per line. + + ----lliisstt--hhiigghhlliigghhtt--ssttyylleess + List supported styles for syntax highlighting, one per line. + See --highlight-style. + + --vv, ----vveerrssiioonn + Print version. + + --hh, ----hheellpp + Show usage message. + + RReeaaddeerr ooppttiioonnss + ----sshhiifftt--hheeaaddiinngg--lleevveell--bbyy==_N_U_M_B_E_R + Shift heading levels by a positive or negative integer. For + example, with --shift-heading-level-by=-1, level 2 headings + become level 1 headings, and level 3 headings become level 2 + headings. Headings cannot have a level less than 1, so a + heading that would be shifted below level 1 becomes a regular + paragraph. Exception: with a shift of -N, a level-N heading at + the beginning of the document replaces the metadata title. + --shift-heading-level-by=-1 is a good choice when converting + HTML or Markdown documents that use an initial level-1 heading + for the document title and level-2+ headings for sections. + --shift-heading-level-by=1 may be a good choice for converting + Markdown documents that use level-1 headings for sections to + HTML, since pandoc uses a level-1 heading to render the document + title. + + ----bbaassee--hheeaaddeerr--lleevveell==_N_U_M_B_E_R + _D_e_p_r_e_c_a_t_e_d_. _U_s_e _-_-_s_h_i_f_t_-_h_e_a_d_i_n_g_-_l_e_v_e_l_-_b_y_=_X _i_n_s_t_e_a_d_, _w_h_e_r_e _X _= + _N_U_M_B_E_R _- _1_. Specify the base level for headings (defaults to 1). + + ----ssttrriipp--eemmppttyy--ppaarraaggrraapphhss + _D_e_p_r_e_c_a_t_e_d_. _U_s_e _t_h_e _+_e_m_p_t_y___p_a_r_a_g_r_a_p_h_s _e_x_t_e_n_s_i_o_n _i_n_s_t_e_a_d_. Ignore + paragraphs with no content. This option is useful for + converting word processing documents where users have used empty + paragraphs to create inter-paragraph space. + + ----iinnddeenntteedd--ccooddee--ccllaasssseess==_C_L_A_S_S_E_S + Specify classes to use for indented code blocks–for example, + perl,numberLines or haskell. Multiple classes may be separated + by spaces or commas. + + ----ddeeffaauulltt--iimmaaggee--eexxtteennssiioonn==_E_X_T_E_N_S_I_O_N + Specify a default extension to use when image paths/URLs have no + extension. This allows you to use the same source for formats + that require different kinds of images. Currently this option + only affects the Markdown and LaTeX readers. + + ----ffiillee--ssccooppee + Parse each file individually before combining for multifile + documents. This will allow footnotes in different files with + the same identifiers to work as expected. If this option is + set, footnotes and links will not work across files. Reading + binary files (docx, odt, epub) implies --file-scope. + + --FF _P_R_O_G_R_A_M, ----ffiilltteerr==_P_R_O_G_R_A_M + Specify an executable to be used as a filter transforming the + pandoc AST after the input is parsed and before the output is + written. The executable should read JSON from stdin and write + JSON to stdout. The JSON must be formatted like pandoc’s own + JSON input and output. The name of the output format will be + passed to the filter as the first argument. Hence, + + + pandoc --filter ./caps.py -t latex + + + is equivalent to + + + pandoc -t json | ./caps.py latex | pandoc -f json -t latex + + + The latter form may be useful for debugging filters. + + Filters may be written in any language. Text.Pandoc.JSON + exports toJSONFilter to facilitate writing filters in Haskell. + Those who would prefer to write filters in python can use the + module pandocfilters, installable from PyPI. There are also + pandoc filter libraries in PHP, perl, and JavaScript/node.js. + + In order of preference, pandoc will look for filters in + + 1. a specified full or relative path (executable or non- + executable) + + 2. $DATADIR/filters (executable or non-executable) where + $DATADIR is the user data directory (see --data-dir, above). + + 3. $PATH (executable only) + + Filters, Lua-filters, and citeproc processing are applied in the + order specified on the command line. + + --LL _S_C_R_I_P_T, ----lluuaa--ffiilltteerr==_S_C_R_I_P_T + Transform the document in a similar fashion as JSON filters (see + --filter), but use pandoc’s built-in Lua filtering system. The + given Lua script is expected to return a list of Lua filters + which will be applied in order. Each Lua filter must contain + element-transforming functions indexed by the name of the AST + element on which the filter function should be applied. + + The pandoc Lua module provides helper functions for element + creation. It is always loaded into the script’s Lua + environment. + + See the Lua filters documentation for further details. + + In order of preference, pandoc will look for Lua filters in + + 1. a specified full or relative path + + 2. $DATADIR/filters where $DATADIR is the user data directory + (see --data-dir, above). + + Filters, Lua filters, and citeproc processing are applied in the + order specified on the command line. + + --MM _K_E_Y[==_V_A_L], ----mmeettaaddaattaa==_K_E_Y[::_V_A_L] + Set the metadata field _K_E_Y to the value _V_A_L. A value specified + on the command line overrides a value specified in the document + using YAML metadata blocks. Values will be parsed as YAML + boolean or string values. If no value is specified, the value + will be treated as Boolean true. Like --variable, --metadata + causes template variables to be set. But unlike --variable, + --metadata affects the metadata of the underlying document + (which is accessible from filters and may be printed in some + output formats) and metadata values will be escaped when + inserted into the template. + + ----mmeettaaddaattaa--ffiillee==_F_I_L_E + Read metadata from the supplied YAML (or JSON) file. This + option can be used with every input format, but string scalars + in the YAML file will always be parsed as Markdown. Generally, + the input will be handled the same as in YAML metadata blocks. + This option can be used repeatedly to include multiple metadata + files; values in files specified later on the command line will + be preferred over those specified in earlier files. Metadata + values specified inside the document, or by using -M, overwrite + values specified with this option. + + --pp, ----pprreesseerrvvee--ttaabbss + Preserve tabs instead of converting them to spaces. (By + default, pandoc converts tabs to spaces before parsing its + input.) Note that this will only affect tabs in literal code + spans and code blocks. Tabs in regular text are always treated + as spaces. + + ----ttaabb--ssttoopp==_N_U_M_B_E_R + Specify the number of spaces per tab (default is 4). + + ----ttrraacckk--cchhaannggeess==aacccceepptt|rreejjeecctt|aallll + Specifies what to do with insertions, deletions, and comments + produced by the MS Word “Track Changes” feature. accept (the + default) processes all the insertions and deletions. reject + ignores them. Both accept and reject ignore comments. all + includes all insertions, deletions, and comments, wrapped in + spans with insertion, deletion, comment-start, and comment-end + classes, respectively. The author and time of change is + included. all is useful for scripting: only accepting changes + from a certain reviewer, say, or before a certain date. If a + paragraph is inserted or deleted, track-changes=all produces a + span with the class paragraph-insertion/paragraph-deletion + before the affected paragraph break. This option only affects + the docx reader. + + ----eexxttrraacctt--mmeeddiiaa==_D_I_R + Extract images and other media contained in or linked from the + source document to the path _D_I_R, creating it if necessary, and + adjust the images references in the document so they point to + the extracted files. Media are downloaded, read from the file + system, or extracted from a binary container (e.g. docx), as + needed. The original file paths are used if they are relative + paths not containing ... Otherwise filenames are constructed + from the SHA1 hash of the contents. + + ----aabbbbrreevviiaattiioonnss==_F_I_L_E + Specifies a custom abbreviations file, with abbreviations one to + a line. If this option is not specified, pandoc will read the + data file abbreviations from the user data directory or fall + back on a system default. To see the system default, use pandoc + --print-default-data-file=abbreviations. The only use pandoc + makes of this list is in the Markdown reader. Strings found in + this list will be followed by a nonbreaking space, and the + period will not produce sentence-ending space in formats like + LaTeX. The strings may not contain spaces. + + GGeenneerraall wwrriitteerr ooppttiioonnss + --ss, ----ssttaannddaalloonnee + Produce output with an appropriate header and footer (e.g. a + standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This + option is set automatically for pdf, epub, epub3, fb2, docx, and + odt output. For native output, this option causes metadata to + be included; otherwise, metadata is suppressed. + + ----tteemmppllaattee==_F_I_L_E|_U_R_L + Use the specified file as a custom template for the generated + document. Implies --standalone. See Templates, below, for a + description of template syntax. If no extension is specified, + an extension corresponding to the writer will be added, so that + --template=special looks for special.html for HTML output. If + the template is not found, pandoc will search for it in the + templates subdirectory of the user data directory (see + --data-dir). If this option is not used, a default template + appropriate for the output format will be used (see + -D/--print-default-template). + + --VV _K_E_Y[==_V_A_L], ----vvaarriiaabbllee==_K_E_Y[::_V_A_L] + Set the template variable _K_E_Y to the value _V_A_L when rendering + the document in standalone mode. If no _V_A_L is specified, the + key will be given the value true. + + --DD _F_O_R_M_A_T, ----pprriinntt--ddeeffaauulltt--tteemmppllaattee==_F_O_R_M_A_T + Print the system default template for an output _F_O_R_M_A_T. (See -t + for a list of possible _F_O_R_M_A_Ts.) Templates in the user data + directory are ignored. This option may be used with -o/--output + to redirect output to a file, but -o/--output must come before + --print-default-template on the command line. + + Note that some of the default templates use partials, for + example styles.html. To print the partials, use + --print-default-data-file: for example, + --print-default-data-file=templates/styles.html. + + ----pprriinntt--ddeeffaauulltt--ddaattaa--ffiillee==_F_I_L_E + Print a system default data file. Files in the user data + directory are ignored. This option may be used with -o/--output + to redirect output to a file, but -o/--output must come before + --print-default-data-file on the command line. + + ----eeooll==ccrrllff|llff|nnaattiivvee + Manually specify line endings: crlf (Windows), lf + (macOS/Linux/UNIX), or native (line endings appropriate to the + OS on which pandoc is being run). The default is native. + + ----ddppii=_N_U_M_B_E_R + Specify the default dpi (dots per inch) value for conversion + from pixels to inch/centimeters and vice versa. (Technically, + the correct term would be ppi: pixels per inch.) The default is + 96dpi. When images contain information about dpi internally, + the encoded value is used instead of the default specified by + this option. + + ----wwrraapp==aauuttoo|nnoonnee|pprreesseerrvvee + Determine how text is wrapped in the output (the source code, + not the rendered version). With auto (the default), pandoc will + attempt to wrap lines to the column width specified by --columns + (default 72). With none, pandoc will not wrap lines at all. + With preserve, pandoc will attempt to preserve the wrapping from + the source document (that is, where there are nonsemantic + newlines in the source, there will be nonsemantic newlines in + the output as well). Automatic wrapping does not currently work + in HTML output. In ipynb output, this option affects wrapping + of the contents of markdown cells. + + ----ccoolluummnnss==_N_U_M_B_E_R + Specify length of lines in characters. This affects text + wrapping in the generated source code (see --wrap). It also + affects calculation of column widths for plain text tables (see + Tables below). + + ----ttoocc, ----ttaabbllee--ooff--ccoonntteennttss + Include an automatically generated table of contents (or, in the + case of latex, context, docx, odt, opendocument, rst, or ms, an + instruction to create one) in the output document. This option + has no effect unless -s/--standalone is used, and it has no + effect on man, docbook4, docbook5, or jats output. + + Note that if you are producing a PDF via ms, the table of + contents will appear at the beginning of the document, before + the title. If you would prefer it to be at the end of the + document, use the option --pdf-engine-opt=--no-toc-relocation. + + ----ttoocc--ddeepptthh==_N_U_M_B_E_R + Specify the number of section levels to include in the table of + contents. The default is 3 (which means that level-1, 2, and 3 + headings will be listed in the contents). + + ----ssttrriipp--ccoommmmeennttss + Strip out HTML comments in the Markdown or Textile source, + rather than passing them on to Markdown, Textile or HTML output + as raw HTML. This does not apply to HTML comments inside raw + HTML blocks when the markdown_in_html_blocks extension is not + set. + + ----nnoo--hhiigghhlliigghhtt + Disables syntax highlighting for code blocks and inlines, even + when a language attribute is given. + + ----hhiigghhlliigghhtt--ssttyyllee==_S_T_Y_L_E|_F_I_L_E + Specifies the coloring style to be used in highlighted source + code. Options are pygments (the default), kate, monochrome, + breezeDark, espresso, zenburn, haddock, and tango. For more + information on syntax highlighting in pandoc, see Syntax + highlighting, below. See also --list-highlight-styles. + + Instead of a _S_T_Y_L_E name, a JSON file with extension .theme may + be supplied. This will be parsed as a KDE syntax highlighting + theme and (if valid) used as the highlighting style. + + To generate the JSON version of an existing style, use + --print-highlight-style. + + ----pprriinntt--hhiigghhlliigghhtt--ssttyyllee==_S_T_Y_L_E|_F_I_L_E + Prints a JSON version of a highlighting style, which can be + modified, saved with a .theme extension, and used with + --highlight-style. This option may be used with -o/--output to + redirect output to a file, but -o/--output must come before + --print-highlight-style on the command line. + + ----ssyynnttaaxx--ddeeffiinniittiioonn==_F_I_L_E + Instructs pandoc to load a KDE XML syntax definition file, which + will be used for syntax highlighting of appropriately marked + code blocks. This can be used to add support for new languages + or to use altered syntax definitions for existing languages. + This option may be repeated to add multiple syntax definitions. + + --HH _F_I_L_E, ----iinncclluuddee--iinn--hheeaaddeerr==_F_I_L_E|_U_R_L + Include contents of _F_I_L_E, verbatim, at the end of the header. + This can be used, for example, to include special CSS or + JavaScript in HTML documents. This option can be used + repeatedly to include multiple files in the header. They will + be included in the order specified. Implies --standalone. + + --BB _F_I_L_E, ----iinncclluuddee--bbeeffoorree--bbooddyy==_F_I_L_E|_U_R_L + Include contents of _F_I_L_E, verbatim, at the beginning of the + document body (e.g. after the tag in HTML, or the + \begin{document} command in LaTeX). This can be used to include + navigation bars or banners in HTML documents. This option can + be used repeatedly to include multiple files. They will be + included in the order specified. Implies --standalone. + + --AA _F_I_L_E, ----iinncclluuddee--aafftteerr--bbooddyy==_F_I_L_E|_U_R_L + Include contents of _F_I_L_E, verbatim, at the end of the document + body (before the tag in HTML, or the \end{document} + command in LaTeX). This option can be used repeatedly to + include multiple files. They will be included in the order + specified. Implies --standalone. + + ----rreessoouurrccee--ppaatthh==_S_E_A_R_C_H_P_A_T_H + List of paths to search for images and other resources. The + paths should be separated by : on Linux, UNIX, and macOS + systems, and by ; on Windows. If --resource-path is not + specified, the default resource path is the working directory. + Note that, if --resource-path is specified, the working + directory must be explicitly listed or it will not be searched. + For example: --resource-path=.:test will search the working + directory and the test subdirectory, in that order. This option + can be used repeatedly. Search path components that come later + on the command line will be searched before those that come + earlier, so --resource-path foo:bar --resource-path baz:bim is + equivalent to --resource-path baz:bim:foo:bar. + + ----rreeqquueesstt--hheeaaddeerr==_N_A_M_E::_V_A_L + Set the request header _N_A_M_E to the value _V_A_L when making HTTP + requests (for example, when a URL is given on the command line, + or when resources used in a document must be downloaded). If + you’re behind a proxy, you also need to set the environment + variable http_proxy to http://.... + + ----nnoo--cchheecckk--cceerrttiiffiiccaattee + Disable the certificate verification to allow access to unsecure + HTTP resources (for example when the certificate is no longer + valid or self signed). + + OOppttiioonnss aaffffeeccttiinngg ssppeecciiffiicc wwrriitteerrss + ----sseellff--ccoonnttaaiinneedd + Produce a standalone HTML file with no external dependencies, + using data: URIs to incorporate the contents of linked scripts, + stylesheets, images, and videos. Implies --standalone. The + resulting file should be “self-contained,” in the sense that it + needs no external files and no net access to be displayed + properly by a browser. This option works only with HTML output + formats, including html4, html5, html+lhs, html5+lhs, s5, slidy, + slideous, dzslides, and revealjs. Scripts, images, and + stylesheets at absolute URLs will be downloaded; those at + relative URLs will be sought relative to the working directory + (if the first source file is local) or relative to the base URL + (if the first source file is remote). Elements with the + attribute data-external="1" will be left alone; the documents + they link to will not be incorporated in the document. + Limitation: resources that are loaded dynamically through + JavaScript cannot be incorporated; as a result, --self-contained + does not work with --mathjax, and some advanced features + (e.g. zoom or speaker notes) may not work in an offline “self- + contained” reveal.js slide show. + + ----hhttmmll--qq--ttaaggss + Use tags for quotes in HTML. (This option only has an + effect if the smart extension is enabled for the input format + used.) + + ----aasscciiii + Use only ASCII characters in output. Currently supported for + XML and HTML formats (which use entities instead of UTF-8 when + this option is selected), CommonMark, gfm, and Markdown (which + use entities), roff ms (which use hexadecimal escapes), and to a + limited degree LaTeX (which uses standard commands for accented + characters when possible). roff man output uses ASCII by + default. + + ----rreeffeerreennccee--lliinnkkss + Use reference-style links, rather than inline links, in writing + Markdown or reStructuredText. By default inline links are used. + The placement of link references is affected by the + --reference-location option. + + ----rreeffeerreennccee--llooccaattiioonn==bblloocckk|sseeccttiioonn|ddooccuummeenntt + Specify whether footnotes (and references, if reference-links is + set) are placed at the end of the current (top-level) block, the + current section, or the document. The default is document. + Currently only affects the markdown writer. + + ----mmaarrkkddoowwnn--hheeaaddiinnggss==sseetteexxtt|aattxx + Specify whether to use ATX-style (#-prefixed) or Setext-style + (underlined) headings for level 1 and 2 headings in Markdown + output. (The default is atx.) ATX-style headings are always + used for levels 3+. This option also affects Markdown cells in + ipynb output. + + ----aattxx--hheeaaddeerrss + _D_e_p_r_e_c_a_t_e_d _s_y_n_o_n_y_m _f_o_r _-_-_m_a_r_k_d_o_w_n_-_h_e_a_d_i_n_g_s_=_a_t_x_. + + ----ttoopp--lleevveell--ddiivviissiioonn==ddeeffaauulltt|sseeccttiioonn|cchhaapptteerr|ppaarrtt + Treat top-level headings as the given division type in LaTeX, + ConTeXt, DocBook, and TEI output. The hierarchy order is part, + chapter, then section; all headings are shifted such that the + top-level heading becomes the specified type. The default + behavior is to determine the best division type via heuristics: + unless other conditions apply, section is chosen. When the + documentclass variable is set to report, book, or memoir (unless + the article option is specified), chapter is implied as the + setting for this option. If beamer is the output format, + specifying either chapter or part will cause top-level headings + to become \part{..}, while second-level headings remain as their + default type. + + --NN, ----nnuummbbeerr--sseeccttiioonnss + Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or + EPUB output. By default, sections are not numbered. Sections + with class unnumbered will never be numbered, even if + --number-sections is specified. + + ----nnuummbbeerr--ooffffsseett==_N_U_M_B_E_R[,,_N_U_M_B_E_R,,_._._.] + Offset for section headings in HTML output (ignored in other + output formats). The first number is added to the section + number for top-level headings, the second for second-level + headings, and so on. So, for example, if you want the first + top-level heading in your document to be numbered “6”, specify + --number-offset=5. If your document starts with a level-2 + heading which you want to be numbered “1.5”, specify + --number-offset=1,4. Offsets are 0 by default. Implies + --number-sections. + + ----lliissttiinnggss + Use the listings package for LaTeX code blocks. The package + does not support multi-byte encoding for source code. To handle + UTF-8 you would need to use a custom template. This issue is + fully documented here: Encoding issue with the listings package. + + --ii, ----iinnccrreemmeennttaall + Make list items in slide shows display incrementally (one by + one). The default is for lists to be displayed all at once. + + ----sslliiddee--lleevveell==_N_U_M_B_E_R + Specifies that headings with the specified level create slides + (for beamer, s5, slidy, slideous, dzslides). Headings above + this level in the hierarchy are used to divide the slide show + into sections; headings below this level create subheads within + a slide. Note that content that is not contained under slide- + level headings will not appear in the slide show. The default + is to set the slide level based on the contents of the document; + see Structuring the slide show. + + ----sseeccttiioonn--ddiivvss + Wrap sections in
tags (or
tags for html4), and + attach identifiers to the enclosing
(or
) rather + than the heading itself. See Heading identifiers, below. + + ----eemmaaiill--oobbffuussccaattiioonn==nnoonnee|jjaavvaassccrriipptt|rreeffeerreenncceess + Specify a method for obfuscating mailto: links in HTML + documents. none leaves mailto: links as they are. javascript + obfuscates them using JavaScript. references obfuscates them by + printing their letters as decimal or hexadecimal character + references. The default is none. + + ----iidd--pprreeffiixx==_S_T_R_I_N_G + Specify a prefix to be added to all identifiers and internal + links in HTML and DocBook output, and to footnote numbers in + Markdown and Haddock output. This is useful for preventing + duplicate identifiers when generating fragments to be included + in other pages. + + --TT _S_T_R_I_N_G, ----ttiittllee--pprreeffiixx==_S_T_R_I_N_G + Specify _S_T_R_I_N_G as a prefix at the beginning of the title that + appears in the HTML header (but not in the title as it appears + at the beginning of the HTML body). Implies --standalone. + + --cc _U_R_L, ----ccssss==_U_R_L + Link to a CSS style sheet. This option can be used repeatedly + to include multiple files. They will be included in the order + specified. + + A stylesheet is required for generating EPUB. If none is + provided using this option (or the css or stylesheet metadata + fields), pandoc will look for a file epub.css in the user data + directory (see --data-dir). If it is not found there, sensible + defaults will be used. + + ----rreeffeerreennccee--ddoocc==_F_I_L_E + Use the specified file as a style reference in producing a docx + or ODT file. + + Docx For best results, the reference docx should be a modified + version of a docx file produced using pandoc. The + contents of the reference docx are ignored, but its + stylesheets and document properties (including margins, + page size, header, and footer) are used in the new docx. + If no reference docx is specified on the command line, + pandoc will look for a file reference.docx in the user + data directory (see --data-dir). If this is not found + either, sensible defaults will be used. + + To produce a custom reference.docx, first get a copy of + the default reference.docx: pandoc -o + custom-reference.docx --print-default-data-file + reference.docx. Then open custom-reference.docx in Word, + modify the styles as you wish, and save the file. For + best results, do not make changes to this file other than + modifying the styles used by pandoc: + + Paragraph styles: + + • Normal + + • Body Text + + • First Paragraph + + • Compact + + • Title + + • Subtitle + + • Author + + • Date + + • Abstract + + • Bibliography + + • Heading 1 + + • Heading 2 + + • Heading 3 + + • Heading 4 + + • Heading 5 + + • Heading 6 + + • Heading 7 + + • Heading 8 + + • Heading 9 + + • Block Text + + • Footnote Text + + • Definition Term + + • Definition + + • Caption + + • Table Caption + + • Image Caption + + • Figure + + • Captioned Figure + + • TOC Heading + + Character styles: + + • Default Paragraph Font + + • Body Text Char + + • Verbatim Char + + • Footnote Reference + + • Hyperlink + + • Section Number + + Table style: + + • Table + + ODT For best results, the reference ODT should be a modified + version of an ODT produced using pandoc. The contents of + the reference ODT are ignored, but its stylesheets are + used in the new ODT. If no reference ODT is specified on + the command line, pandoc will look for a file + reference.odt in the user data directory (see + --data-dir). If this is not found either, sensible + defaults will be used. + + To produce a custom reference.odt, first get a copy of + the default reference.odt: pandoc -o custom-reference.odt + --print-default-data-file reference.odt. Then open + custom-reference.odt in LibreOffice, modify the styles as + you wish, and save the file. + + PowerPoint + Templates included with Microsoft PowerPoint 2013 (either + with .pptx or .potx extension) are known to work, as are + most templates derived from these. + + The specific requirement is that the template should + begin with the following first four layouts: + + 1. Title Slide + + 2. Title and Content + + 3. Section Header + + 4. Two Content + + All templates included with a recent version of MS + PowerPoint will fit these criteria. (You can click on + Layout under the Home menu to check.) + + You can also modify the default reference.pptx: first run + pandoc -o custom-reference.pptx --print-default-data-file + reference.pptx, and then modify custom-reference.pptx in + MS PowerPoint (pandoc will use the first four layout + slides, as mentioned above). + + ----eeppuubb--ccoovveerr--iimmaaggee==_F_I_L_E + Use the specified image as the EPUB cover. It is recommended + that the image be less than 1000px in width and height. Note + that in a Markdown source document you can also specify + cover-image in a YAML metadata block (see EPUB Metadata, below). + + ----eeppuubb--mmeettaaddaattaa==_F_I_L_E + Look in the specified XML file for metadata for the EPUB. The + file should contain a series of Dublin Core elements. For + example: + + + Creative Commons + es-AR + + + By default, pandoc will include the following metadata elements: + (from the document title), (from the + document authors), (from the document date, which + should be in ISO 8601 format), (from the lang + variable, or, if is not set, the locale), and (a randomly generated UUID). Any of these may be + overridden by elements in the metadata file. + + Note: if the source document is Markdown, a YAML metadata block + in the document can be used instead. See below under EPUB + Metadata. + + ----eeppuubb--eemmbbeedd--ffoonntt==_F_I_L_E + Embed the specified font in the EPUB. This option can be + repeated to embed multiple fonts. Wildcards can also be used: + for example, DejaVuSans-*.ttf. However, if you use wildcards on + the command line, be sure to escape them or put the whole + filename in single quotes, to prevent them from being + interpreted by the shell. To use the embedded fonts, you will + need to add declarations like the following to your CSS (see + --css): + + + @font-face { + font-family: DejaVuSans; + font-style: normal; + font-weight: normal; + src:url("DejaVuSans-Regular.ttf"); + } + @font-face { + font-family: DejaVuSans; + font-style: normal; + font-weight: bold; + src:url("DejaVuSans-Bold.ttf"); + } + @font-face { + font-family: DejaVuSans; + font-style: italic; + font-weight: normal; + src:url("DejaVuSans-Oblique.ttf"); + } + @font-face { + font-family: DejaVuSans; + font-style: italic; + font-weight: bold; + src:url("DejaVuSans-BoldOblique.ttf"); + } + body { font-family: "DejaVuSans"; } + + + ----eeppuubb--cchhaapptteerr--lleevveell==_N_U_M_B_E_R + Specify the heading level at which to split the EPUB into + separate “chapter” files. The default is to split into chapters + at level-1 headings. This option only affects the internal + composition of the EPUB, not the way chapters and sections are + displayed to users. Some readers may be slow if the chapter + files are too large, so for large documents with few level-1 + headings, one might want to use a chapter level of 2 or 3. + + ----eeppuubb--ssuubbddiirreeccttoorryy==_D_I_R_N_A_M_E + Specify the subdirectory in the OCF container that is to hold + the EPUB-specific contents. The default is EPUB. To put the + EPUB contents in the top level, use an empty string. + + ----iippyynnbb--oouuttppuutt==aallll||nnoonnee||bbeesstt + Determines how ipynb output cells are treated. all means that + all of the data formats included in the original are preserved. + none means that the contents of data cells are omitted. best + causes pandoc to try to pick the richest data block in each + output cell that is compatible with the output format. The + default is best. + + ----ppddff--eennggiinnee==_P_R_O_G_R_A_M + Use the specified engine when producing PDF output. Valid + values are pdflatex, lualatex, xelatex, latexmk, tectonic, + wkhtmltopdf, weasyprint, prince, context, and pdfroff. If the + engine is not in your PATH, the full path of the engine may be + specified here. If this option is not specified, pandoc uses + the following defaults depending on the output format specified + using -t/--to: + + • -t latex or none: pdflatex (other options: xelatex, lualatex, + tectonic, latexmk) + + • -t context: context + + • -t html: wkhtmltopdf (other options: prince, weasyprint; see + print-css.rocks for a good introduction to PDF generation from + HTML/CSS.) + + • -t ms: pdfroff + + ----ppddff--eennggiinnee--oopptt==_S_T_R_I_N_G + Use the given string as a command-line argument to the + pdf-engine. For example, to use a persistent directory foo for + latexmk’s auxiliary files, use --pdf-engine-opt=-outdir=foo. + Note that no check for duplicate options is done. + + CCiittaattiioonn rreennddeerriinngg + --CC, ----cciitteepprroocc + Process the citations in the file, replacing them with rendered + citations and adding a bibliography. Citation processing will + not take place unless bibliographic data is supplied, either + through an external file specified using the --bibliography + option or the bibliography field in metadata, or via a + references section in metadata containing a list of citations in + CSL YAML format with Markdown formatting. The style is + controlled by a CSL stylesheet specified using the --csl option + or the csl field in metadata. (If no stylesheet is specified, + the chicago-author-date style will be used by default.) The + citation processing transformation may be applied before or + after filters or Lua filters (see --filter, --lua-filter): these + transformations are applied in the order they appear on the + command line. For more information, see the section on + Citations. + + ----bbiibblliiooggrraapphhyy==_F_I_L_E + Set the bibliography field in the document’s metadata to _F_I_L_E, + overriding any value set in the metadata. If you supply this + argument multiple times, each _F_I_L_E will be added to + bibliography. If _F_I_L_E is a URL, it will be fetched via HTTP. + If _F_I_L_E is not found relative to the working directory, it will + be sought in the resource path (see --resource-path). + + ----ccssll==_F_I_L_E + Set the csl field in the document’s metadata to _F_I_L_E, overriding + any value set in the metadata. (This is equivalent to + --metadata csl=FILE.) If _F_I_L_E is a URL, it will be fetched via + HTTP. If _F_I_L_E is not found relative to the working directory, + it will be sought in the resource path (see --resource-path) and + finally in the csl subdirectory of the pandoc user data + directory. + + ----cciittaattiioonn--aabbbbrreevviiaattiioonnss==_F_I_L_E + Set the citation-abbreviations field in the document’s metadata + to _F_I_L_E, overriding any value set in the metadata. (This is + equivalent to --metadata citation-abbreviations=FILE.) If _F_I_L_E + is a URL, it will be fetched via HTTP. If _F_I_L_E is not found + relative to the working directory, it will be sought in the + resource path (see --resource-path) and finally in the csl + subdirectory of the pandoc user data directory. + + ----nnaattbbiibb + Use natbib for citations in LaTeX output. This option is not + for use with the --citeproc option or with PDF output. It is + intended for use in producing a LaTeX file that can be processed + with bibtex. + + ----bbiibbllaatteexx + Use biblatex for citations in LaTeX output. This option is not + for use with the --citeproc option or with PDF output. It is + intended for use in producing a LaTeX file that can be processed + with bibtex or biber. + + MMaatthh rreennddeerriinngg iinn HHTTMMLL + The default is to render TeX math as far as possible using Unicode + characters. Formulas are put inside a span with class="math", so that + they may be styled differently from the surrounding text if needed. + However, this gives acceptable results only for basic math, usually you + will want to use --mathjax or another of the following options. + + ----mmaatthhjjaaxx[==_U_R_L] + Use MathJax to display embedded TeX math in HTML output. TeX + math will be put between \(...\) (for inline math) or \[...\] + (for display math) and wrapped in tags with class math. + Then the MathJax JavaScript will render it. The _U_R_L should + point to the MathJax.js load script. If a _U_R_L is not provided, + a link to the Cloudflare CDN will be inserted. + + ----mmaatthhmmll + Convert TeX math to MathML (in epub3, docbook4, docbook5, jats, + html4 and html5). This is the default in odt output. Note that + currently only Firefox and Safari (and select e-book readers) + natively support MathML. + + ----wweebbtteexx[==_U_R_L] + Convert TeX formulas to tags that link to an external + script that converts formulas to images. The formula will be + URL-encoded and concatenated with the URL provided. For SVG + images you can for example use --webtex + https://latex.codecogs.com/svg.latex?. If no URL is specified, + the CodeCogs URL generating PNGs will be used + (https://latex.codecogs.com/png.latex?). Note: the --webtex + option will affect Markdown output as well as HTML, which is + useful if you’re targeting a version of Markdown without native + math support. + + ----kkaatteexx[==_U_R_L] + Use KaTeX to display embedded TeX math in HTML output. The _U_R_L + is the base URL for the KaTeX library. That directory should + contain a katex.min.js and a katex.min.css file. If a _U_R_L is + not provided, a link to the KaTeX CDN will be inserted. + + ----ggllaaddtteexx + Enclose TeX math in tags in HTML output. The resulting + HTML can then be processed by GladTeX to produce SVG images of + the typeset formulas and an HTML file with these images + embedded. + + + pandoc -s --gladtex input.md -o myfile.htex + gladtex -d image_dir myfile.htex + # produces myfile.html and images in image_dir + + + OOppttiioonnss ffoorr wwrraappppeerr ssccrriippttss + ----dduummpp--aarrggss + Print information about command-line arguments to _s_t_d_o_u_t, then + exit. This option is intended primarily for use in wrapper + scripts. The first line of output contains the name of the + output file specified with the -o option, or - (for _s_t_d_o_u_t) if + no output file was specified. The remaining lines contain the + command-line arguments, one per line, in the order they appear. + These do not include regular pandoc options and their arguments, + but do include any options appearing after a -- separator at the + end of the line. + + ----iiggnnoorree--aarrggss + Ignore command-line arguments (for use in wrapper scripts). + Regular pandoc options are not ignored. Thus, for example, + + + pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1 + + + is equivalent to + + + pandoc -o foo.html -s + + +EEXXIITT CCOODDEESS + If pandoc completes successfully, it will return exit code 0. Nonzero + exit codes have the following meanings: + + Code Error + ─────────────────────────────────────── + 3 PandocFailOnWarningError + 4 PandocAppError + 5 PandocTemplateError + 6 PandocOptionError + 21 PandocUnknownReaderError + 22 PandocUnknownWriterError + 23 PandocUnsupportedExtensionError + 24 PandocCiteprocError + 31 PandocEpubSubdirectoryError + 43 PandocPDFError + 44 PandocXMLError + 47 PandocPDFProgramNotFoundError + 61 PandocHttpError + 62 PandocShouldNeverHappenError + 63 PandocSomeError + 64 PandocParseError + 65 PandocParsecError + 66 PandocMakePDFError + 67 PandocSyntaxMapError + 83 PandocFilterError + 91 PandocMacroLoop + 92 PandocUTF8DecodingError + 93 PandocIpynbDecodingError + 94 PandocUnsupportedCharsetError + 97 PandocCouldNotFindDataFileError + 99 PandocResourceNotFound + +DDEEFFAAUULLTT FFIILLEESS + The --defaults option may be used to specify a package of options. + Here is a sample defaults file demonstrating all of the fields that may + be used: + + + from: markdown+emoji + # reader: may be used instead of from: + to: html5 + # writer: may be used instead of to: + + # leave blank for output to stdout: + output-file: + # leave blank for input from stdin, use [] for no input: + input-files: + - preface.md + - content.md + # or you may use input-file: with a single value + + # Include options from the specified defaults files. + # The files will be searched for first in the working directory + # and then in the defaults subdirectory of the user data directory. + # The files are included in the same order in which they appear in + # the list. Options specified in this defaults file always have + # priority over the included ones. + defaults: + - defsA + - defsB + + template: letter + standalone: true + self-contained: false + + # note that structured variables may be specified: + variables: + documentclass: book + classoption: + - twosides + - draft + + # metadata values specified here are parsed as literal + # string text, not markdown: + metadata: + author: + - Sam Smith + - Julie Liu + metadata-files: + - boilerplate.yaml + # or you may use metadata-file: with a single value + + # Note that these take files, not their contents: + include-before-body: [] + include-after-body: [] + include-in-header: [] + resource-path: ["."] + + # turn on built-in citation processing. Note that if you need + # control over when the citeproc processing is done relative + # to other filters, you should instead use `citeproc` in the + # list of `filters` (see below). + citeproc: true + csl: ieee + bibliography: + - foobar.bib + - barbaz.json + citation-abbreviations: abbrevs.json + + # Filters will be assumed to be Lua filters if they have + # the .lua extension, and json filters otherwise. But + # the filter type can also be specified explicitly, as shown. + # Filters are run in the order specified. + # To include the built-in citeproc filter, use either `citeproc` + # or `{type: citeproc}`. + filters: + - wordcount.lua + - type: json + path: foo.lua + + file-scope: false + + data-dir: + + # ERROR, WARNING, or INFO + verbosity: INFO + log-file: log.json + + # citeproc, natbib, or biblatex. This only affects LaTeX + # output. If you want to use citeproc to format citations, + # you should also set 'citeproc: true' (see above). + cite-method: citeproc + + # part, chapter, section, or default: + top-level-division: chapter + abbreviations: + + pdf-engine: pdflatex + pdf-engine-opts: + - "-shell-escape" + # you may also use pdf-engine-opt: with a single option + # pdf-engine-opt: "-shell-escape" + + # auto, preserve, or none + wrap: auto + columns: 78 + dpi: 72 + + extract-media: mediadir + + table-of-contents: true + toc-depth: 2 + number-sections: false + # a list of offsets at each heading level + number-offset: [0,0,0,0,0,0] + # toc: may also be used instead of table-of-contents: + shift-heading-level-by: 1 + section-divs: true + identifier-prefix: foo + title-prefix: "" + strip-empty-paragraphs: true + # lf, crlf, or native + eol: lf + strip-comments: false + indented-code-classes: [] + ascii: true + default-image-extension: ".jpg" + + # either a style name of a style definition file: + highlight-style: pygments + syntax-definitions: + - c.xml + # or you may use syntax-definition: with a single value + listings: false + + reference-doc: myref.docx + + # method is plain, webtex, gladtex, mathml, mathjax, katex + # you may specify a url with webtex, mathjax, katex + html-math-method: + method: mathjax + url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" + # none, references, or javascript + email-obfuscation: javascript + + tab-stop: 8 + preserve-tabs: true + + incremental: false + slide-level: 2 + + epub-subdirectory: EPUB + epub-metadata: meta.xml + epub-fonts: + - foobar.otf + epub-chapter-level: 1 + epub-cover-image: cover.jpg + + reference-links: true + # block, section, or document + reference-location: block + markdown-headings: setext + + # accept, reject, or all + track-changes: accept + + html-q-tags: false + css: + - site.css + + # none, all, or best + ipynb-output: best + + # A list of two-element lists + request-headers: + - ["User-Agent", "Mozilla/5.0"] + + fail-if-warnings: false + dump-args: false + ignore-args: false + trace: false + + + Fields that are omitted will just have their regular default values. + So a defaults file can be as simple as one line: + + + verbosity: INFO + + + In fields that expect a file path (or list of file paths), the + following syntax may be used to interpolate environment variables: + + + csl: ${HOME}/mycsldir/special.csl + + + ${USERDATA} may also be used; this will always resolve to the user data + directory that is current when the defaults file is parsed, regardless + of the setting of the environment variable USERDATA. + + ${.} will resolve to the directory containing the default file itself. + This allows you to refer to resources contained in that directory: + + + epub-cover-image: ${.}/cover.jpg + epub-metadata: ${.}/meta.xml + resource-path: + - . # the working directory from which pandoc is run + - ${.}/images # the images subdirectory of the directory + # containing this defaults file + + + This environment variable interpolation syntax _o_n_l_y works in fields + that expect file paths. + + Default files can be placed in the defaults subdirectory of the user + data directory and used from any directory. For example, one could + create a file specifying defaults for writing letters, save it as + letter.yaml in the defaults subdirectory of the user data directory, + and then invoke these defaults from any directory using pandoc + --defaults letter or pandoc -dletter. + + When multiple defaults are used, their contents will be combined. + + Note that, where command-line arguments may be repeated + (--metadata-file, --css, --include-in-header, --include-before-body, + --include-after-body, --variable, --metadata, --syntax-definition), the + values specified on the command line will combine with values specified + in the defaults file, rather than replacing them. + +TTEEMMPPLLAATTEESS + When the -s/--standalone option is used, pandoc uses a template to add + header and footer material that is needed for a self-standing document. + To see the default template that is used, just type + + + pandoc -D *FORMAT* + + + where _F_O_R_M_A_T is the name of the output format. A custom template can + be specified using the --template option. You can also override the + system default templates for a given output format _F_O_R_M_A_T by putting a + file templates/default.*FORMAT* in the user data directory (see + --data-dir, above). _E_x_c_e_p_t_i_o_n_s_: + + • For odt output, customize the default.opendocument template. + + • For pdf output, customize the default.latex template (or the + default.context template, if you use -t context, or the default.ms + template, if you use -t ms, or the default.html template, if you use + -t html). + + • docx and pptx have no template (however, you can use --reference-doc + to customize the output). + + Templates contain _v_a_r_i_a_b_l_e_s, which allow for the inclusion of arbitrary + information at any point in the file. They may be set at the command + line using the -V/--variable option. If a variable is not set, pandoc + will look for the key in the document’s metadata, which can be set + using either YAML metadata blocks or with the -M/--metadata option. In + addition, some variables are given default values by pandoc. See + Variables below for a list of variables used in pandoc’s default + templates. + + If you use custom templates, you may need to revise them as pandoc + changes. We recommend tracking the changes in the default templates, + and modifying your custom templates accordingly. An easy way to do + this is to fork the pandoc-templates repository and merge in changes + after each pandoc release. + + TTeemmppllaattee ssyynnttaaxx + CCoommmmeennttss + Anything between the sequence $-- and the end of the line will be + treated as a comment and omitted from the output. + + DDeelliimmiitteerrss + To mark variables and control structures in the template, either $...$ + or ${...} may be used as delimiters. The styles may also be mixed in + the same template, but the opening and closing delimiter must match in + each case. The opening delimiter may be followed by one or more spaces + or tabs, which will be ignored. The closing delimiter may be followed + by one or more spaces or tabs, which will be ignored. + + To include a literal $ in the document, use $$. + + IInntteerrppoollaatteedd vvaarriiaabblleess + A slot for an interpolated variable is a variable name surrounded by + matched delimiters. Variable names must begin with a letter and can + contain letters, numbers, _, -, and .. The keywords it, if, else, + endif, for, sep, and endfor may not be used as variable names. + Examples: + + + $foo$ + $foo.bar.baz$ + $foo_bar.baz-bim$ + $ foo $ + ${foo} + ${foo.bar.baz} + ${foo_bar.baz-bim} + ${ foo } + + + Variable names with periods are used to get at structured variable + values. So, for example, employee.salary will return the value of the + salary field of the object that is the value of the employee field. + + • If the value of the variable is simple value, it will be rendered + verbatim. (Note that no escaping is done; the assumption is that the + calling program will escape the strings appropriately for the output + format.) + + • If the value is a list, the values will be concatenated. + + • If the value is a map, the string true will be rendered. + + • Every other value will be rendered as the empty string. + + CCoonnddiittiioonnaallss + A conditional begins with if(variable) (enclosed in matched delimiters) + and ends with endif (enclosed in matched delimiters). It may + optionally contain an else (enclosed in matched delimiters). The if + section is used if variable has a non-empty value, otherwise the else + section is used (if present). Examples: + + + $if(foo)$bar$endif$ + + $if(foo)$ + $foo$ + $endif$ + + $if(foo)$ + part one + $else$ + part two + $endif$ + + ${if(foo)}bar${endif} + + ${if(foo)} + ${foo} + ${endif} + + ${if(foo)} + ${ foo.bar } + ${else} + no foo! + ${endif} + + + The keyword elseif may be used to simplify complex nested conditionals: + + + $if(foo)$ + XXX + $elseif(bar)$ + YYY + $else$ + ZZZ + $endif$ + + + FFoorr llooooppss + A for loop begins with for(variable) (enclosed in matched delimiters) + and ends with endfor (enclosed in matched delimiters. + + • If variable is an array, the material inside the loop will be + evaluated repeatedly, with variable being set to each value of the + array in turn, and concatenated. + + • If variable is a map, the material inside will be set to the map. + + • If the value of the associated variable is not an array or a map, a + single iteration will be performed on its value. + + Examples: + + + $for(foo)$$foo$$sep$, $endfor$ + + $for(foo)$ + - $foo.last$, $foo.first$ + $endfor$ + + ${ for(foo.bar) } + - ${ foo.bar.last }, ${ foo.bar.first } + ${ endfor } + + $for(mymap)$ + $it.name$: $it.office$ + $endfor$ + + + You may optionally specify a separator between consecutive values using + sep (enclosed in matched delimiters). The material between sep and the + endfor is the separator. + + + ${ for(foo) }${ foo }${ sep }, ${ endfor } + + + Instead of using variable inside the loop, the special anaphoric + keyword it may be used. + + + ${ for(foo.bar) } + - ${ it.last }, ${ it.first } + ${ endfor } + + + PPaarrttiiaallss + Partials (subtemplates stored in different files) may be included by + using the name of the partial, followed by (), for example: + + + ${ styles() } + + + Partials will be sought in the directory containing the main template. + The file name will be assumed to have the same extension as the main + template if it lacks an extension. When calling the partial, the full + name including file extension can also be used: + + + ${ styles.html() } + + + (If a partial is not found in the directory of the template and the + template path is given as a relative path, it will also be sought in + the templates subdirectory of the user data directory.) + + Partials may optionally be applied to variables using a colon: + + + ${ date:fancy() } + + ${ articles:bibentry() } + + + If articles is an array, this will iterate over its values, applying + the partial bibentry() to each one. So the second example above is + equivalent to + + + ${ for(articles) } + ${ it:bibentry() } + ${ endfor } + + + Note that the anaphoric keyword it must be used when iterating over + partials. In the above examples, the bibentry partial should contain + it.title (and so on) instead of articles.title. + + Final newlines are omitted from included partials. + + Partials may include other partials. + + A separator between values of an array may be specified in square + brackets, immediately after the variable name or partial: + + + ${months[, ]}$ + + ${articles:bibentry()[; ]$ + + + The separator in this case is literal and (unlike with sep in an + explicit for loop) cannot contain interpolated variables or other + template directives. + + NNeessttiinngg + To ensure that content is “nested,” that is, subsequent lines indented, + use the ^ directive: + + + $item.number$ $^$$item.description$ ($item.price$) + + + In this example, if item.description has multiple lines, they will all + be indented to line up with the first line: + + + 00123 A fine bottle of 18-year old + Oban whiskey. ($148) + + + To nest multiple lines to the same level, align them with the ^ + directive in the template. For example: + + + $item.number$ $^$$item.description$ ($item.price$) + (Available til $item.sellby$.) + + + will produce + + + 00123 A fine bottle of 18-year old + Oban whiskey. ($148) + (Available til March 30, 2020.) + + + If a variable occurs by itself on a line, preceded by whitespace and + not followed by further text or directives on the same line, and the + variable’s value contains multiple lines, it will be nested + automatically. + + BBrreeaakkaabbllee ssppaacceess + Normally, spaces in the template itself (as opposed to values of the + interpolated variables) are not breakable, but they can be made + breakable in part of the template by using the ~ keyword (ended with + another ~). + + + $~$This long line may break if the document is rendered + with a short line length.$~$ + + + PPiippeess + A pipe transforms the value of a variable or partial. Pipes are + specified using a slash (/) between the variable name (or partial) and + the pipe name. Example: + + + $for(name)$ + $name/uppercase$ + $endfor$ + + $for(metadata/pairs)$ + - $it.key$: $it.value$ + $endfor$ + + $employee:name()/uppercase$ + + + Pipes may be chained: + + + $for(employees/pairs)$ + $it.key/alpha/uppercase$. $it.name$ + $endfor$ + + + Some pipes take parameters: + + + |----------------------|------------| + $for(employee)$ + $it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$ + $endfor$ + |----------------------|------------| + + + Currently the following pipes are predefined: + + • pairs: Converts a map or array to an array of maps, each with key and + value fields. If the original value was an array, the key will be + the array index, starting with 1. + + • uppercase: Converts text to uppercase. + + • lowercase: Converts text to lowercase. + + • length: Returns the length of the value: number of characters for a + textual value, number of elements for a map or array. + + • reverse: Reverses a textual value or array, and has no effect on + other values. + + • first: Returns the first value of an array, if applied to a non-empty + array; otherwise returns the original value. + + • last: Returns the last value of an array, if applied to a non-empty + array; otherwise returns the original value. + + • rest: Returns all but the first value of an array, if applied to a + non-empty array; otherwise returns the original value. + + • allbutlast: Returns all but the last value of an array, if applied to + a non-empty array; otherwise returns the original value. + + • chomp: Removes trailing newlines (and breakable space). + + • nowrap: Disables line wrapping on breakable spaces. + + • alpha: Converts textual values that can be read as an integer into + lowercase alphabetic characters a..z (mod 26). This can be used to + get lettered enumeration from array indices. To get uppercase + letters, chain with uppercase. + + • roman: Converts textual values that can be read as an integer into + lowercase roman numerials. This can be used to get lettered + enumeration from array indices. To get uppercase roman, chain with + uppercase. + + • left n "leftborder" "rightborder": Renders a textual value in a block + of width n, aligned to the left, with an optional left and right + border. Has no effect on other values. This can be used to align + material in tables. Widths are positive integers indicating the + number of characters. Borders are strings inside double quotes; + literal " and \ characters must be backslash-escaped. + + • right n "leftborder" "rightborder": Renders a textual value in a + block of width n, aligned to the right, and has no effect on other + values. + + • center n "leftborder" "rightborder": Renders a textual value in a + block of width n, aligned to the center, and has no effect on other + values. + + VVaarriiaabblleess + MMeettaaddaattaa vvaarriiaabblleess + ttiittllee, aauutthhoorr, ddaattee + allow identification of basic aspects of the document. Included + in PDF metadata through LaTeX and ConTeXt. These can be set + through a pandoc title block, which allows for multiple authors, + or through a YAML metadata block: + + + --- + author: + - Aristotle + - Peter Abelard + ... + + + Note that if you just want to set PDF or HTML metadata, without + including a title block in the document itself, you can set the + title-meta, author-meta, and date-meta variables. (By default + these are set automatically, based on title, author, and date.) + The page title in HTML is set by pagetitle, which is equal to + title by default. + + ssuubbttiittllee + document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and + docx documents + + aabbssttrraacctt + document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx + documents + + kkeeyywwoorrddss + list of keywords to be included in HTML, PDF, ODT, pptx, docx + and AsciiDoc metadata; repeat as for author, above + + ssuubbjjeecctt + document subject, included in ODT, PDF, docx and pptx metadata + + ddeessccrriippttiioonn + document description, included in ODT, docx and pptx metadata. + Some applications show this as Comments metadata. + + ccaatteeggoorryy + document category, included in docx and pptx metadata + + Additionally, any root-level string metadata, not included in ODT, docx + or pptx metadata is added as a _c_u_s_t_o_m _p_r_o_p_e_r_t_y. The following YAML + metadata block for instance: + + + --- + title: 'This is the title' + subtitle: "This is the subtitle" + author: + - Author One + - Author Two + description: | + This is a long + description. + + It consists of two paragraphs + ... + + + will include title, author and description as standard document + properties and subtitle as a custom property when converting to docx, + ODT or pptx. + + LLaanngguuaaggee vvaarriiaabblleess + llaanngg identifies the main language of the document using IETF language + tags (following the BCP 47 standard), such as en or en-GB. The + Language subtag lookup tool can look up or verify these tags. + This affects most formats, and controls hyphenation in PDF + output when using LaTeX (through babel and polyglossia) or + ConTeXt. + + Use native pandoc Divs and Spans with the lang attribute to + switch the language: + + + --- + lang: en-GB + ... + + Text in the main document language (British English). + + ::: {lang=fr-CA} + > Cette citation est écrite en français canadien. + ::: + + More text in English. ['Zitat auf Deutsch.']{lang=de} + + + ddiirr the base script direction, either rtl (right-to-left) or ltr + (left-to-right). + + For bidirectional documents, native pandoc spans and divs with + the dir attribute (value rtl or ltr) can be used to override the + base direction in some output formats. This may not always be + necessary if the final renderer (e.g. the browser, when + generating HTML) supports the Unicode Bidirectional Algorithm. + + When using LaTeX for bidirectional documents, only the xelatex + engine is fully supported (use --pdf-engine=xelatex). + + VVaarriiaabblleess ffoorr HHTTMMLL + ddooccuummeenntt--ccssss + Enables inclusion of most of the CSS in the styles.html partial + (have a look with pandoc + --print-default-data-file=templates/styles.html). Unless you + use --css, this variable is set to true by default. You can + disable it with e.g. pandoc -M document-css=false. + + mmaaiinnffoonntt + sets the CSS font-family property on the html element. + + ffoonnttssiizzee + sets the base CSS font-size, which you’d usually set to + e.g. 20px, but it also accepts pt (12pt = 16px in most + browsers). + + ffoonnttccoolloorr + sets the CSS color property on the html element. + + lliinnkkccoolloorr + sets the CSS color property on all links. + + mmoonnooffoonntt + sets the CSS font-family property on code elements. + + mmoonnoobbaacckkggrroouunnddccoolloorr + sets the CSS background-color property on code elements and adds + extra padding. + + lliinneessttrreettcchh + sets the CSS line-height property on the html element, which is + preferred to be unitless. + + bbaacckkggrroouunnddccoolloorr + sets the CSS background-color property on the html element. + + mmaarrggiinn--lleefftt, mmaarrggiinn--rriigghhtt, mmaarrggiinn--ttoopp, mmaarrggiinn--bboottttoomm + sets the corresponding CSS padding properties on the body + element. + + To override or extend some CSS for just one document, include for + example: + + + --- + header-includes: | + + --- + + + VVaarriiaabblleess ffoorr HHTTMMLL mmaatthh + ccllaassssooppttiioonn + when using KaTeX, you can render display math equations flush + left using YAML metadata or with -M classoption=fleqn. + + VVaarriiaabblleess ffoorr HHTTMMLL sslliiddeess + These affect HTML output when [producing slide shows with pandoc]. + + iinnssttiittuuttee + author affiliations: can be a list when there are multiple + authors + + rreevveeaalljjss--uurrll + base URL for reveal.js documents (defaults to + https://unpkg.com/reveal.js@^4/) + + ss55--uurrll base URL for S5 documents (defaults to s5/default) + + sslliiddyy--uurrll + base URL for Slidy documents (defaults to + https://www.w3.org/Talks/Tools/Slidy2) + + sslliiddeeoouuss--uurrll + base URL for Slideous documents (defaults to slideous) + + ttiittllee--sslliiddee--aattttrriibbuutteess + additional attributes for the title slide of reveal.js slide + shows. See background in reveal.js and beamer for an example. + + All reveal.js configuration options are available as variables. To + turn off boolean flags that default to true in reveal.js, use 0. + + VVaarriiaabblleess ffoorr BBeeaammeerr sslliiddeess + These variables change the appearance of PDF slides using beamer. + + aassppeeccttrraattiioo + slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for + 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2) + + bbeeaammeerraarrttiiccllee + produce an article from Beamer slides + + bbeeaammeerrooppttiioonn + add extra beamer option with \setbeameroption{} + + iinnssttiittuuttee + author affiliations: can be a list when there are multiple + authors + + llooggoo logo image for slides + + nnaavviiggaattiioonn + controls navigation symbols (default is empty for no navigation + symbols; other valid values are frame, vertical, and horizontal) + + sseeccttiioonn--ttiittlleess + enables “title pages” for new sections (default is true) + + tthheemmee, ccoolloorrtthheemmee, ffoonntttthheemmee, iinnnneerrtthheemmee, oouutteerrtthheemmee + beamer themes + + tthheemmeeooppttiioonnss + options for LaTeX beamer themes (a list). + + ttiittlleeggrraapphhiicc + image for title slide + + VVaarriiaabblleess ffoorr PPoowweerrPPooiinntt + These variables control the visual aspects of a slide show that are not + easily controlled via templates. + + mmoonnooffoonntt + font to use for code. + + VVaarriiaabblleess ffoorr LLaaTTeeXX + Pandoc uses these variables when creating a PDF with a LaTeX engine. + + LLaayyoouutt + bblloocckk--hheeaaddiinnggss + make \paragraph and \subparagraph (fourth- and fifth-level + headings, or fifth- and sixth-level with book classes) free- + standing rather than run-in; requires further formatting to + distinguish from \subsubsection (third- or fourth-level + headings). Instead of using this option, KOMA-Script can adjust + headings more extensively: + + + --- + documentclass: scrartcl + header-includes: | + \RedeclareSectionCommand[ + beforeskip=-10pt plus -2pt minus -1pt, + afterskip=1sp plus -1sp minus 1sp, + font=\normalfont\itshape]{paragraph} + \RedeclareSectionCommand[ + beforeskip=-10pt plus -2pt minus -1pt, + afterskip=1sp plus -1sp minus 1sp, + font=\normalfont\scshape, + indent=0pt]{subparagraph} + ... + + + ccllaassssooppttiioonn + option for document class, e.g. oneside; repeat for multiple + options: + + + --- + classoption: + - twocolumn + - landscape + ... + + + ddooccuummeennttccllaassss + document class: usually one of the standard classes, article, + book, and report; the KOMA-Script equivalents, scrartcl, + scrbook, and scrreprt, which default to smaller margins; or + memoir + + ggeeoommeettrryy + option for geometry package, e.g. margin=1in; repeat for + multiple options: + + + --- + geometry: + - top=30mm + - left=20mm + - heightrounded + ... + + + hhyyppeerrrreeffooppttiioonnss + option for hyperref package, e.g. linktoc=all; repeat for + multiple options: + + + --- + hyperrefoptions: + - linktoc=all + - pdfwindowui + - pdfpagemode=FullScreen + ... + + + iinnddeenntt if true, pandoc will use document class settings for indentation + (the default LaTeX template otherwise removes indentation and + adds space between paragraphs) + + lliinneessttrreettcchh + adjusts line spacing using the setspace package, e.g. 1.25, 1.5 + + mmaarrggiinn--lleefftt, mmaarrggiinn--rriigghhtt, mmaarrggiinn--ttoopp, mmaarrggiinn--bboottttoomm + sets margins if geometry is not used (otherwise geometry + overrides these) + + ppaaggeessttyyllee + control \pagestyle{}: the default article class supports plain + (default), empty (no running heads or page numbers), and + headings (section titles in running heads) + + ppaappeerrssiizzee + paper size, e.g. letter, a4 + + sseeccnnuummddeepptthh + numbering depth for sections (with --number-sections option or + numbersections variable) + + FFoonnttss + ffoonntteenncc + allows font encoding to be specified through fontenc package + (with pdflatex); default is T1 (see LaTeX font encodings guide) + + ffoonnttffaammiillyy + font package for use with pdflatex: TeX Live includes many + options, documented in the LaTeX Font Catalogue. The default is + Latin Modern. + + ffoonnttffaammiillyyooppttiioonnss + options for package used as fontfamily; repeat for multiple + options. For example, to use the Libertine font with + proportional lowercase (old-style) figures through the + libertinus package: + + + --- + fontfamily: libertinus + fontfamilyoptions: + - osf + - p + ... + + + ffoonnttssiizzee + font size for body text. The standard classes allow 10pt, 11pt, + and 12pt. To use another size, set documentclass to one of the + KOMA-Script classes, such as scrartcl or scrbook. + + mmaaiinnffoonntt, ssaannssffoonntt, mmoonnooffoonntt, mmaatthhffoonntt, CCJJKKmmaaiinnffoonntt + font families for use with xelatex or lualatex: take the name of + any system font, using the fontspec package. CJKmainfont uses + the xecjk package. + + mmaaiinnffoonnttooppttiioonnss, ssaannssffoonnttooppttiioonnss, mmoonnooffoonnttooppttiioonnss, mmaatthhffoonnttooppttiioonnss, + CCJJKKooppttiioonnss + options to use with mainfont, sansfont, monofont, mathfont, + CJKmainfont in xelatex and lualatex. Allow for any choices + available through fontspec; repeat for multiple options. For + example, to use the TeX Gyre version of Palatino with lowercase + figures: + + + --- + mainfont: TeX Gyre Pagella + mainfontoptions: + - Numbers=Lowercase + - Numbers=Proportional + ... + + + mmiiccrroottyyppeeooppttiioonnss + options to pass to the microtype package + + LLiinnkkss + ccoolloorrlliinnkkss + add color to link text; automatically enabled if any of + linkcolor, filecolor, citecolor, urlcolor, or toccolor are set + + lliinnkkccoolloorr, ffiilleeccoolloorr, cciitteeccoolloorr, uurrllccoolloorr, ttooccccoolloorr + color for internal links, external links, citation links, linked + URLs, and links in table of contents, respectively: uses options + allowed by xcolor, including the dvipsnames, svgnames, and + x11names lists + + lliinnkkss--aass--nnootteess + causes links to be printed as footnotes + + FFrroonntt mmaatttteerr + llooff, lloott + include list of figures, list of tables + + tthhaannkkss contents of acknowledgments footnote after document title + + ttoocc include table of contents (can also be set using + --toc/--table-of-contents) + + ttoocc--ddeepptthh + level of section to include in table of contents + + BBiibbLLaaTTeeXX BBiibblliiooggrraapphhiieess + These variables function when using BibLaTeX for citation rendering. + + bbiibbllaatteexxooppttiioonnss + list of options for biblatex + + bbiibblliioo--ssttyyllee + bibliography style, when used with --natbib and --biblatex. + + bbiibblliioo--ttiittllee + bibliography title, when used with --natbib and --biblatex. + + bbiibblliiooggrraapphhyy + bibliography to use for resolving references + + nnaattbbiibbooppttiioonnss + list of options for natbib + + VVaarriiaabblleess ffoorr CCoonnTTeeXXtt + Pandoc uses these variables when creating a PDF with ConTeXt. + + ffoonnttssiizzee + font size for body text (e.g. 10pt, 12pt) + + hheeaaddeerrtteexxtt, ffooootteerrtteexxtt + text to be placed in running header or footer (see ConTeXt + Headers and Footers); repeat up to four times for different + placement + + iinnddeennttiinngg + controls indentation of paragraphs, e.g. yes,small,next (see + ConTeXt Indentation); repeat for multiple options + + iinntteerrlliinneessppaaccee + adjusts line spacing, e.g. 4ex (using setupinterlinespace); + repeat for multiple options + + llaayyoouutt options for page margins and text arrangement (see ConTeXt + Layout); repeat for multiple options + + lliinnkkccoolloorr, ccoonnttrraassttccoolloorr + color for links outside and inside a page, e.g. red, blue (see + ConTeXt Color) + + lliinnkkssttyyllee + typeface style for links, e.g. normal, bold, slanted, + boldslanted, type, cap, small + + llooff, lloott + include list of figures, list of tables + + mmaaiinnffoonntt, ssaannssffoonntt, mmoonnooffoonntt, mmaatthhffoonntt + font families: take the name of any system font (see ConTeXt + Font Switching) + + mmaarrggiinn--lleefftt, mmaarrggiinn--rriigghhtt, mmaarrggiinn--ttoopp, mmaarrggiinn--bboottttoomm + sets margins, if layout is not used (otherwise layout overrides + these) + + ppaaggeennuummbbeerriinngg + page number style and location (using setuppagenumbering); + repeat for multiple options + + ppaappeerrssiizzee + paper size, e.g. letter, A4, landscape (see ConTeXt Paper + Setup); repeat for multiple options + + ppddffaa adds to the preamble the setup necessary to generate PDF/A of + the type specified, e.g. 1a:2005, 2a. If no type is specified + (i.e. the value is set to True, by e.g. --metadata=pdfa or + pdfa: true in a YAML metadata block), 1b:2005 will be used as + default, for reasons of backwards compatibility. Using + --variable=pdfa without specified value is not supported. To + successfully generate PDF/A the required ICC color profiles have + to be available and the content and all included files (such as + images) have to be standard conforming. The ICC profiles and + output intent may be specified using the variables + pdfaiccprofile and pdfaintent. See also ConTeXt PDFA for more + details. + + ppddffaaiiccccpprrooffiillee + when used in conjunction with pdfa, specifies the ICC profile to + use in the PDF, e.g. default.cmyk. If left unspecified, + sRGB.icc is used as default. May be repeated to include + multiple profiles. Note that the profiles have to be available + on the system. They can be obtained from ConTeXt ICC Profiles. + + ppddffaaiinntteenntt + when used in conjunction with pdfa, specifies the output intent + for the colors, e.g. ISO coated v2 300\letterpercent\space (ECI) + If left unspecified, sRGB IEC61966-2.1 is used as default. + + ttoocc include table of contents (can also be set using + --toc/--table-of-contents) + + wwhhiitteessppaaccee + spacing between paragraphs, e.g. none, small (using + setupwhitespace) + + iinncclluuddeessoouurrccee + include all source documents as file attachments in the PDF file + + VVaarriiaabblleess ffoorr wwkkhhttmmllttooppddff + Pandoc uses these variables when creating a PDF with wkhtmltopdf. The + --css option also affects the output. + + ffooootteerr--hhttmmll, hheeaaddeerr--hhttmmll + add information to the header and footer + + mmaarrggiinn--lleefftt, mmaarrggiinn--rriigghhtt, mmaarrggiinn--ttoopp, mmaarrggiinn--bboottttoomm + set the page margins + + ppaappeerrssiizzee + sets the PDF paper size + + VVaarriiaabblleess ffoorr mmaann ppaaggeess + aaddjjuussttiinngg + adjusts text to left (l), right (r), center (c), or both (b) + margins + + ffooootteerr footer in man pages + + hheeaaddeerr header in man pages + + hhyypphheennaattee + if true (the default), hyphenation will be used + + sseeccttiioonn + section number in man pages + + VVaarriiaabblleess ffoorr mmss + ffoonnttffaammiillyy + font family (e.g. T or P) + + iinnddeenntt paragraph indent (e.g. 2m) + + lliinneehheeiigghhtt + line height (e.g. 12p) + + ppooiinnttssiizzee + point size (e.g. 10p) + + VVaarriiaabblleess sseett aauuttoommaattiiccaallllyy + Pandoc sets these variables automatically in response to options or + document contents; users can also modify them. These vary depending on + the output format, and include the following: + + bbooddyy body of document + + ddaattee--mmeettaa + the date variable converted to ISO 8601 YYYY-MM-DD, included in + all HTML based formats (dzslides, epub, html, html4, html5, + revealjs, s5, slideous, slidy). The recognized formats for date + are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy + (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy + (e.g. Apr. 02, 2018 or April 02, + 2018),yyyy[mm[dd]]](e.g.20180402, 201804 or 2018). + + hheeaaddeerr--iinncclluuddeess + contents specified by -H/--include-in-header (may have multiple + values) + + iinncclluuddee--bbeeffoorree + contents specified by -B/--include-before-body (may have + multiple values) + + iinncclluuddee--aafftteerr + contents specified by -A/--include-after-body (may have multiple + values) + + mmeettaa--jjssoonn + JSON representation of all of the document’s metadata. Field + values are transformed to the selected output format. + + nnuummbbeerrsseeccttiioonnss + non-null value if -N/--number-sections was specified + + ssoouurrcceeffiillee, oouuttppuuttffiillee + source and destination filenames, as given on the command line. + sourcefile can also be a list if input comes from multiple + files, or empty if input is from stdin. You can use the + following snippet in your template to distinguish them: + + + $if(sourcefile)$ + $for(sourcefile)$ + $sourcefile$ + $endfor$ + $else$ + (stdin) + $endif$ + + + Similarly, outputfile can be - if output goes to the terminal. + + If you need absolute paths, use e.g. $curdir$/$sourcefile$. + + ccuurrddiirr working directory from which pandoc is run. + + ttoocc non-null value if --toc/--table-of-contents was specified + + ttoocc--ttiittllee + title of table of contents (works only with EPUB, HTML, + opendocument, odt, docx, pptx, beamer, LaTeX) + +EEXXTTEENNSSIIOONNSS + The behavior of some of the readers and writers can be adjusted by + enabling or disabling various extensions. + + An extension can be enabled by adding +EXTENSION to the format name and + disabled by adding -EXTENSION. For example, --from + markdown_strict+footnotes is strict Markdown with footnotes enabled, + while --from markdown-footnotes-pipe_tables is pandoc’s Markdown + without footnotes or pipe tables. + + The markdown reader and writer make by far the most use of extensions. + Extensions only used by them are therefore covered in the section + Pandoc’s Markdown below (See Markdown variants for commonmark and gfm.) + In the following, extensions that also work for other formats are + covered. + + Note that markdown extensions added to the ipynb format affect Markdown + cells in Jupyter notebooks (as do command-line options like + --atx-headers). + + TTyyppooggrraapphhyy + EExxtteennssiioonn:: ssmmaarrtt + Interpret straight quotes as curly quotes, --- as em-dashes, -- as + en-dashes, and ... as ellipses. Nonbreaking spaces are inserted after + certain abbreviations, such as “Mr.” + + This extension can be enabled/disabled for the following formats: + + input formats + markdown, commonmark, latex, mediawiki, org, rst, twiki + + output formats + markdown, latex, context, rst + + enabled by default in + markdown, latex, context (both input and output) + + Note: If you are _w_r_i_t_i_n_g Markdown, then the smart extension has the + reverse effect: what would have been curly quotes comes out straight. + + In LaTeX, smart means to use the standard TeX ligatures for quotation + marks (`` and '' for double quotes, ` and ' for single quotes) and + dashes (-- for en-dash and --- for em-dash). If smart is disabled, + then in reading LaTeX pandoc will parse these characters literally. In + writing LaTeX, enabling smart tells pandoc to use the ligatures when + possible; if smart is disabled pandoc will use unicode quotation mark + and dash characters. + + HHeeaaddiinnggss aanndd sseeccttiioonnss + EExxtteennssiioonn:: aauuttoo__iiddeennttiiffiieerrss + A heading without an explicitly specified identifier will be + automatically assigned a unique identifier based on the heading text. + + This extension can be enabled/disabled for the following formats: + + input formats + markdown, latex, rst, mediawiki, textile + + output formats + markdown, muse + + enabled by default in + markdown, muse + + The default algorithm used to derive the identifier from the heading + text is: + + • Remove all formatting, links, etc. + + • Remove all footnotes. + + • Remove all non-alphanumeric characters, except underscores, hyphens, + and periods. + + • Replace all spaces and newlines with hyphens. + + • Convert all alphabetic characters to lowercase. + + • Remove everything up to the first letter (identifiers may not begin + with a number or punctuation mark). + + • If nothing is left after this, use the identifier section. + + Thus, for example, + + Heading Identifier + ────────────────────────────────────────────────────── + Heading identifiers in heading-identifiers-in-html + HTML + Maître d'hôtel maître-dhôtel + *Dogs*?--in *my* house? dogs--in-my-house + [HTML], [S5], or [RTF]? html-s5-or-rtf + 3. Applications applications + 33 section + + These rules should, in most cases, allow one to determine the + identifier from the heading text. The exception is when several + headings have the same text; in this case, the first will get an + identifier as described above; the second will get the same identifier + with -1 appended; the third with -2; and so on. + + (However, a different algorithm is used if gfm_auto_identifiers is + enabled; see below.) + + These identifiers are used to provide link targets in the table of + contents generated by the --toc|--table-of-contents option. They also + make it easy to provide links from one section of a document to + another. A link to this section, for example, might look like this: + + + See the section on + [heading identifiers](#heading-identifiers-in-html-latex-and-context). + + + Note, however, that this method of providing links to sections works + only in HTML, LaTeX, and ConTeXt formats. + + If the --section-divs option is specified, then each section will be + wrapped in a section (or a div, if html4 was specified), and the + identifier will be attached to the enclosing
(or
) tag + rather than the heading itself. This allows entire sections to be + manipulated using JavaScript or treated differently in CSS. + + EExxtteennssiioonn:: aasscciiii__iiddeennttiiffiieerrss + Causes the identifiers produced by auto_identifiers to be pure ASCII. + Accents are stripped off of accented Latin letters, and non-Latin + letters are omitted. + + EExxtteennssiioonn:: ggffmm__aauuttoo__iiddeennttiiffiieerrss + Changes the algorithm used by auto_identifiers to conform to GitHub’s + method. Spaces are converted to dashes (-), uppercase characters to + lowercase characters, and punctuation characters other than - and _ are + removed. Emojis are replaced by their names. + + MMaatthh IInnppuutt + The extensions tex_math_dollars, tex_math_single_backslash, and + tex_math_double_backslash are described in the section about Pandoc’s + Markdown. + + However, they can also be used with HTML input. This is handy for + reading web pages formatted using MathJax, for example. + + RRaaww HHTTMMLL//TTeeXX + The following extensions are described in more detail in their + respective sections of Pandoc’s Markdown: + + • raw_html allows HTML elements which are not representable in pandoc’s + AST to be parsed as raw HTML. By default, this is disabled for HTML + input. + + • raw_tex allows raw LaTeX, TeX, and ConTeXt to be included in a + document. This extension can be enabled/disabled for the following + formats (in addition to markdown): + + input formats + latex, textile, html (environments, \ref, and \eqref only), + ipynb + + output formats + textile, commonmark + + Note: as applied to ipynb, raw_html and raw_tex affect not only raw + TeX in markdown cells, but data with mime type text/html in output + cells. Since the ipynb reader attempts to preserve the richest + possible outputs when several options are given, you will get best + results if you disable raw_html and raw_tex when converting to + formats like docx which don’t allow raw html or tex. + + • native_divs causes HTML div elements to be parsed as native pandoc + Div blocks. If you want them to be parsed as raw HTML, use -f + html-native_divs+raw_html. + + • native_spans causes HTML span elements to be parsed as native pandoc + Span inlines. If you want them to be parsed as raw HTML, use -f + html-native_spans+raw_html. If you want to drop all divs and spans + when converting HTML to Markdown, you can use pandoc -f + html-native_divs-native_spans -t markdown. + + LLiitteerraattee HHaasskkeellll ssuuppppoorrtt + EExxtteennssiioonn:: lliitteerraattee__hhaasskkeellll + Treat the document as literate Haskell source. + + This extension can be enabled/disabled for the following formats: + + input formats + markdown, rst, latex + + output formats + markdown, rst, latex, html + + If you append +lhs (or +literate_haskell) to one of the formats above, + pandoc will treat the document as literate Haskell source. This means + that + + • In Markdown input, “bird track” sections will be parsed as Haskell + code rather than block quotations. Text between \begin{code} and + \end{code} will also be treated as Haskell code. For ATX-style + headings the character `=' will be used instead of `#'. + + • In Markdown output, code blocks with classes haskell and literate + will be rendered using bird tracks, and block quotations will be + indented one space, so they will not be treated as Haskell code. In + addition, headings will be rendered setext-style (with underlines) + rather than ATX-style (with `#' characters). (This is because ghc + treats `#' characters in column 1 as introducing line numbers.) + + • In restructured text input, “bird track” sections will be parsed as + Haskell code. + + • In restructured text output, code blocks with class haskell will be + rendered using bird tracks. + + • In LaTeX input, text in code environments will be parsed as Haskell + code. + + • In LaTeX output, code blocks with class haskell will be rendered + inside code environments. + + • In HTML output, code blocks with class haskell will be rendered with + class literatehaskell and bird tracks. + + Examples: + + + pandoc -f markdown+lhs -t html + + + reads literate Haskell source formatted with Markdown conventions and + writes ordinary HTML (without bird tracks). + + + pandoc -f markdown+lhs -t html+lhs + + + writes HTML with the Haskell code in bird tracks, so it can be copied + and pasted as literate Haskell source. + + Note that GHC expects the bird tracks in the first column, so indented + literate code blocks (e.g. inside an itemized environment) will not be + picked up by the Haskell compiler. + + OOtthheerr eexxtteennssiioonnss + EExxtteennssiioonn:: eemmppttyy__ppaarraaggrraapphhss + Allows empty paragraphs. By default empty paragraphs are omitted. + + This extension can be enabled/disabled for the following formats: + + input formats + docx, html + + output formats + docx, odt, opendocument, html + + EExxtteennssiioonn:: nnaattiivvee__nnuummbbeerriinngg + Enables native numbering of figures and tables. Enumeration starts at + 1. + + This extension can be enabled/disabled for the following formats: + + output formats + odt, opendocument + + EExxtteennssiioonn:: xxrreeffss__nnaammee + Links to headings, figures and tables inside the document are + substituted with cross-references that will use the name or caption of + the referenced item. The original link text is replaced once the + generated document is refreshed. This extension can be combined with + xrefs_number in which case numbers will appear before the name. + + Text in cross-references is only made consistent with the referenced + item once the document has been refreshed. + + This extension can be enabled/disabled for the following formats: + + output formats + odt, opendocument + + EExxtteennssiioonn:: xxrreeffss__nnuummbbeerr + Links to headings, figures and tables inside the document are + substituted with cross-references that will use the number of the + referenced item. The original link text is discarded. This extension + can be combined with xrefs_name in which case the name or caption + numbers will appear after the number. + + For the xrefs_number to be useful heading numbers must be enabled in + the generated document, also table and figure captions must be enabled + using for example the native_numbering extension. + + Numbers in cross-references are only visible in the final document once + it has been refreshed. + + This extension can be enabled/disabled for the following formats: + + output formats + odt, opendocument + + EExxtteennssiioonn:: ssttyylleess + When converting from docx, read all docx styles as divs (for paragraph + styles) and spans (for character styles) regardless of whether pandoc + understands the meaning of these styles. This can be used with docx + custom styles. Disabled by default. + + input formats + docx + + EExxtteennssiioonn:: aammuussee + In the muse input format, this enables Text::Amuse extensions to Emacs + Muse markup. + + EExxtteennssiioonn:: rraaww__mmaarrkkddoowwnn + In the ipynb input format, this causes Markdown cells to be included as + raw Markdown blocks (allowing lossless round-tripping) rather than + being parsed. Use this only when you are targeting ipynb or a + markdown-based output format. + + EExxtteennssiioonn:: cciittaattiioonnss + Some aspects of Pandoc’s Markdown citation syntax are also accepted in + org input. + + EExxtteennssiioonn:: eelleemmeenntt__cciittaattiioonnss + In the jats output formats, this causes reference items to be replaced + with elements. These elements are not influenced by + CSL styles, but all information on the item is included in tags. + + EExxtteennssiioonn:: nnttbb + In the context output format this enables the use of Natural Tables + (TABLE) instead of the default Extreme Tables (xtables). Natural + tables allow more fine-grained global customization but come at a + performance penalty compared to extreme tables. + +PPAANNDDOOCC’’SS MMAARRKKDDOOWWNN + Pandoc understands an extended and slightly revised version of John + Gruber’s Markdown syntax. This document explains the syntax, noting + differences from standard Markdown. Except where noted, these + differences can be suppressed by using the markdown_strict format + instead of markdown. Extensions can be enabled or disabled to specify + the behavior more granularly. They are described in the following. + See also Extensions above, for extensions that work also on other + formats. + + PPhhiilloossoopphhyy + Markdown is designed to be easy to write, and, even more importantly, + easy to read: + + A Markdown-formatted document should be publishable as-is, as + plain text, without looking like it’s been marked up with tags + or formatting instructions. – John Gruber + + This principle has guided pandoc’s decisions in finding syntax for + tables, footnotes, and other extensions. + + There is, however, one respect in which pandoc’s aims are different + from the original aims of Markdown. Whereas Markdown was originally + designed with HTML generation in mind, pandoc is designed for multiple + output formats. Thus, while pandoc allows the embedding of raw HTML, + it discourages it, and provides other, non-HTMLish ways of representing + important document elements like definition lists, tables, mathematics, + and footnotes. + + PPaarraaggrraapphhss + A paragraph is one or more lines of text followed by one or more blank + lines. Newlines are treated as spaces, so you can reflow your + paragraphs as you like. If you need a hard line break, put two or more + spaces at the end of a line. + + EExxtteennssiioonn:: eessccaappeedd__lliinnee__bbrreeaakkss + A backslash followed by a newline is also a hard line break. Note: in + multiline and grid table cells, this is the only way to create a hard + line break, since trailing spaces in the cells are ignored. + + HHeeaaddiinnggss + There are two kinds of headings: Setext and ATX. + + SSeetteexxtt--ssttyyllee hheeaaddiinnggss + A setext-style heading is a line of text “underlined” with a row of = + signs (for a level-one heading) or - signs (for a level-two heading): + + + A level-one heading + =================== + + A level-two heading + ------------------- + + + The heading text can contain inline formatting, such as emphasis (see + Inline formatting, below). + + AATTXX--ssttyyllee hheeaaddiinnggss + An ATX-style heading consists of one to six # signs and a line of text, + optionally followed by any number of # signs. The number of # signs at + the beginning of the line is the heading level: + + + ## A level-two heading + + ### A level-three heading ### + + + As with setext-style headings, the heading text can contain formatting: + + + # A level-one heading with a [link](/url) and *emphasis* + + + EExxtteennssiioonn:: bbllaannkk__bbeeffoorree__hheeaaddeerr + Standard Markdown syntax does not require a blank line before a + heading. Pandoc does require this (except, of course, at the beginning + of the document). The reason for the requirement is that it is all too + easy for a # to end up at the beginning of a line by accident (perhaps + through line wrapping). Consider, for example: + + + I like several of their flavors of ice cream: + #22, for example, and #5. + + + EExxtteennssiioonn:: ssppaaccee__iinn__aattxx__hheeaaddeerr + Many Markdown implementations do not require a space between the + opening #s of an ATX heading and the heading text, so that #5 bolt and + #hashtag count as headings. With this extension, pandoc does require + the space. + + HHeeaaddiinngg iiddeennttiiffiieerrss + See also the auto_identifiers extension above. + + EExxtteennssiioonn:: hheeaaddeerr__aattttrriibbuutteess + Headings can be assigned attributes using this syntax at the end of the + line containing the heading text: + + + {#identifier .class .class key=value key=value} + + + Thus, for example, the following headings will all be assigned the + identifier foo: + + + # My heading {#foo} + + ## My heading ## {#foo} + + My other heading {#foo} + --------------- + + + (This syntax is compatible with PHP Markdown Extra.) + + Note that although this syntax allows assignment of classes and + key/value attributes, writers generally don’t use all of this + information. Identifiers, classes, and key/value attributes are used + in HTML and HTML-based formats such as EPUB and slidy. Identifiers are + used for labels and link anchors in the LaTeX, ConTeXt, Textile, Jira + markup, and AsciiDoc writers. + + Headings with the class unnumbered will not be numbered, even if + --number-sections is specified. A single hyphen (-) in an attribute + context is equivalent to .unnumbered, and preferable in non-English + documents. So, + + + # My heading {-} + + + is just the same as + + + # My heading {.unnumbered} + + + If the unlisted class is present in addition to unnumbered, the heading + will not be included in a table of contents. (Currently this feature + is only implemented for certain formats: those based on LaTeX and HTML, + PowerPoint, and RTF.) + + EExxtteennssiioonn:: iimmpplliicciitt__hheeaaddeerr__rreeffeerreenncceess + Pandoc behaves as if reference links have been defined for each + heading. So, to link to a heading + + + # Heading identifiers in HTML + + + you can simply write + + + [Heading identifiers in HTML] + + + or + + + [Heading identifiers in HTML][] + + + or + + + [the section on heading identifiers][heading identifiers in + HTML] + + + instead of giving the identifier explicitly: + + + [Heading identifiers in HTML](#heading-identifiers-in-html) + + + If there are multiple headings with identical text, the corresponding + reference will link to the first one only, and you will need to use + explicit links to link to the others, as described above. + + Like regular reference links, these references are case-insensitive. + + Explicit link reference definitions always take priority over implicit + heading references. So, in the following example, the link will point + to bar, not to #foo: + + + # Foo + + [foo]: bar + + See [foo] + + + BBlloocckk qquuoottaattiioonnss + Markdown uses email conventions for quoting blocks of text. A block + quotation is one or more paragraphs or other block elements (such as + lists or headings), with each line preceded by a > character and an + optional space. (The > need not start at the left margin, but it + should not be indented more than three spaces.) + + + > This is a block quote. This + > paragraph has two lines. + > + > 1. This is a list inside a block quote. + > 2. Second item. + + + A “lazy” form, which requires the > character only on the first line of + each block, is also allowed: + + + > This is a block quote. This + paragraph has two lines. + + > 1. This is a list inside a block quote. + 2. Second item. + + + Among the block elements that can be contained in a block quote are + other block quotes. That is, block quotes can be nested: + + + > This is a block quote. + > + > > A block quote within a block quote. + + + If the > character is followed by an optional space, that space will be + considered part of the block quote marker and not part of the + indentation of the contents. Thus, to put an indented code block in a + block quote, you need five spaces after the >: + + + > code + + + EExxtteennssiioonn:: bbllaannkk__bbeeffoorree__bblloocckkqquuoottee + Standard Markdown syntax does not require a blank line before a block + quote. Pandoc does require this (except, of course, at the beginning + of the document). The reason for the requirement is that it is all too + easy for a > to end up at the beginning of a line by accident (perhaps + through line wrapping). So, unless the markdown_strict format is used, + the following does not produce a nested block quote in pandoc: + + + > This is a block quote. + >> Nested. + + + VVeerrbbaattiimm ((ccooddee)) bblloocckkss + IInnddeenntteedd ccooddee bblloocckkss + A block of text indented four spaces (or one tab) is treated as + verbatim text: that is, special characters do not trigger special + formatting, and all spaces and line breaks are preserved. For example, + + + if (a > 3) { + moveShip(5 * gravity, DOWN); + } + + + The initial (four space or one tab) indentation is not considered part + of the verbatim text, and is removed in the output. + + Note: blank lines in the verbatim text need not begin with four spaces. + + FFeenncceedd ccooddee bblloocckkss + EExxtteennssiioonn:: ffeenncceedd__ccooddee__bblloocckkss + In addition to standard indented code blocks, pandoc supports _f_e_n_c_e_d + code blocks. These begin with a row of three or more tildes (~) and + end with a row of tildes that must be at least as long as the starting + row. Everything between these lines is treated as code. No + indentation is necessary: + + + ~~~~~~~ + if (a > 3) { + moveShip(5 * gravity, DOWN); + } + ~~~~~~~ + + + Like regular code blocks, fenced code blocks must be separated from + surrounding text by blank lines. + + If the code itself contains a row of tildes or backticks, just use a + longer row of tildes or backticks at the start and end: + + + ~~~~~~~~~~~~~~~~ + ~~~~~~~~~~ + code including tildes + ~~~~~~~~~~ + ~~~~~~~~~~~~~~~~ + + + EExxtteennssiioonn:: bbaacckkttiicckk__ccooddee__bblloocckkss + Same as fenced_code_blocks, but uses backticks (`) instead of tildes + (~). + + EExxtteennssiioonn:: ffeenncceedd__ccooddee__aattttrriibbuutteess + Optionally, you may attach attributes to fenced or backtick code block + using this syntax: + + + ~~~~ {#mycode .haskell .numberLines startFrom="100"} + qsort [] = [] + qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ + qsort (filter (>= x) xs) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + Here mycode is an identifier, haskell and numberLines are classes, and + startFrom is an attribute with value 100. Some output formats can use + this information to do syntax highlighting. Currently, the only output + formats that uses this information are HTML, LaTeX, Docx, Ms, and + PowerPoint. If highlighting is supported for your output format and + language, then the code block above will appear highlighted, with + numbered lines. (To see which languages are supported, type pandoc + --list-highlight-languages.) Otherwise, the code block above will + appear as follows: + + + 
+                
+                ...
+                
+
+ + + The numberLines (or number-lines) class will cause the lines of the + code block to be numbered, starting with 1 or the value of the + startFrom attribute. The lineAnchors (or line-anchors) class will + cause the lines to be clickable anchors in HTML output. + + A shortcut form can also be used for specifying the language of the + code block: + + + ```haskell + qsort [] = [] + ``` + + + This is equivalent to: + + + ``` {.haskell} + qsort [] = [] + ``` + + + If the fenced_code_attributes extension is disabled, but input contains + class attribute(s) for the code block, the first class attribute will + be printed after the opening fence as a bare word. + + To prevent all highlighting, use the --no-highlight flag. To set the + highlighting style, use --highlight-style. For more information on + highlighting, see Syntax highlighting, below. + + LLiinnee bblloocckkss + EExxtteennssiioonn:: lliinnee__bblloocckkss + A line block is a sequence of lines beginning with a vertical bar (|) + followed by a space. The division into lines will be preserved in the + output, as will any leading spaces; otherwise, the lines will be + formatted as Markdown. This is useful for verse and addresses: + + + | The limerick packs laughs anatomical + | In space that is quite economical. + | But the good ones I've seen + | So seldom are clean + | And the clean ones so seldom are comical + + | 200 Main St. + | Berkeley, CA 94718 + + + The lines can be hard-wrapped if needed, but the continuation line must + begin with a space. + + + | The Right Honorable Most Venerable and Righteous Samuel L. + Constable, Jr. + | 200 Main St. + | Berkeley, CA 94718 + + + Inline formatting (such as emphasis) is allowed in the content, but not + block-level formatting (such as block quotes or lists). + + This syntax is borrowed from reStructuredText. + + LLiissttss + BBuulllleett lliissttss + A bullet list is a list of bulleted list items. A bulleted list item + begins with a bullet (*, +, or -). Here is a simple example: + + + * one + * two + * three + + + This will produce a “compact” list. If you want a “loose” list, in + which each item is formatted as a paragraph, put spaces between the + items: + + + * one + + * two + + * three + + + The bullets need not be flush with the left margin; they may be + indented one, two, or three spaces. The bullet must be followed by + whitespace. + + List items look best if subsequent lines are flush with the first line + (after the bullet): + + + * here is my first + list item. + * and my second. + + + But Markdown also allows a “lazy” format: + + + * here is my first + list item. + * and my second. + + + BBlloocckk ccoonntteenntt iinn lliisstt iitteemmss + A list item may contain multiple paragraphs and other block-level + content. However, subsequent paragraphs must be preceded by a blank + line and indented to line up with the first non-space content after the + list marker. + + + * First paragraph. + + Continued. + + * Second paragraph. With a code block, which must be indented + eight spaces: + + { code } + + + Exception: if the list marker is followed by an indented code block, + which must begin 5 spaces after the list marker, then subsequent + paragraphs must begin two columns after the last character of the list + marker: + + + * code + + continuation paragraph + + + List items may include other lists. In this case the preceding blank + line is optional. The nested list must be indented to line up with the + first non-space character after the list marker of the containing list + item. + + + * fruits + + apples + - macintosh + - red delicious + + pears + + peaches + * vegetables + + broccoli + + chard + + + As noted above, Markdown allows you to write list items “lazily,” + instead of indenting continuation lines. However, if there are + multiple paragraphs or other blocks in a list item, the first line of + each must be indented. + + + + A lazy, lazy, list + item. + + + Another one; this looks + bad but is legal. + + Second paragraph of second + list item. + + + OOrrddeerreedd lliissttss + Ordered lists work just like bulleted lists, except that the items + begin with enumerators rather than bullets. + + In standard Markdown, enumerators are decimal numbers followed by a + period and a space. The numbers themselves are ignored, so there is no + difference between this list: + + + 1. one + 2. two + 3. three + + + and this one: + + + 5. one + 7. two + 1. three + + + EExxtteennssiioonn:: ffaannccyy__lliissttss + Unlike standard Markdown, pandoc allows ordered list items to be marked + with uppercase and lowercase letters and roman numerals, in addition to + Arabic numerals. List markers may be enclosed in parentheses or + followed by a single right-parentheses or period. They must be + separated from the text that follows by at least one space, and, if the + list marker is a capital letter with a period, by at least two spaces. + + The fancy_lists extension also allows `#' to be used as an ordered list + marker in place of a numeral: + + + #. one + #. two + + + EExxtteennssiioonn:: ssttaarrttnnuumm + Pandoc also pays attention to the type of list marker used, and to the + starting number, and both of these are preserved where possible in the + output format. Thus, the following yields a list with numbers followed + by a single parenthesis, starting with 9, and a sublist with lowercase + roman numerals: + + + 9) Ninth + 10) Tenth + 11) Eleventh + i. subone + ii. subtwo + iii. subthree + + + Pandoc will start a new list each time a different type of list marker + is used. So, the following will create three lists: + + + (2) Two + (5) Three + 1. Four + * Five + + + If default list markers are desired, use #.: + + + #. one + #. two + #. three + + + EExxtteennssiioonn:: ttaasskk__lliissttss + Pandoc supports task lists, using the syntax of GitHub-Flavored + Markdown. + + + - [ ] an unchecked task list item + - [x] checked item + + + DDeeffiinniittiioonn lliissttss + EExxtteennssiioonn:: ddeeffiinniittiioonn__lliissttss + Pandoc supports definition lists, using the syntax of PHP Markdown + Extra with some extensions. + + + Term 1 + + : Definition 1 + + Term 2 with *inline markup* + + : Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. + + + Each term must fit on one line, which may optionally be followed by a + blank line, and must be followed by one or more definitions. A + definition begins with a colon or tilde, which may be indented one or + two spaces. + + A term may have multiple definitions, and each definition may consist + of one or more block elements (paragraph, code block, list, etc.), each + indented four spaces or one tab stop. The body of the definition + (including the first line, aside from the colon or tilde) should be + indented four spaces. However, as with other Markdown lists, you can + “lazily” omit indentation except at the beginning of a paragraph or + other block element: + + + Term 1 + + : Definition + with lazy continuation. + + Second paragraph of the definition. + + + If you leave space before the definition (as in the example above), the + text of the definition will be treated as a paragraph. In some output + formats, this will mean greater spacing between term/definition pairs. + For a more compact definition list, omit the space before the + definition: + + + Term 1 + ~ Definition 1 + + Term 2 + ~ Definition 2a + ~ Definition 2b + + + Note that space between items in a definition list is required. (A + variant that loosens this requirement, but disallows “lazy” hard + wrapping, can be activated with compact_definition_lists: see Non- + default extensions, below.) + + NNuummbbeerreedd eexxaammppllee lliissttss + EExxtteennssiioonn:: eexxaammppllee__lliissttss + The special list marker @ can be used for sequentially numbered + examples. The first list item with a @ marker will be numbered `1', + the next `2', and so on, throughout the document. The numbered + examples need not occur in a single list; each new list using @ will + take up where the last stopped. So, for example: + + + (@) My first example will be numbered (1). + (@) My second example will be numbered (2). + + Explanation of examples. + + (@) My third example will be numbered (3). + + + Numbered examples can be labeled and referred to elsewhere in the + document: + + + (@good) This is a good example. + + As (@good) illustrates, ... + + + The label can be any string of alphanumeric characters, underscores, or + hyphens. + + Note: continuation paragraphs in example lists must always be indented + four spaces, regardless of the length of the list marker. That is, + example lists always behave as if the four_space_rule extension is set. + This is because example labels tend to be long, and indenting content + to the first non-space character after the label would be awkward. + + EEnnddiinngg aa lliisstt + What if you want to put an indented code block after a list? + + + - item one + - item two + + { my code block } + + + Trouble! Here pandoc (like other Markdown implementations) will treat { + my code block } as the second paragraph of item two, and not as a code + block. + + To “cut off” the list after item two, you can insert some non-indented + content, like an HTML comment, which won’t produce visible output in + any format: + + + - item one + - item two + + + + { my code block } + + + You can use the same trick if you want two consecutive lists instead of + one big list: + + + 1. one + 2. two + 3. three + + + + 1. uno + 2. dos + 3. tres + + + HHoorriizzoonnttaall rruulleess + A line containing a row of three or more *, -, or _ characters + (optionally separated by spaces) produces a horizontal rule: + + + * * * * + + --------------- + + + TTaabblleess + Four kinds of tables may be used. The first three kinds presuppose the + use of a fixed-width font, such as Courier. The fourth kind can be + used with proportionally spaced fonts, as it does not require lining up + columns. + + EExxtteennssiioonn:: ttaabbllee__ccaappttiioonnss + A caption may optionally be provided with all 4 kinds of tables (as + illustrated in the examples below). A caption is a paragraph beginning + with the string Table: (or just :), which will be stripped off. It may + appear either before or after the table. + + EExxtteennssiioonn:: ssiimmppllee__ttaabblleess + Simple tables look like this: + + + Right Left Center Default + ------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 + + Table: Demonstration of simple table syntax. + + + The header and table rows must each fit on one line. Column alignments + are determined by the position of the header text relative to the + dashed line below it: + + • If the dashed line is flush with the header text on the right side + but extends beyond it on the left, the column is right-aligned. + + • If the dashed line is flush with the header text on the left side but + extends beyond it on the right, the column is left-aligned. + + • If the dashed line extends beyond the header text on both sides, the + column is centered. + + • If the dashed line is flush with the header text on both sides, the + default alignment is used (in most cases, this will be left). + + The table must end with a blank line, or a line of dashes followed by a + blank line. + + The column header row may be omitted, provided a dashed line is used to + end the table. For example: + + + ------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 + ------- ------ ---------- ------- + + + When the header row is omitted, column alignments are determined on the + basis of the first line of the table body. So, in the tables above, + the columns would be right, left, center, and right aligned, + respectively. + + EExxtteennssiioonn:: mmuullttiilliinnee__ttaabblleess + Multiline tables allow header and table rows to span multiple lines of + text (but cells that span multiple columns or rows of the table are not + supported). Here is an example: + + + ------------------------------------------------------------- + Centered Default Right Left + Header Aligned Aligned Aligned + ----------- ------- --------------- ------------------------- + First row 12.0 Example of a row that + spans multiple lines. + + Second row 5.0 Here's another one. Note + the blank line between + rows. + ------------------------------------------------------------- + + Table: Here's the caption. It, too, may span + multiple lines. + + + These work like simple tables, but with the following differences: + + • They must begin with a row of dashes, before the header text (unless + the header row is omitted). + + • They must end with a row of dashes, then a blank line. + + • The rows must be separated by blank lines. + + In multiline tables, the table parser pays attention to the widths of + the columns, and the writers try to reproduce these relative widths in + the output. So, if you find that one of the columns is too narrow in + the output, try widening it in the Markdown source. + + The header may be omitted in multiline tables as well as simple tables: + + + ----------- ------- --------------- ------------------------- + First row 12.0 Example of a row that + spans multiple lines. + + Second row 5.0 Here's another one. Note + the blank line between + rows. + ----------- ------- --------------- ------------------------- + + : Here's a multiline table without a header. + + + It is possible for a multiline table to have just one row, but the row + should be followed by a blank line (and then the row of dashes that + ends the table), or the table may be interpreted as a simple table. + + EExxtteennssiioonn:: ggrriidd__ttaabblleess + Grid tables look like this: + + + : Sample grid table. + + +---------------+---------------+--------------------+ + | Fruit | Price | Advantages | + +===============+===============+====================+ + | Bananas | $1.34 | - built-in wrapper | + | | | - bright color | + +---------------+---------------+--------------------+ + | Oranges | $2.10 | - cures scurvy | + | | | - tasty | + +---------------+---------------+--------------------+ + + + The row of =s separates the header from the table body, and can be + omitted for a headerless table. The cells of grid tables may contain + arbitrary block elements (multiple paragraphs, code blocks, lists, + etc.). Cells that span multiple columns or rows are not supported. + Grid tables can be created easily using Emacs’ table-mode (M-x + table-insert). + + Alignments can be specified as with pipe tables, by putting colons at + the boundaries of the separator line after the header: + + + +---------------+---------------+--------------------+ + | Right | Left | Centered | + +==============:+:==============+:==================:+ + | Bananas | $1.34 | built-in wrapper | + +---------------+---------------+--------------------+ + + + For headerless tables, the colons go on the top line instead: + + + +--------------:+:--------------+:------------------:+ + | Right | Left | Centered | + +---------------+---------------+--------------------+ + + + GGrriidd TTaabbllee LLiimmiittaattiioonnss + Pandoc does not support grid tables with row spans or column spans. + This means that neither variable numbers of columns across rows nor + variable numbers of rows across columns are supported by Pandoc. All + grid tables must have the same number of columns in each row, and the + same number of rows in each column. For example, the Docutils sample + grid tables will not render as expected with Pandoc. + + EExxtteennssiioonn:: ppiippee__ttaabblleess + Pipe tables look like this: + + + | Right | Left | Default | Center | + |------:|:-----|---------|:------:| + | 12 | 12 | 12 | 12 | + | 123 | 123 | 123 | 123 | + | 1 | 1 | 1 | 1 | + + : Demonstration of pipe table syntax. + + + The syntax is identical to PHP Markdown Extra tables. The beginning + and ending pipe characters are optional, but pipes are required between + all columns. The colons indicate column alignment as shown. The + header cannot be omitted. To simulate a headerless table, include a + header with blank cells. + + Since the pipes indicate column boundaries, columns need not be + vertically aligned, as they are in the above example. So, this is a + perfectly legal (though ugly) pipe table: + + + fruit| price + -----|-----: + apple|2.05 + pear|1.37 + orange|3.09 + + + The cells of pipe tables cannot contain block elements like paragraphs + and lists, and cannot span multiple lines. If a pipe table contains a + row whose Markdown content is wider than the column width (see + --columns), then the table will take up the full text width and the + cell contents will wrap, with the relative cell widths determined by + the number of dashes in the line separating the table header from the + table body. (For example ---|- would make the first column 3/4 and the + second column 1/4 of the full text width.) On the other hand, if no + lines are wider than column width, then cell contents will not be + wrapped, and the cells will be sized to their contents. + + Note: pandoc also recognizes pipe tables of the following form, as can + be produced by Emacs’ orgtbl-mode: + + + | One | Two | + |-----+-------| + | my | table | + | is | nice | + + + The difference is that + is used instead of |. Other orgtbl features + are not supported. In particular, to get non-default column alignment, + you’ll need to add colons as above. + + MMeettaaddaattaa bblloocckkss + EExxtteennssiioonn:: ppaannddoocc__ttiittllee__bblloocckk + If the file begins with a title block + + + % title + % author(s) (separated by semicolons) + % date + + + it will be parsed as bibliographic information, not regular text. (It + will be used, for example, in the title of standalone LaTeX or HTML + output.) The block may contain just a title, a title and an author, or + all three elements. If you want to include an author but no title, or + a title and a date but no author, you need a blank line: + + + % + % Author + + + + % My title + % + % June 15, 2006 + + + The title may occupy multiple lines, but continuation lines must begin + with leading space, thus: + + + % My title + on multiple lines + + + If a document has multiple authors, the authors may be put on separate + lines with leading space, or separated by semicolons, or both. So, all + of the following are equivalent: + + + % Author One + Author Two + + + + % Author One; Author Two + + + + % Author One; + Author Two + + + The date must fit on one line. + + All three metadata fields may contain standard inline formatting + (italics, links, footnotes, etc.). + + Title blocks will always be parsed, but they will affect the output + only when the --standalone (-s) option is chosen. In HTML output, + titles will appear twice: once in the document head – this is the title + that will appear at the top of the window in a browser – and once at + the beginning of the document body. The title in the document head can + have an optional prefix attached (--title-prefix or -T option). The + title in the body appears as an H1 element with class “title”, so it + can be suppressed or reformatted with CSS. If a title prefix is + specified with -T and no title block appears in the document, the title + prefix will be used by itself as the HTML title. + + The man page writer extracts a title, man page section number, and + other header and footer information from the title line. The title is + assumed to be the first word on the title line, which may optionally + end with a (single-digit) section number in parentheses. (There should + be no space between the title and the parentheses.) Anything after + this is assumed to be additional footer and header text. A single pipe + character (|) should be used to separate the footer text from the + header text. Thus, + + + % PANDOC(1) + + + will yield a man page with the title PANDOC and section 1. + + + % PANDOC(1) Pandoc User Manuals + + + will also have “Pandoc User Manuals” in the footer. + + + % PANDOC(1) Pandoc User Manuals | Version 4.0 + + + will also have “Version 4.0” in the header. + + EExxtteennssiioonn:: yyaammll__mmeettaaddaattaa__bblloocckk + A YAML metadata block is a valid YAML object, delimited by a line of + three hyphens (---) at the top and a line of three hyphens (---) or + three dots (...) at the bottom. A YAML metadata block may occur + anywhere in the document, but if it is not at the beginning, it must be + preceded by a blank line. (Note that, because of the way pandoc + concatenates input files when several are provided, you may also keep + the metadata in a separate YAML file and pass it to pandoc as an + argument, along with your Markdown files: + + + pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html + + + Just be sure that the YAML file begins with --- and ends with --- or + ....) Alternatively, you can use the --metadata-file option. Using + that approach however, you cannot reference content (like footnotes) + from the main markdown input document. + + Metadata will be taken from the fields of the YAML object and added to + any existing document metadata. Metadata can contain lists and objects + (nested arbitrarily), but all string scalars will be interpreted as + Markdown. Fields with names ending in an underscore will be ignored by + pandoc. (They may be given a role by external processors.) Field names + must not be interpretable as YAML numbers or boolean values (so, for + example, yes, True, and 15 cannot be used as field names). + + A document may contain multiple metadata blocks. If two metadata + blocks attempt to set the same field, the value from the second block + will be taken. + + When pandoc is used with -t markdown to create a Markdown document, a + YAML metadata block will be produced only if the -s/--standalone option + is used. All of the metadata will appear in a single block at the + beginning of the document. + + Note that YAML escaping rules must be followed. Thus, for example, if + a title contains a colon, it must be quoted, and if it contains a + backslash escape, then it must be ensured that it is not treated as a + YAML escape sequence. The pipe character (|) can be used to begin an + indented block that will be interpreted literally, without need for + escaping. This form is necessary when the field contains blank lines + or block-level formatting: + + + --- + title: 'This is the title: it contains a colon' + author: + - Author One + - Author Two + keywords: [nothing, nothingness] + abstract: | + This is the abstract. + + It consists of two paragraphs. + ... + + + The literal block after the | must be indented relative to the line + containing the |. If it is not, the YAML will be invalid and pandoc + will not interpret it as metadata. For an overview of the complex + rules governing YAML, see the Wikipedia entry on YAML syntax. + + Template variables will be set automatically from the metadata. Thus, + for example, in writing HTML, the variable abstract will be set to the + HTML equivalent of the Markdown in the abstract field: + + +

This is the abstract.

+

It consists of two paragraphs.

+ + + Variables can contain arbitrary YAML structures, but the template must + match this structure. The author variable in the default templates + expects a simple list or string, but can be changed to support more + complicated structures. The following combination, for example, would + add an affiliation to the author if one is given: + + + --- + title: The document title + author: + - name: Author One + affiliation: University of Somewhere + - name: Author Two + affiliation: University of Nowhere + ... + + + To use the structured authors in the example above, you would need a + custom template: + + + $for(author)$ + $if(author.name)$ + $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$ + $else$ + $author$ + $endif$ + $endfor$ + + + Raw content to include in the document’s header may be specified using + header-includes; however, it is important to mark up this content as + raw code for a particular output format, using the raw_attribute + extension), or it will be interpreted as markdown. For example: + + + header-includes: + - | + ```{=latex} + \let\oldsection\section + \renewcommand{\section}[1]{\clearpage\oldsection{#1}} + ``` + + + Note: the yaml_metadata_block extension works with commonmark as well + as markdown (and it is enabled by default in gfm and commonmark_x). + However, in these formats the following restrictions apply: + + • The YAML metadata block must occur at the beginning of the document + (and there can be only one). If multiple files are given as + arguments to pandoc, only the first can be a YAML metadata block. + + • The leaf nodes of the YAML structure are parsed in isolation from + each other and from the rest of the document. So, for example, you + can’t use a reference link in these contexts if the link definition + is somewhere else in the document. + + BBaacckkssllaasshh eessccaappeess + EExxtteennssiioonn:: aallll__ssyymmbboollss__eessccaappaabbllee + Except inside a code block or inline code, any punctuation or space + character preceded by a backslash will be treated literally, even if it + would normally indicate formatting. Thus, for example, if one writes + + + *\*hello\** + + + one will get + + + *hello* + + + instead of + + + hello + + + This rule is easier to remember than standard Markdown’s rule, which + allows only the following characters to be backslash-escaped: + + + \`*_{}[]()>#+-.! + + + (However, if the markdown_strict format is used, the standard Markdown + rule will be used.) + + A backslash-escaped space is parsed as a nonbreaking space. In TeX + output, it will appear as ~. In HTML and XML output, it will appear as + a literal unicode nonbreaking space character (note that it will thus + actually look “invisible” in the generated HTML source; you can still + use the --ascii command-line option to make it appear as an explicit + entity). + + A backslash-escaped newline (i.e. a backslash occurring at the end of a + line) is parsed as a hard line break. It will appear in TeX output as + \\ and in HTML as
. This is a nice alternative to Markdown’s + “invisible” way of indicating hard line breaks using two trailing + spaces on a line. + + Backslash escapes do not work in verbatim contexts. + + IInnlliinnee ffoorrmmaattttiinngg + EEmmpphhaassiiss + To _e_m_p_h_a_s_i_z_e some text, surround it with *s or _, like this: + + + This text is _emphasized with underscores_, and this + is *emphasized with asterisks*. + + + Double * or _ produces ssttrroonngg eemmpphhaassiiss: + + + This is **strong emphasis** and __with underscores__. + + + A * or _ character surrounded by spaces, or backslash-escaped, will not + trigger emphasis: + + + This is * not emphasized *, and \*neither is this\*. + + + EExxtteennssiioonn:: iinnttrraawwoorrdd__uunnddeerrssccoorreess + Because _ is sometimes used inside words and identifiers, pandoc does + not interpret a _ surrounded by alphanumeric characters as an emphasis + marker. If you want to emphasize just part of a word, use *: + + + feas*ible*, not feas*able*. + + + SSttrriikkeeoouutt + EExxtteennssiioonn:: ssttrriikkeeoouutt + To strikeout a section of text with a horizontal line, begin and end it + with ~~. Thus, for example, + + + This ~~is deleted text.~~ + + + SSuuppeerrssccrriippttss aanndd ssuubbssccrriippttss + EExxtteennssiioonn:: ssuuppeerrssccrriipptt, subscript + Superscripts may be written by surrounding the superscripted text by ^ + characters; subscripts may be written by surrounding the subscripted + text by ~ characters. Thus, for example, + + + H~2~O is a liquid. 2^10^ is 1024. + + + The text between ^...^ or ~...~ may not contain spaces or newlines. If + the superscripted or subscripted text contains spaces, these spaces + must be escaped with backslashes. (This is to prevent accidental + superscripting and subscripting through the ordinary use of ~ and ^, + and also bad interactions with footnotes.) Thus, if you want the letter + P with `a cat' in subscripts, use P~a\ cat~, not P~a cat~. + + VVeerrbbaattiimm + To make a short span of text verbatim, put it inside backticks: + + + What is the difference between `>>=` and `>>`? + + + If the verbatim text includes a backtick, use double backticks: + + + Here is a literal backtick `` ` ``. + + + (The spaces after the opening backticks and before the closing + backticks will be ignored.) + + The general rule is that a verbatim span starts with a string of + consecutive backticks (optionally followed by a space) and ends with a + string of the same number of backticks (optionally preceded by a + space). + + Note that backslash-escapes (and other Markdown constructs) do not work + in verbatim contexts: + + + This is a backslash followed by an asterisk: `\*`. + + + EExxtteennssiioonn:: iinnlliinnee__ccooddee__aattttrriibbuutteess + Attributes can be attached to verbatim text, just as with fenced code + blocks: + + + `<$>`{.haskell} + + + SSmmaallll ccaappss + To write small caps, use the smallcaps class: + + + [Small caps]{.smallcaps} + + + Or, without the bracketed_spans extension: + + + Small caps + + + For compatibility with other Markdown flavors, CSS is also supported: + + + Small caps + + + This will work in all output formats that support small caps. + + MMaatthh + EExxtteennssiioonn:: tteexx__mmaatthh__ddoollllaarrss + Anything between two $ characters will be treated as TeX math. The + opening $ must have a non-space character immediately to its right, + while the closing $ must have a non-space character immediately to its + left, and must not be followed immediately by a digit. Thus, $20,000 + and $30,000 won’t parse as math. If for some reason you need to + enclose text in literal $ characters, backslash-escape them and they + won’t be treated as math delimiters. + + For display math, use $$ delimiters. (In this case, the delimiters may + be separated from the formula by whitespace. However, there can be no + blank lines betwen the opening and closing $$ delimiters.) + + TeX math will be printed in all output formats. How it is rendered + depends on the output format: + + LaTeX It will appear verbatim surrounded by \(...\) (for inline math) + or \[...\] (for display math). + + Markdown, Emacs Org mode, ConTeXt, ZimWiki + It will appear verbatim surrounded by $...$ (for inline math) or + $$...$$ (for display math). + + XWiki It will appear verbatim surrounded by {{formula}}..{{/formula}}. + + reStructuredText + It will be rendered using an interpreted text role :math:. + + AsciiDoc + For AsciiDoc output format (-t asciidoc) it will appear verbatim + surrounded by latexmath:[$...$] (for inline math) or + [latexmath]++++\[...\]+++ (for display math). For AsciiDoctor + output format (-t asciidoctor) the LaTex delimiters ($..$ and + \[..\]) are omitted. + + Texinfo + It will be rendered inside a @math command. + + roff man, Jira markup + It will be rendered verbatim without $’s. + + MediaWiki, DokuWiki + It will be rendered inside tags. + + Textile + It will be rendered inside tags. + + RTF, OpenDocument + It will be rendered, if possible, using Unicode characters, and + will otherwise appear verbatim. + + ODT It will be rendered, if possible, using MathML. + + DocBook + If the --mathml flag is used, it will be rendered using MathML + in an inlineequation or informalequation tag. Otherwise it will + be rendered, if possible, using Unicode characters. + + Docx It will be rendered using OMML math markup. + + FictionBook2 + If the --webtex option is used, formulas are rendered as images + using CodeCogs or other compatible web service, downloaded and + embedded in the e-book. Otherwise, they will appear verbatim. + + HTML, Slidy, DZSlides, S5, EPUB + The way math is rendered in HTML will depend on the command-line + options selected. Therefore see Math rendering in HTML above. + + RRaaww HHTTMMLL + EExxtteennssiioonn:: rraaww__hhttmmll + Markdown allows you to insert raw HTML (or DocBook) anywhere in a + document (except verbatim contexts, where <, >, and & are interpreted + literally). (Technically this is not an extension, since standard + Markdown allows it, but it has been made an extension so that it can be + disabled if desired.) + + The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, + DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile + output, and suppressed in other formats. + + For a more explicit way of including raw HTML in a Markdown document, + see the raw_attribute extension. + + In the CommonMark format, if raw_html is enabled, superscripts, + subscripts, strikeouts and small capitals will be represented as HTML. + Otherwise, plain-text fallbacks will be used. Note that even if + raw_html is disabled, tables will be rendered with HTML syntax if they + cannot use pipe syntax. + + EExxtteennssiioonn:: mmaarrkkddoowwnn__iinn__hhttmmll__bblloocckkss + Standard Markdown allows you to include HTML “blocks”: blocks of HTML + between balanced tags that are separated from the surrounding text with + blank lines, and start and end at the left margin. Within these + blocks, everything is interpreted as HTML, not Markdown; so (for + example), * does not signify emphasis. + + Pandoc behaves this way when the markdown_strict format is used; but by + default, pandoc interprets material between HTML block tags as + Markdown. Thus, for example, pandoc will turn + + + + + + + +
*one*[a link](https://google.com)
+ + + into + + + + + + + +
onea link
+ + + whereas Markdown.pl will preserve it as is. + + There is one exception to this rule: text between + HTML + """) + ``` + + ## Image + + This image ![image](myimage.png) will be + included as a cell attachment. + + + If you want to add cell attributes, group cells differently, or add + output to code cells, then you need to include divs to indicate the + structure. You can use either fenced divs or native divs for this. + Here is an example: + + + :::::: {.cell .markdown} + # Lorem + + **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus + bibendum felis dictum sodales. + :::::: + + :::::: {.cell .code execution_count=1} + ``` {.python} + print("hello") + ``` + + ::: {.output .stream .stdout} + ``` + hello + ``` + ::: + :::::: + + :::::: {.cell .code execution_count=2} + ``` {.python} + from IPython.display import HTML + HTML(""" + + HTML + """) + ``` + + ::: {.output .execute_result execution_count=2} + ```{=html} + + HTML + hello + ``` + ::: + :::::: + + + If you include raw HTML or TeX in an output cell, use the [raw + attribute][Extension: fenced_attribute], as shown in the last cell of + the example above. Although pandoc can process “bare” raw HTML and + TeX, the result is often interspersed raw elements and normal textual + elements, and in an output cell pandoc expects a single, connected raw + block. To avoid using raw HTML or TeX except when marked explicitly + using raw attributes, we recommend specifying the extensions + -raw_html-raw_tex+raw_attribute when translating between Markdown and + ipynb notebooks. + + Note that options and extensions that affect reading and writing of + Markdown will also affect Markdown cells in ipynb notebooks. For + example, --wrap=preserve will preserve soft line breaks in Markdown + cells; --atx-headers will cause ATX-style headings to be used; and + --preserve-tabs will prevent tabs from being turned to spaces. + +SSYYNNTTAAXX HHIIGGHHLLIIGGHHTTIINNGG + Pandoc will automatically highlight syntax in fenced code blocks that + are marked with a language name. The Haskell library skylighting is + used for highlighting. Currently highlighting is supported only for + HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language + names that pandoc will recognize, type pandoc + --list-highlight-languages. + + The color scheme can be selected using the --highlight-style option. + The default color scheme is pygments, which imitates the default color + scheme used by the Python library pygments (though pygments is not + actually used to do the highlighting). To see a list of highlight + styles, type pandoc --list-highlight-styles. + + If you are not satisfied with the predefined styles, you can use + --print-highlight-style to generate a JSON .theme file which can be + modified and used as the argument to --highlight-style. To get a JSON + version of the pygments style, for example: + + + pandoc --print-highlight-style pygments > my.theme + + + Then edit my.theme and use it like this: + + + pandoc --highlight-style my.theme + + + If you are not satisfied with the built-in highlighting, or you want + highlight a language that isn’t supported, you can use the + --syntax-definition option to load a KDE-style XML syntax definition + file. Before writing your own, have a look at KDE’s repository of + syntax definitions. + + To disable highlighting, use the --no-highlight option. + +CCUUSSTTOOMM SSTTYYLLEESS + Custom styles can be used in the docx and ICML formats. + + OOuuttppuutt + By default, pandoc’s docx and ICML output applies a predefined set of + styles for blocks such as paragraphs and block quotes, and uses largely + default formatting (italics, bold) for inlines. This will work for + most purposes, especially alongside a reference.docx file. However, if + you need to apply your own styles to blocks, or match a preexisting set + of styles, pandoc allows you to define custom styles for blocks and + text using divs and spans, respectively. + + If you define a div or span with the attribute custom-style, pandoc + will apply your specified style to the contained elements (with the + exception of elements whose function depends on a style, like headings, + code blocks, block quotes, or links). So, for example, using the + bracketed_spans syntax, + + + [Get out]{custom-style="Emphatically"}, he said. + + + would produce a docx file with “Get out” styled with character style + Emphatically. Similarly, using the fenced_divs syntax, + + + Dickinson starts the poem simply: + + ::: {custom-style="Poetry"} + | A Bird came down the Walk--- + | He did not know I saw--- + ::: + + + would style the two contained lines with the Poetry paragraph style. + + For docx output, styles will be defined in the output file as + inheriting from normal text, if the styles are not yet in your + reference.docx. If they are already defined, pandoc will not alter the + definition. + + This feature allows for greatest customization in conjunction with + pandoc filters. If you want all paragraphs after block quotes to be + indented, you can write a filter to apply the styles necessary. If you + want all italics to be transformed to the Emphasis character style + (perhaps to change their color), you can write a filter which will + transform all italicized inlines to inlines within an Emphasis + custom-style span. + + For docx output, you don’t need to enable any extensions for custom + styles to work. + + IInnppuutt + The docx reader, by default, only reads those styles that it can + convert into pandoc elements, either by direct conversion or + interpreting the derivation of the input document’s styles. + + By enabling the styles extension in the docx reader (-f docx+styles), + you can produce output that maintains the styles of the input document, + using the custom-style class. Paragraph styles are interpreted as + divs, while character styles are interpreted as spans. + + For example, using the custom-style-reference.docx file in the test + directory, we have the following different outputs: + + Without the +styles extension: + + + $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown + This is some text. + + This is text with an *emphasized* text style. And this is text with a + **strengthened** text style. + + > Here is a styled paragraph that inherits from Block Text. + + + And with the extension: + + + $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown + + ::: {custom-style="First Paragraph"} + This is some text. + ::: + + ::: {custom-style="Body Text"} + This is text with an [emphasized]{custom-style="Emphatic"} text style. + And this is text with a [strengthened]{custom-style="Strengthened"} + text style. + ::: + + ::: {custom-style="My Block Style"} + > Here is a styled paragraph that inherits from Block Text. + ::: + + + With these custom styles, you can use your input document as a + reference-doc while creating docx output (see below), and maintain the + same styles in your input and output files. + +CCUUSSTTOOMM WWRRIITTEERRSS + Pandoc can be extended with custom writers written in Lua. (Pandoc + includes a Lua interpreter, so Lua need not be installed separately.) + + To use a custom writer, simply specify the path to the Lua script in + place of the output format. For example: + + + pandoc -t data/sample.lua + + + Creating a custom writer requires writing a Lua function for each + possible element in a pandoc document. To get a documented example + which you can modify according to your needs, do + + + pandoc --print-default-data-file sample.lua + + + Note that custom writers have no default template. If you want to use + --standalone with a custom writer, you will need to specify a template + manually using --template or add a new default template with the name + default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your + user data directory (see Templates). + +RREEPPRROODDUUCCIIBBLLEE BBUUIILLDDSS + Some of the document formats pandoc targets (such as EPUB, docx, and + ODT) include build timestamps in the generated document. That means + that the files generated on successive builds will differ, even if the + source does not. To avoid this, set the SOURCE_DATE_EPOCH environment + variable, and the timestamp will be taken from it instead of the + current time. SOURCE_DATE_EPOCH should contain an integer unix + timestamp (specifying the number of second since midnight UTC January + 1, 1970). + + Some document formats also include a unique identifier. For EPUB, this + can be set explicitly by setting the identifier metadata field (see + EPUB Metadata, above). + +AA NNOOTTEE OONN SSEECCUURRIITTYY + If you use pandoc to convert user-contributed content in a web + application, here are some things to keep in mind: + + 1. Although pandoc itself will not create or modify any files other + than those you explicitly ask it create (with the exception of + temporary files used in producing PDFs), a filter or custom writer + could in principle do anything on your file system. Please audit + filters and custom writers very carefully before using them. + + 2. If your application uses pandoc as a Haskell library (rather than + shelling out to the executable), it is possible to use it in a mode + that fully isolates pandoc from your file system, by running the + pandoc operations in the PandocPure monad. See the document Using + the pandoc API for more details. + + 3. Pandoc’s parsers can exhibit pathological performance on some corner + cases. It is wise to put any pandoc operations under a timeout, to + avoid DOS attacks that exploit these issues. If you are using the + pandoc executable, you can add the command line options +RTS -M512M + -RTS (for example) to limit the heap size to 512MB. + + 4. The HTML generated by pandoc is not guaranteed to be safe. If + raw_html is enabled for the Markdown input, users can inject + arbitrary HTML. Even if raw_html is disabled, users can include + dangerous content in URLs and attributes. To be safe, you should + run all the generated HTML through an HTML sanitizer. + +AAUUTTHHOORRSS + Copyright 2006–2021 John MacFarlane (jgm@berkeley.edu). Released under + the GPL, version 2 or greater. This software carries no warranty of + any kind. (See COPYRIGHT for full copyright and warranty notices.) For + a full list of contributors, see the file AUTHORS.md in the pandoc + source code. + + The Pandoc source code and all documentation may be downloaded from + . + + + +pandoc 2.14.0.3 June 20, 2021 Pandoc User’s Guide()