From a396003a31afd2c3baa9657669cbbb77460e5cf2 Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Wed, 20 Jul 2016 14:12:57 +0200 Subject: Rename README to MANUAL.txt --- .gitignore | 4 +- CONTRIBUTING.md | 8 +- INSTALL | 2 +- MANUAL.txt | 4007 ++++++++++++++++++++++++++++++++++++ Makefile | 2 +- README | 4007 ------------------------------------ appveyor.yml | 2 +- pandoc.cabal | 4 +- src/Text/Pandoc/Data.hsb | 2 +- src/Text/Pandoc/Shared.hs | 4 +- windows/make-windows-installer.bat | 4 +- windows/pandoc.wxs | 20 +- 12 files changed, 4033 insertions(+), 4033 deletions(-) create mode 100644 MANUAL.txt delete mode 100644 README diff --git a/.gitignore b/.gitignore index 9b7630a4c..0e2686c83 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ *~ dist/* -README.* -!README.Debian +MANUAL.* +!MANUAL.txt INSTALL.* .configure-stamp .cabal-sandbox diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f39acab10..31d786214 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ Out of scope? ------------- A less than perfect conversion does not necessarily mean there's -a bug in pandoc. Quoting from the README: +a bug in pandoc. Quoting from the MANUAL: > Because Pandoc's intermediate representation of a document is less > expressive than many of the formats it converts between, one should @@ -124,7 +124,7 @@ Please follow these guidelines: below under [Tests](#tests).) If you are adding a new writer or reader, you must include tests. -7. If you are adding a new feature, include updates to the README. +7. If you are adding a new feature, include updates to the README and MANUAL. 8. All code must be released under the general license governing pandoc (GPL v2). @@ -259,7 +259,7 @@ The library is structured as follows: - `Text.Pandoc.Shared` is a grab-bag of shared utility functions. - `Text.Pandoc.Writers.Shared` contains utilities used in writers only. - `Text.Pandoc.Slides` contains functions for splitting a markdown document - into slides, using the conventions described in the README. + into slides, using the conventions described in the MANUAL. - `Text.Pandoc.Templates` defines pandoc's templating system. - `Text.Pandoc.UTF8` contains functions for converting text to and from UTF8 bytestrings (strict and lazy). @@ -270,7 +270,7 @@ The library is structured as follows: [pandoc-discuss]: http://groups.google.com/group/pandoc-discuss [issue tracker]: https://github.com/jgm/pandoc/issues -[User's Guide]: http://pandoc.org/README.html +[User's Guide]: http://pandoc.org/MANUAL.html [FAQs]: http://pandoc.org/faqs.html [EditorConfig]: http://editorconfig.org/ [Haskell platform]: http://www.haskell.org/platform/ diff --git a/INSTALL b/INSTALL index bfb548913..87be44eca 100644 --- a/INSTALL +++ b/INSTALL @@ -95,7 +95,7 @@ Quick install with cabal The `pandoc.1` man page will be installed automatically. cabal shows you where it is installed: you may need to set your `MANPATH` -accordingly. If `README` has been modified, the man page can be +accordingly. If `MANUAL.txt` has been modified, the man page can be rebuilt: `make man/pandoc.1`. The `pandoc-citeproc.1` man page will also be installed automatically. diff --git a/MANUAL.txt b/MANUAL.txt new file mode 100644 index 000000000..8d5be98f8 --- /dev/null +++ b/MANUAL.txt @@ -0,0 +1,4007 @@ +% Pandoc User's Guide +% John MacFarlane +% July 17, 2016 + +Synopsis +======== + +`pandoc` [*options*] [*input-file*]... + +Description +=========== + +Pandoc is a [Haskell] library for converting from one markup format to +another, and a command-line tool that uses this library. It can read +[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown], +[MultiMarkdown], and (subsets of) [Textile], [reStructuredText], [HTML], +[LaTeX], [MediaWiki markup], [TWiki markup], [Haddock markup], [OPML], [Emacs +Org mode], [DocBook], [txt2tags], [EPUB], [ODT] and [Word docx]; and it can +write plain text, [Markdown], [CommonMark], [PHP Markdown Extra], +[GitHub-Flavored Markdown], [MultiMarkdown], [reStructuredText], [XHTML], +[HTML5], [LaTeX] (including [`beamer`] slide shows), [ConTeXt], [RTF], [OPML], +[DocBook], [OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki +markup], [DokuWiki markup], [ZimWiki markup], [Haddock markup], +[EPUB] (v2 or v3), [FictionBook2], [Textile], [groff man] pages, +[Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI Simple], and [Slidy], +[Slideous], [DZSlides], [reveal.js] or [S5] HTML slide shows. It can also +produce [PDF] output on systems where LaTeX, ConTeXt, or `wkhtmltopdf` is +installed. + +Pandoc's enhanced version of Markdown includes syntax for [footnotes], +[tables], flexible [ordered lists], [definition lists], [fenced code blocks], +[superscripts and subscripts], [strikeout], [metadata blocks], automatic tables of +contents, embedded LaTeX [math], [citations], and [Markdown inside HTML block +elements][Extension: `markdown_in_html_blocks`]. (These enhancements, described below under +[Pandoc's Markdown], can be disabled using the +`markdown_strict` input or output format.) + +In contrast to most existing tools for converting Markdown to HTML, which +use regex substitutions, 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, 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. + +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. + +[Markdown]: http://daringfireball.net/projects/markdown/ +[CommonMark]: http://commonmark.org +[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/ +[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/ +[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/ +[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +[S5]: http://meyerweb.com/eric/tools/s5/ +[Slidy]: http://www.w3.org/Talks/Tools/Slidy/ +[Slideous]: http://goessner.net/articles/slideous/ +[HTML]: http://www.w3.org/html/ +[HTML5]: http://www.w3.org/TR/html5/ +[XHTML]: http://www.w3.org/TR/xhtml1/ +[LaTeX]: http://latex-project.org +[`beamer`]: https://ctan.org/pkg/beamer +[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf +[ConTeXt]: http://contextgarden.net/ +[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format +[DocBook]: http://docbook.org +[txt2tags]: http://txt2tags.org +[EPUB]: http://idpf.org/epub +[OPML]: http://dev.opml.org/spec2.html +[OpenDocument]: http://opendocument.xml.org +[ODT]: http://en.wikipedia.org/wiki/OpenDocument +[Textile]: http://redcloth.org/textile +[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting +[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki +[ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html +[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules +[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html +[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html +[Haskell]: https://www.haskell.org +[GNU Texinfo]: http://www.gnu.org/software/texinfo/ +[Emacs Org mode]: http://orgmode.org +[AsciiDoc]: http://www.methods.co.nz/asciidoc/ +[DZSlides]: http://paulrouget.com/dzslides/ +[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx +[PDF]: https://www.adobe.com/pdf/ +[reveal.js]: http://lab.hakim.se/reveal-js/ +[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1 +[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf +[TEI Simple]: https://github.com/TEIC/TEI-Simple + +Using `pandoc` +-------------- + +If no *input-file* is specified, input is read from *stdin*. +Otherwise, the *input-files* are concatenated (with a blank +line between each) and used as input. Output goes to *stdout* by +default (though output to *stdout* is disabled for the `odt`, `docx`, +`epub`, and `epub3` output formats). For output to a file, use the +`-o` option: + + pandoc -o output.html input.txt + +By default, pandoc produces a document fragment, not a standalone +document with a proper header and footer. To produce a standalone +document, 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. + +Instead of a file, an absolute URI may be given. In this case +pandoc will fetch the content using HTTP: + + pandoc -f html -t markdown http://www.fsf.org + +If multiple input files are given, `pandoc` will concatenate them all (with +blank lines between them) before parsing. This feature is disabled for + binary input formats such as `EPUB`, `odt`, and `docx`. + +The format of the input and output can be specified explicitly using +command-line options. The input format can be specified using the +`-r/--read` or `-f/--from` options, the output format using the +`-w/--write` or `-t/--to` options. 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 output formats are listed below under the `-t/--to` option. +Supported input formats are listed below under the `-f/--from` option. Note +that the `rst`, `textile`, `latex`, and `html` readers are not complete; +there are some constructs that they do not parse. + +If the input or output format is not specified explicitly, `pandoc` +will attempt to guess it from the extensions of +the input and output 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 *stdout*), 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 *stdin*), or +if the input files' extensions are unknown, the input format will +be assumed to be Markdown unless explicitly specified. + +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. + +[`iconv`]: http://www.gnu.org/software/libiconv/ + +Creating a PDF +-------------- + +To produce a PDF, specify an output file with a `.pdf` extension. +By default, pandoc will use LaTeX to convert it to PDF: + + pandoc test.txt -o test.pdf + +Production of a PDF requires that a LaTeX engine be installed (see +`--latex-engine`, below), and assumes that the following LaTeX packages +are available: [`amsfonts`], [`amsmath`], [`lm`], +[`ifxetex`], [`ifluatex`], [`eurosym`], [`listings`] (if the +`--listings` option is used), [`fancyvrb`], [`longtable`], +[`booktabs`], [`graphicx`] and [`grffile`] (if the +document contains images), [`hyperref`], [`ulem`], +[`geometry`] (with the `geometry` variable set), [`setspace`] (with +`linestretch`), and [`babel`] (with `lang`). The use of `xelatex` or +`lualatex` as the LaTeX engine requires [`fontspec`]; `xelatex` uses +[`mathspec`], [`polyglossia`] (with `lang`), [`xecjk`], and +[`bidi`] (with the `dir` variable set). The [`upquote`] and +[`microtype`] packages are used if available, and [`csquotes`] will +be used for [smart punctuation] if added to the template or included in +any header file. The [`natbib`], [`biblatex`], [`bibtex`], and [`biber`] +packages can optionally be used for [citation rendering]. These are +included with all recent versions of [TeX Live]. + +Alternatively, pandoc can use ConTeXt or `wkhtmltopdf` to create a PDF. +To do this, specify an output file with a `.pdf` extension, +as before, but add `-t context` or `-t html5` to the command line. + +PDF output can be controlled using [variables for LaTeX] (if +LaTeX is used) and [variables for ConTeXt] (if ConTeXt is used). +If `wkhtmltopdf` is used, then the variables `margin-left`, +`margin-right`, `margin-top`, `margin-bottom`, and `papersize` +will affect the output, as will `--css`. + +[`amsfonts`]: https://ctan.org/pkg/amsfonts +[`amsmath`]: https://ctan.org/pkg/amsmath +[`lm`]: https://ctan.org/pkg/lm +[`ifxetex`]: https://ctan.org/pkg/ifxetex +[`ifluatex`]: https://ctan.org/pkg/ifluatex +[`eurosym`]: https://ctan.org/pkg/eurosym +[`listings`]: https://ctan.org/pkg/listings +[`fancyvrb`]: https://ctan.org/pkg/fancyvrb +[`longtable`]: https://ctan.org/pkg/longtable +[`booktabs`]: https://ctan.org/pkg/booktabs +[`graphicx`]: https://ctan.org/pkg/graphicx +[`grffile`]: https://ctan.org/pkg/grffile +[`geometry`]: https://ctan.org/pkg/geometry +[`setspace`]: https://ctan.org/pkg/setspace +[`xecjk`]: https://ctan.org/pkg/xecjk +[`hyperref`]: https://ctan.org/pkg/hyperref +[`ulem`]: https://ctan.org/pkg/ulem +[`babel`]: https://ctan.org/pkg/babel +[`bidi`]: https://ctan.org/pkg/bidi +[`mathspec`]: https://ctan.org/pkg/mathspec +[`polyglossia`]: https://ctan.org/pkg/polyglossia +[`fontspec`]: https://ctan.org/pkg/fontspec +[`upquote`]: https://ctan.org/pkg/upquote +[`microtype`]: https://ctan.org/pkg/microtype +[`csquotes`]: https://ctan.org/pkg/csquotes +[`natbib`]: https://ctan.org/pkg/natbib +[`biblatex`]: https://ctan.org/pkg/biblatex +[`bibtex`]: https://ctan.org/pkg/bibtex +[`biber`]: https://ctan.org/pkg/biber +[TeX Live]: http://www.tug.org/texlive/ + +Options +======= + +General options +--------------- + +`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT* + +: Specify input format. *FORMAT* can be `native` (native Haskell), + `json` (JSON version of native AST), `markdown` (pandoc's + extended Markdown), `markdown_strict` (original unextended + Markdown), `markdown_phpextra` (PHP Markdown Extra), `markdown_github` + (GitHub-Flavored Markdown), `markdown_mmd` (MultiMarkdown), + `commonmark` (CommonMark Markdown), `textile` (Textile), `rst` + (reStructuredText), `html` (HTML), `docbook` (DocBook), `t2t` + (txt2tags), `docx` (docx), `odt` (ODT), `epub` (EPUB), `opml` (OPML), + `org` (Emacs Org mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki + markup), `haddock` (Haddock markup), or `latex` (LaTeX). If + `+lhs` is appended to `markdown`, `rst`, `latex`, or `html`, the + input will be treated as literate Haskell source: see [Literate + Haskell support], below. Markdown + syntax extensions can be individually enabled or disabled by + appending `+EXTENSION` or `-EXTENSION` to the format name. So, for + example, `markdown_strict+footnotes+definition_lists` is strict + Markdown with footnotes and definition lists enabled, and + `markdown-pipe_tables+hard_line_breaks` is pandoc's Markdown + without pipe tables and with hard line breaks. See [Pandoc's + Markdown], below, for a list of extensions and + their names. + +`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT* + +: Specify output format. *FORMAT* can be `native` (native Haskell), + `json` (JSON version of native AST), `plain` (plain text), + `markdown` (pandoc's extended Markdown), `markdown_strict` + (original unextended Markdown), `markdown_phpextra` (PHP Markdown + Extra), `markdown_github` (GitHub-Flavored Markdown), `markdown_mmd` + (MultiMarkdown), `commonmark` (CommonMark Markdown), `rst` + (reStructuredText), `html` (XHTML), `html5` (HTML5), `latex` + (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt), + `man` (groff man), `mediawiki` (MediaWiki markup), + `dokuwiki` (DokuWiki markup), `zimwiki` (ZimWiki markup), + `textile` (Textile), `org` (Emacs Org mode), + `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook 4), + `docbook5` (DocBook 5), `opendocument` (OpenDocument), `odt` + (OpenOffice text document), `docx` (Word docx), `haddock` + (Haddock markup), `rtf` (rich text format), `epub` (EPUB v2 + book), `epub3` (EPUB v3), `fb2` (FictionBook2 e-book), + `asciidoc` (AsciiDoc), `icml` (InDesign ICML), `tei` (TEI + Simple), `slidy` (Slidy HTML and javascript slide show), + `slideous` (Slideous 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), or the path of a custom + lua writer (see [Custom writers], below). Note that `odt`, + `epub`, and `epub3` output will not be directed to *stdout*; + an output filename must be specified using the `-o/--output` + option. If `+lhs` is appended to `markdown`, `rst`, `latex`, + `beamer`, `html`, or `html5`, the output will be rendered as + literate Haskell source: see [Literate Haskell support], + below. Markdown syntax extensions can be individually + enabled or disabled by appending `+EXTENSION` or + `-EXTENSION` to the format name, as described above under `-f`. + +`-o` *FILE*, `--output=`*FILE* + +: Write output to *FILE* instead of *stdout*. If *FILE* is + `-`, output will go to *stdout*. (Exception: if the output + format is `odt`, `docx`, `epub`, or `epub3`, output to stdout is disabled.) + +`--data-dir=`*DIRECTORY* + +: 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. This is, in Unix: + + $HOME/.pandoc + + in Windows XP: + + C:\Documents And Settings\USERNAME\Application Data\pandoc + + and in Windows Vista or later: + + 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`. + A `reference.odt`, `reference.docx`, `epub.css`, `templates`, + `slidy`, `slideous`, or `s5` directory + placed in this directory will override pandoc's normal defaults. + +`--bash-completion` + +: Generate a bash completion script. To enable bash completion + with pandoc, add this to your `.bashrc`: + + eval "$(pandoc --bash-completion)" + +`--verbose` + +: Give verbose debugging output. Currently this only has an effect + with PDF output. + +`-v`, `--version` + +: Print version. + +`-h`, `--help` + +: Show usage message. + +Reader options +-------------- + +`-R`, `--parse-raw` + +: Parse untranslatable HTML codes and LaTeX environments as raw HTML + or LaTeX, instead of ignoring them. Affects only HTML and LaTeX + input. Raw HTML can be printed in Markdown, reStructuredText, Emacs Org + mode, HTML, Slidy, Slideous, DZSlides, reveal.js, and S5 output; raw LaTeX + can be printed in Markdown, reStructuredText, Emacs Org mode, LaTeX, and + ConTeXt output. The default is for the readers to omit untranslatable + HTML codes and LaTeX environments. (The LaTeX reader does pass through + untranslatable LaTeX *commands*, even if `-R` is not specified.) + +`-S`, `--smart` + +: Produce typographically correct output, converting straight quotes + to curly quotes, `---` to em-dashes, `--` to en-dashes, and + `...` to ellipses. Nonbreaking spaces are inserted after certain + abbreviations, such as "Mr." (Note: This option is selected automatically + when the output format is `latex` or `context`, unless `--no-tex-ligatures` + is used. It has no effect for `latex` input.) + +`--old-dashes` + +: Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: `-` before + a numeral is an en-dash, and `--` is an em-dash. This option is selected + automatically for `textile` input. + +`--base-header-level=`*NUMBER* + +: Specify the base level for headers (defaults to 1). + +`--indented-code-classes=`*CLASSES* + +: Specify classes to use for indented code blocks--for example, + `perl,numberLines` or `haskell`. Multiple classes may be separated + by spaces or commas. + +`--default-image-extension=`*EXTENSION* + +: 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. + +`--file-scope` + +: 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`. + +`--filter=`*EXECUTABLE* + +: 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]. + + Note that the *EXECUTABLE* will be sought in the user's + `PATH`, and not in the working directory, if no directory is + provided. If you want to run a script in the working directory, + preface the filename with `./`. + +`-M` *KEY*[`=`*VAL*], `--metadata=`*KEY*[`:`*VAL*] + +: Set the metadata field *KEY* to the value *VAL*. A value specified + on the command line overrides a value specified in the document. + 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). + +`--normalize` + +: Normalize the document after reading: merge adjacent + `Str` or `Emph` elements, for example, and remove repeated `Space`s. + +`-p`, `--preserve-tabs` + +: Preserve tabs instead of converting them to spaces (the default). + Note that this will only affect tabs in literal code spans and code + blocks; tabs in regular text will be treated as spaces. + +`--tab-stop=`*NUMBER* + +: Specify the number of spaces per tab (default is 4). + +`--track-changes=accept`|`reject`|`all` + +: Specifies what to do with insertions, deletions, and comments + produced by the MS Word "Track Changes" feature. `accept` (the + default), inserts all insertions, and ignores all + deletions. `reject` inserts all deletions and ignores + insertions. Both `accept` and `reject` ignore comments. `all` puts + in 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. This + option only affects the docx reader. + +`--extract-media=`*DIR* + +: Extract images and other media contained in a docx or epub container + to the path *DIR*, creating it if necessary, and adjust the images + references in the document so they point to the extracted files. + This option only affects the docx and epub readers. + +[`pandocfilters`]: https://github.com/jgm/pandocfilters +[PHP]: https://github.com/vinai/pandocfilters-php +[perl]: https://metacpan.org/pod/Pandoc::Filter +[javascript/node.js]: https://github.com/mvhenderson/pandoc-filter-node + +General writer options +---------------------- + +`-s`, `--standalone` + +: 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. + +`--template=`*FILE* + +: Use *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`). + +`-V` *KEY*[`=`*VAL*], `--variable=`*KEY*[`:`*VAL*] + +: Set the template variable *KEY* to the value *VAL* when rendering the + document in standalone mode. This is generally only useful when the + `--template` option is used to specify a custom template, since + pandoc automatically sets the variables used in the default + templates. If no *VAL* is specified, the key will be given the + value `true`. + +`-D` *FORMAT*, `--print-default-template=`*FORMAT* + +: Print the system default template for an output *FORMAT*. (See `-t` + for a list of possible *FORMAT*s.) Templates in the user data + directory are ignored. + +`--print-default-data-file=`*FILE* + +: Print a system default data file. Files in the user data directory + are ignored. + +`--dpi`=*NUMBER* +: Specify the dpi (dots per inch) value for conversion from pixels + to inch/centimeters and vice versa. The default is 96dpi. + Technically, the correct term would be ppi (pixels per inch). + +`--wrap=[auto|none|preserve]` + +: 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 80). 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). + +`--no-wrap` + +: Deprecated synonym for `--wrap=none`. + +`--columns=`*NUMBER* + +: 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). + +`--toc`, `--table-of-contents` + +: Include an automatically generated table of contents (or, in + the case of `latex`, `context`, `docx`, and `rst`, an instruction to create + one) in the output document. This option has no effect on `man`, + `docbook`, `docbook5`, `slidy`, `slideous`, `s5`, or `odt` output. + +`--toc-depth=`*NUMBER* + +: 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 + headers will be listed in the contents). + +`--no-highlight` + +: Disables syntax highlighting for code blocks and inlines, even when + a language attribute is given. + +`--highlight-style=`*STYLE* + +: Specifies the coloring style to be used in highlighted source code. + Options are `pygments` (the default), `kate`, `monochrome`, + `espresso`, `zenburn`, `haddock`, and `tango`. For more information + on syntax highlighting in pandoc, see [Syntax highlighting], below. + +`-H` *FILE*, `--include-in-header=`*FILE* + +: Include contents of *FILE*, 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`. + +`-B` *FILE*, `--include-before-body=`*FILE* + +: Include contents of *FILE*, 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`. + +`-A` *FILE*, `--include-after-body=`*FILE* + +: Include contents of *FILE*, 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`. + +Options affecting specific writers +---------------------------------- + +`--self-contained` + +: Produce a standalone HTML file with no external dependencies, using + `data:` URIs to incorporate the contents of linked scripts, stylesheets, + images, and videos. 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 `html`, `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). 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. + +`--html-q-tags` + +: Use `` tags for quotes in HTML. + +`--ascii` + +: Use only ascii characters in output. Currently supported only + for HTML output (which uses numerical entities instead of + UTF-8 when this option is selected). + +`--reference-links` + +: Use reference-style links, rather than inline links, in writing Markdown + or reStructuredText. By default inline links are used. + +`--atx-headers` + +: Use ATX-style headers in Markdown and asciidoc output. The default is + to use setext-style headers for levels 1-2, and then ATX headers. + +`--chapters` + +: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook + output. When the LaTeX document class is set to `report`, `book`, + or `memoir` (unless the `article` option is specified), this + option is implied. If `beamer` is the output format, top-level + headers will become `\part{..}`. + +`-N`, `--number-sections` + +: Number section headings in LaTeX, ConTeXt, HTML, or EPUB output. + By default, sections are not numbered. Sections with class + `unnumbered` will never be numbered, even if `--number-sections` + is specified. + +`--number-offset=`*NUMBER*[`,`*NUMBER*`,`*...*] + +: Offset for section headings in HTML output (ignored in other + output formats). The first number is added to the section number for + top-level headers, the second for second-level headers, and so on. + So, for example, if you want the first top-level header in your + document to be numbered "6", specify `--number-offset=5`. + If your document starts with a level-2 header which you want to + be numbered "1.5", specify `--number-offset=1,4`. + Offsets are 0 by default. Implies `--number-sections`. + +`--no-tex-ligatures` + +: Do not use the TeX ligatures for quotation marks, apostrophes, + and dashes (`` `...' ``, ` ``..'' `, `--`, `---`) when + writing or reading LaTeX or ConTeXt. In reading LaTeX, + parse the characters `` ` ``, `'`, and `-` literally, rather + than parsing ligatures for quotation marks and dashes. In + writing LaTeX or ConTeXt, print unicode quotation mark and + dash characters literally, rather than converting them to + the standard ASCII TeX ligatures. Note: normally `--smart` + is selected automatically for LaTeX and ConTeXt output, but + it must be specified explicitly if `--no-tex-ligatures` is + selected. If you use literal curly quotes, dashes, and + ellipses in your source, then you may want to use + `--no-tex-ligatures` without `--smart`. + +`--listings` + +: Use the [`listings`] package for LaTeX code blocks + +`-i`, `--incremental` + +: Make list items in slide shows display incrementally (one by one). + The default is for lists to be displayed all at once. + +`--slide-level=`*NUMBER* + +: Specifies that headers with the specified level create + slides (for `beamer`, `s5`, `slidy`, `slideous`, `dzslides`). Headers + above this level in the hierarchy are used to divide the + slide show into sections; headers below this level create + subheads within a slide. The default is to set the slide level + based on the contents of the document; see + [Structuring the slide show]. + +`--section-divs` + +: Wrap sections in `
` tags (or `
` tags in HTML5), + and attach identifiers to the enclosing `
` (or `
`) + rather than the header itself. See + [Header identifiers], below. + +`--email-obfuscation=none`|`javascript`|`references` + +: 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`. + +`--id-prefix=`*STRING* + +: Specify a prefix to be added to all automatically generated identifiers + in HTML and DocBook output, and to footnote numbers in Markdown output. + This is useful for preventing duplicate identifiers when generating + fragments to be included in other pages. + +`-T` *STRING*, `--title-prefix=`*STRING* + +: Specify *STRING* 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`. + +`-c` *URL*, `--css=`*URL* + +: Link to a CSS style sheet. This option can be used repeatedly to + include multiple files. They will be included in the order specified. + +`--reference-odt=`*FILE* + +: Use the specified file as a style reference in producing an 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. + +`--reference-docx=`*FILE* + +: Use the specified file as a style reference in producing a docx file. + 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. The following styles are used by pandoc: [paragraph] + Normal, Body Text, First Paragraph, Compact, Title, Subtitle, Author, Date, + Abstract, Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, + Heading 5, Heading 6, Block Text, Footnote Text, Definition Term, + Definition, Caption, Table Caption, Image Caption, Figure, + Figure With Caption, TOC Heading; + [character] Default Paragraph Font, Body Text Char, Verbatim Char, + Footnote Reference, Hyperlink; [table] Normal Table. + +`--epub-stylesheet=`*FILE* + +: Use the specified CSS file to style the EPUB. If no stylesheet + is specified, 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. + +`--epub-cover-image=`*FILE* + +: 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). + +`--epub-metadata=`*FILE* + +: 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]. + +`--epub-embed-font=`*FILE* + +: 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 `--epub-stylesheet`): + + @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"; } + +`--epub-chapter-level=`*NUMBER* + +: Specify the header level at which to split the EPUB into separate + "chapter" files. The default is to split into chapters at level 1 + headers. 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 headers, one might want to use a chapter + level of 2 or 3. + +`--latex-engine=pdflatex`|`lualatex`|`xelatex` + +: Use the specified LaTeX engine when producing PDF output. + The default is `pdflatex`. If the engine is not in your PATH, + the full path of the engine may be specified here. + +`--latex-engine-opt=`*STRING* + +: Use the given string as a command-line argument to the `latex-engine`. + If used multiple times, the arguments are provided with spaces between + them. Note that no check for duplicate options is done. + +[Dublin Core elements]: http://dublincore.org/documents/dces/ +[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime + +Citation rendering +------------------ + +`--bibliography=`*FILE* + +: Set the `bibliography` field in the document's metadata to *FILE*, + overriding any value set in the metadata, and process citations + using `pandoc-citeproc`. (This is equivalent to + `--metadata bibliography=FILE --filter pandoc-citeproc`.) + If `--natbib` or `--biblatex` is also supplied, `pandoc-citeproc` is not + used, making this equivalent to `--metadata bibliography=FILE`. + If you supply this argument multiple times, each *FILE* will be added + to bibliography. + +`--csl=`*FILE* + +: Set the `csl` field in the document's metadata to *FILE*, + overriding any value set in the metadata. (This is equivalent to + `--metadata csl=FILE`.) + This option is only relevant with `pandoc-citeproc`. + +`--citation-abbreviations=`*FILE* + +: Set the `citation-abbreviations` field in the document's metadata to + *FILE*, overriding any value set in the metadata. (This is equivalent to + `--metadata citation-abbreviations=FILE`.) + This option is only relevant with `pandoc-citeproc`. + +`--natbib` + +: Use [`natbib`] for citations in LaTeX output. This option is not for use + with the `pandoc-citeproc` filter or with PDF output. It is intended for + use in producing a LaTeX file that can be processed with [`bibtex`]. + +`--biblatex` + +: Use [`biblatex`] for citations in LaTeX output. This option is not for use + with the `pandoc-citeproc` filter or with PDF output. It is intended for + use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`]. + +Math rendering in HTML +---------------------- + +`-m` [*URL*], `--latexmathml`[`=`*URL*] + +: Use the [LaTeXMathML] script to display embedded TeX math in HTML output. + To insert a link to a local copy of the `LaTeXMathML.js` script, + provide a *URL*. If no *URL* is provided, the contents of the + script will be inserted directly into the HTML header, preserving + portability at the price of efficiency. If you plan to use math on + several pages, it is much better to link to a copy of the script, + so it can be cached. + +`--mathml`[`=`*URL*] + +: Convert TeX math to [MathML] (in `docbook`, `docbook5`, `html` and `html5`). + In standalone `html` output, a small javascript (or a link to such a + script if a *URL* is supplied) will be inserted that allows the MathML to + be viewed on some browsers. + +`--jsmath`[`=`*URL*] + +: Use [jsMath] to display embedded TeX math in HTML output. + The *URL* should point to the jsMath load script (e.g. + `jsMath/easy/load.js`); if provided, it will be linked to in + the header of standalone HTML documents. If a *URL* is not provided, + no link to the jsMath load script will be inserted; it is then + up to the author to provide such a link in the HTML template. + +`--mathjax`[`=`*URL*] + +: Use [MathJax] to display embedded TeX math in HTML output. + The *URL* should point to the `MathJax.js` load script. + If a *URL* is not provided, a link to the MathJax CDN will + be inserted. + +`--gladtex` + +: Enclose TeX math in `` tags in HTML output. These can then + be processed by [gladTeX] to produce links to images of the typeset + formulas. + +`--mimetex`[`=`*URL*] + +: Render TeX math using the [mimeTeX] CGI script. If *URL* is not + specified, it is assumed that the script is at `/cgi-bin/mimetex.cgi`. + +`--webtex`[`=`*URL*] + +: Render TeX formulas using an external script that converts TeX + formulas to images. The formula will be concatenated with the URL + provided. If *URL* is not specified, the Google Chart API will be used. + Note: the `--webtex` option will affect Markdown output + as well as HTML. + +`--katex`[`=`*URL*] + +: Use [KaTeX] to display embedded TeX math in HTML output. + The *URL* should point to the `katex.js` load script. If a *URL* is + not provided, a link to the KaTeX CDN will be inserted. + +`--katex-stylesheet=`*URL* + +: The *URL* should point to the `katex.css` stylesheet. If this option is + not specified, a link to the KaTeX CDN will be inserted. Note that this + option does not imply `--katex`. + +[MathML]: http://www.w3.org/Math/ +[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/ +[jsMath]: http://www.math.union.edu/~dpvc/jsmath/ +[MathJax]: https://www.mathjax.org +[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/ +[mimeTeX]: http://www.forkosh.com/mimetex.html +[KaTeX]: https://github.com/Khan/KaTeX + +Options for wrapper scripts +--------------------------- + +`--dump-args` + +: Print information about command-line arguments to *stdout*, 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 *stdout*) 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. + +`--ignore-args` + +: 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 + +Templates +========= + +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 *FORMAT* 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 *FORMAT* +by putting a file `templates/default.*FORMAT*` in the user data +directory (see `--data-dir`, above). *Exceptions:* + +- For `odt` output, customize the `default.opendocument` + template. +- For `pdf` output, customize the `default.latex` template + (or the `default.beamer` template, if you use `-t beamer`, + or the `default.context` template, if you use `-t context`). +- `docx` has no template (however, you can use + `--reference-docx` to customize the output). + +Templates contain *variables*, which allow for the inclusion of +arbitrary information at any point in the file. Variables may be set +within the document using [YAML metadata blocks][Extension: +`yaml_metadata_block`]. They may also be set at the +command line using the `-V/--variable` option: variables set in this +way override metadata fields with the same name. + +Variables set by pandoc +----------------------- + +Some variables are set automatically by pandoc. These vary somewhat +depending on the output format, but include metadata fields as well +as the following: + +`title`, `author`, `date` +: 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][Extension: `pandoc_title_block`], + which allows for multiple authors, or through a YAML metadata block: + + --- + author: + - Aristotle + - Peter Abelard + ... + +`subtitle` +: document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word docx; + renders in LaTeX only when using a document class that supports + `\subtitle`, such as `beamer` or the [KOMA-Script] series (`scrartcl`, + `scrreprt`, `scrbook`).[^subtitle] + +`institute` +: author affiliations (in LaTeX and Beamer only). Can be a + list, when there are multiple authors. + +`abstract` +: document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx + +`keywords` +: list of keywords to be included in HTML, PDF, and AsciiDoc metadata; + may be repeated as for `author`, above + +`header-includes` +: contents specified by `-H/--include-in-header` (may have multiple + values) + +`toc` +: non-null value if `--toc/--table-of-contents` was specified + +`toc-title` +: title of table of contents (works only with EPUB and docx) + +`include-before` +: contents specified by `-B/--include-before-body` (may have + multiple values) + +`include-after` +: contents specified by `-A/--include-after-body` (may have + multiple values) + +`body` +: body of document + +`meta-json` +: JSON representation of all of the document's metadata + +[^subtitle]: To make `subtitle` work with other LaTeX + document classes, you can add the following to `header-includes`: + + \providecommand{\subtitle}[1]{% + \usepackage{titling} + \posttitle{% + \par\large#1\end{center}} + } + +Language variables +------------------ + +`lang` +: identifies the main language of the document, + using a code according to [BCP 47] (e.g. `en` or `en-GB`). + For some output formats, pandoc will convert it to an appropriate + format stored in the additional variables `babel-lang`, + `polyglossia-lang` (LaTeX) and `context-lang` (ConTeXt). + + Native pandoc `span`s and `div`s with the lang attribute + (value in BCP 47) can be used to switch the language in + that range. + +`otherlangs` +: a list of other languages used in the document + in the YAML metadata, according to [BCP 47]. For example: + `otherlangs: [en-GB, fr]`. + This is automatically generated from the `lang` attributes + in all `span`s and `div`s but can be overridden. + Currently only used by LaTeX through the generated + `babel-otherlangs` and `polyglossia-otherlangs` variables. + The LaTeX writer outputs polyglossia commands in the text but + the `babel-newcommands` variable contains mappings for them + to the corresponding babel. + +`dir` +: the base direction of the document, either `rtl` (right-to-left) + or `ltr` (left-to-right). + + For bidirectional documents, native pandoc `span`s and `div`s + 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 `--latex-engine=xelatex`). + +[BCP 47]: https://tools.ietf.org/html/bcp47 +[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics + +Variables for slides +-------------------- + +Variables are available for [producing slide shows with pandoc], +including all [reveal.js configuration options]. + +`slidy-url` +: base URL for Slidy documents (defaults to + `http://www.w3.org/Talks/Tools/Slidy2`) + +`slideous-url` +: base URL for Slideous documents (defaults to `slideous`) + +`s5-url` +: base URL for S5 documents (defaults to `s5/default`) + +`revealjs-url` +: base URL for reveal.js documents (defaults to `reveal.js`) + +`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` +: themes for LaTeX [`beamer`] documents + +`navigation` +: controls navigation symbols in `beamer` documents + (default is `empty` for no navigation symbols; other valid values + are `frame`, `vertical`, and `horizontal`). + +`section-titles` +: enables on "title pages" for new sections in `beamer` + documents (default = true). + +[reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration + +Variables for LaTeX +------------------- + +LaTeX variables are used when [creating a PDF]. + +`papersize` +: paper size, e.g. `letter`, `A4` + +`fontsize` +: font size for body text (e.g. `10pt`, `12pt`) + +`documentclass` +: document class, e.g. [`article`], [`report`], [`book`], [`memoir`] + +`classoption` +: option for document class, e.g. `oneside`; may be repeated + for multiple options + +`geometry` +: option for [`geometry`] package, e.g. `margin=1in`; + may be repeated for multiple options + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins, if `geometry` is not used (otherwise `geometry` + overrides these) + +`linestretch` +: adjusts line spacing using the [`setspace`] + package, e.g. `1.25`, `1.5` + +`fontfamily` +: font package for use with `pdflatex`: + [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. + The default is [Latin Modern][`lm`]. + +`fontfamilyoptions` +: options for package used as `fontfamily`: e.g. `osf,sc` with + `fontfamily` set to [`mathpazo`] provides Palatino with old-style + figures and true small caps; may be repeated for multiple options + +`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` +: font families for use with `xelatex` or + `lualatex`: take the name of any system font, using the + [`fontspec`] package. Note that if `CJKmainfont` is used, + the [`xecjk`] package must be available. + +`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions` +: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, + `CJKmainfont` in `xelatex` and `lualatex`. Allow for any choices + available through [`fontspec`], such as the OpenType features + `Numbers=OldStyle,Numbers=Proportional`. May be repeated for multiple options. + +`fontenc` +: allows font encoding to be specified through `fontenc` package (with `pdflatex`); + default is `T1` (see guide to [LaTeX font encodings]) + +`colorlinks` +: add color to link text; automatically enabled if any of `linkcolor`, `citecolor`, + `urlcolor`, or `toccolor` are set + +`linkcolor`, `citecolor`, `urlcolor`, `toccolor` +: color for internal links, citation links, external links, and links in table of contents: + uses any of the [predefined LaTeX colors] + +`links-as-notes` +: causes links to be printed as footnotes + +`indent` +: uses document class settings for indentation (the default LaTeX template + otherwise removes indentation and adds space between paragraphs) + +`subparagraph` +: disables default behavior of LaTeX template that redefines (sub)paragraphs + as sections, changing the appearance of nested headings in some classes + +`thanks` +: specifies contents of acknowledgments footnote after document title. + +`toc` +: include table of contents (can also be set using `--toc/--table-of-contents`) + +`toc-depth` +: level of section to include in table of contents + +`secnumdepth` +: numbering depth for sections, if sections are numbered + +`lof`, `lot` +: include list of figures, list of tables + +`bibliography` +: bibliography to use for resolving references + +`biblio-style` +: bibliography style, when used with `--natbib` and + `--biblatex`. + +`biblatexoptions` +: list of options for biblatex. + +[`article`]: https://ctan.org/pkg/article +[`report`]: https://ctan.org/pkg/report +[`book`]: https://ctan.org/pkg/book +[KOMA-Script]: https://ctan.org/pkg/koma-script +[`memoir`]: https://ctan.org/pkg/memoir +[predefined LaTeX colors]: https://en.wikibooks.org/wiki/LaTeX/Colors#Predefined_colors +[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/ +[`mathpazo`]: https://ctan.org/pkg/mathpazo +[LaTeX font encodings]: https://ctan.org/pkg/encguide + +Variables for ConTeXt +--------------------- + +`papersize` +: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]); + may be repeated for multiple options + +`layout` +: options for page margins and text arrangement (see [ConTeXt Layout]); + may be repeated for multiple options + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins, if `layout` is not used (otherwise `layout` + overrides these) + +`fontsize` +: font size for body text (e.g. `10pt`, `12pt`) + +`mainfont`, `sansfont`, `monofont`, `mathfont` +: font families: take the name of any system font (see [ConTeXt Font Switching]) + +`linkcolor`, `contrastcolor` +: color for links outside and inside a page, e.g. `red`, `blue` (see [ConTeXt Color]) + +`linkstyle` +: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`, `type`, `cap`, `small` + +`indenting` +: controls indentation of paragraphs, e.g. `yes,small,next` (see [ConTeXt Indentation]); + may be repeated for multiple options + +`whitespace` +: spacing between paragraphs, e.g. `none`, `small` (using [`setupwhitespace`]) + +`interlinespace` +: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); + may be repeated for multiple options + +`headertext`, `footertext` +: text to be placed in running header or footer (see [ConTeXt Headers and Footers]); + may be repeated up to four times for different placement + +`pagenumbering` +: page number style and location (using [`setuppagenumbering`]); + may be repeated for multiple options + +`toc` +: include table of contents (can also be set using `--toc/--table-of-contents`) + +`lof`, `lot` +: include list of figures, list of tables + +[ConTeXt Paper Setup]: http://wiki.contextgarden.net/PaperSetup +[ConTeXt Layout]: http://wiki.contextgarden.net/Layout +[ConTeXt Font Switching]: http://wiki.contextgarden.net/Font_Switching +[ConTeXt Color]: http://wiki.contextgarden.net/Color +[ConTeXt Headers and Footers]: http://wiki.contextgarden.net/Headers_and_Footers +[ConTeXt Indentation]: http://wiki.contextgarden.net/Indentation +[`setupwhitespace`]: http://wiki.contextgarden.net/Command/setupwhitespace +[`setupinterlinespace`]: http://wiki.contextgarden.net/Command/setupinterlinespace +[`setuppagenumbering`]: http://wiki.contextgarden.net/Command/setuppagenumbering + +Variables for man pages +----------------------- + +`section` +: section number in man pages + +`header` +: header in man pages + +`footer` +: footer in man pages + +`adjusting` +: adjusts text to left (`l`), right (`r`), center (`c`), + or both (`b`) margins + +`hyphenate` +: if `true` (the default), hyphenation will be used + +Using variables in templates +---------------------------- + +Variable names are sequences of alphanumerics, `-`, and `_`, +starting with a letter. A variable name surrounded by `$` signs +will be replaced by its value. For example, the string `$title$` in + + $title$ + +will be replaced by the document title. + +To write a literal `$` in a template, use `$$`. + +Templates may contain conditionals. The syntax is as follows: + + $if(variable)$ + X + $else$ + Y + $endif$ + +This will include `X` in the template if `variable` has a non-null +value; otherwise it will include `Y`. `X` and `Y` are placeholders for +any valid template text, and may include interpolated variables or other +conditionals. The `$else$` section may be omitted. + +When variables can have multiple values (for example, `author` in +a multi-author document), you can use the `$for$` keyword: + + $for(author)$ + + $endfor$ + +You can optionally specify a separator to be used between +consecutive items: + + $for(author)$$author$$sep$, $endfor$ + +A dot can be used to select a field of a variable that takes +an object as its value. So, for example: + + $author.name$ ($author.affiliation$) + +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. + +[pandoc-templates]: https://github.com/jgm/pandoc-templates + +Pandoc's Markdown +================= + +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`. An extensions can be enabled by adding `+EXTENSION` +to the format name and disabled by adding `-EXTENSION`. For example, +`markdown_strict+footnotes` is strict Markdown with footnotes +enabled, while `markdown-footnotes-pipe_tables` is pandoc's +Markdown without footnotes or pipe tables. + +Philosophy +---------- + +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](http://daringfireball.net/projects/markdown/syntax#philosophy) + +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. + +Paragraphs +---------- + +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. + +#### Extension: `escaped_line_breaks` #### + +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. + +Headers +------- + +There are two kinds of headers: Setext and ATX. + +### Setext-style headers ### + +A setext-style header is a line of text "underlined" with a row of `=` signs +(for a level one header) or `-` signs (for a level two header): + + A level-one header + ================== + + A level-two header + ------------------ + +The header text can contain inline formatting, such as emphasis (see +[Inline formatting], below). + + +### ATX-style headers ### + +An ATX-style header 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 header level: + + ## A level-two header + + ### A level-three header ### + +As with setext-style headers, the header text can contain formatting: + + # A level-one header with a [link](/url) and *emphasis* + +#### Extension: `blank_before_header` #### + +Standard Markdown syntax does not require a blank line before a header. +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. + + +### Header identifiers ### + +#### Extension: `header_attributes` #### + +Headers can be assigned attributes using this syntax at the end +of the line containing the header text: + + {#identifier .class .class key=value key=value} + +Thus, for example, the following headers will all be assigned the identifier +`foo`: + + # My header {#foo} + + ## My header ## {#foo} + + My other header {#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, and AsciiDoc writers. + +Headers 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 header {-} + +is just the same as + + # My header {.unnumbered} + +#### Extension: `auto_identifiers` #### + +A header without an explicitly specified identifier will be +automatically assigned a unique identifier based on the header text. +To derive the identifier from the header text, + + - Remove all formatting, links, etc. + - Remove all footnotes. + - Remove all punctuation, 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, + + Header Identifier + ------------------------------- ---------------------------- + `Header identifiers in HTML` `header-identifiers-in-html` + `*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 header text. The exception is when several headers 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. + +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 + [header identifiers](#header-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 `div` (or a `section`, if `--html5` was specified), +and the identifier will be attached to the enclosing `
` +(or `
`) tag rather than the header itself. This allows entire +sections to be manipulated using javascript or treated differently in +CSS. + +#### Extension: `implicit_header_references` #### + +Pandoc behaves as if reference links have been defined for each header. +So, to link to a header + + # Header identifiers in HTML + +you can simply write + + [Header identifiers in HTML] + +or + + [Header identifiers in HTML][] + +or + + [the section on header identifiers][header identifiers in + HTML] + +instead of giving the identifier explicitly: + + [Header identifiers in HTML](#header-identifiers-in-html) + +If there are multiple headers 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 header references. So, in the following example, the +link will point to `bar`, not to `#foo`: + + # Foo + + [foo]: bar + + See [foo] + +Block quotations +---------------- + +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 headers), 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 + +#### Extension: `blank_before_blockquote` #### + +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. + + +Verbatim (code) blocks +---------------------- + +### Indented code blocks ### + +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. + + +### Fenced code blocks ### + +#### Extension: `fenced_code_blocks` #### + +In addition to standard indented code blocks, pandoc supports +*fenced* 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 + ~~~~~~~~~~ + ~~~~~~~~~~~~~~~~ + +#### Extension: `backtick_code_blocks` #### + +Same as `fenced_code_blocks`, but uses backticks (`` ` ``) instead of tildes +(`~`). + +#### Extension: `fenced_code_attributes` #### + +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 and LaTeX. 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, do +`pandoc --version`.) Otherwise, the code block above will appear as follows: + + 
+      
+      ...
+      
+
+ +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 codeblock, 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. + +Line blocks +----------- + +#### Extension: `line_blocks` #### + +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 + +This syntax is borrowed from [reStructuredText]. + +Lists +----- + +### Bullet lists ### + +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. + +### The four-space rule ### + +A list item may contain multiple paragraphs and other block-level +content. However, subsequent paragraphs must be preceded by a blank line +and indented four spaces or a tab. The list will look better if the first +paragraph is aligned with the rest: + + * First paragraph. + + Continued. + + * Second paragraph. With a code block, which must be indented + eight spaces: + + { code } + +List items may include other lists. In this case the preceding blank +line is optional. The nested list must be indented four spaces or +one tab: + + * 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. + +**Note:** Although the four-space rule for continuation paragraphs +comes from the official [Markdown syntax guide], the reference implementation, +`Markdown.pl`, does not follow it. So pandoc will give different results than +`Markdown.pl` when authors have indented continuation paragraphs fewer than +four spaces. + +The [Markdown syntax guide] is not explicit whether the four-space +rule applies to *all* block-level content in a list item; it only +mentions paragraphs and code blocks. But it implies that the rule +applies to all block-level content (including nested lists), and +pandoc interprets it that way. + + [Markdown syntax guide]: + http://daringfireball.net/projects/markdown/syntax#list + +### Ordered lists ### + +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 + +#### Extension: `fancy_lists` #### + +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.[^2] + +[^2]: The point of this rule is to ensure that normal paragraphs + starting with people's initials, like + + B. Russell was an English philosopher. + + do not get treated as list items. + + This rule will not prevent + + (C) 2007 Joe Smith + + from being interpreted as a list item. In this case, a backslash + escape can be used: + + (C\) 2007 Joe Smith + +The `fancy_lists` extension also allows '`#`' to be used as an +ordered list marker in place of a numeral: + + #. one + #. two + +#### Extension: `startnum` #### + +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 + + +### Definition lists ### + +#### Extension: `definition_lists` #### + +Pandoc supports definition lists, using the syntax of +[PHP Markdown Extra] with some extensions.[^3] + + 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-pandoc extensions], below.) + +[^3]: I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html). + +### Numbered example lists ### + +#### Extension: `example_lists` #### + +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. + + +### Compact and loose lists ### + +Pandoc behaves differently from `Markdown.pl` on some "edge +cases" involving lists. Consider this source: + + + First + + Second: + - Fee + - Fie + - Foe + + + Third + +Pandoc transforms this into a "compact list" (with no `

` tags around +"First", "Second", or "Third"), while Markdown puts `

` tags around +"Second" and "Third" (but not "First"), because of the blank space +around "Third". Pandoc follows a simple rule: if the text is followed by +a blank line, it is treated as a paragraph. Since "Second" is followed +by a list, and not a blank line, it isn't treated as a paragraph. The +fact that the list is followed by a blank line is irrelevant. (Note: +Pandoc works this way even when the `markdown_strict` format is specified. This +behavior is consistent with the official Markdown syntax description, +even though it is different from that of `Markdown.pl`.) + + +### Ending a list ### + +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 + +Horizontal rules +---------------- + +A line containing a row of three or more `*`, `-`, or `_` characters +(optionally separated by spaces) produces a horizontal rule: + + * * * * + + --------------- + + +Tables +------ + +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. + +#### Extension: `table_captions` #### + +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. + +#### Extension: `simple_tables` #### + +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 headers 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:[^4] + + - 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). + +[^4]: This scheme is due to Michel Fortin, who proposed it on the + [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html). + +The table must end with a blank line, or a line of dashes followed by +a blank line. + +The column headers 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 headers are 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. + +#### Extension: `multiline_tables` #### + +Multiline tables allow headers 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 headers are 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. + +Headers 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 headers. + +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. + +#### Extension: `grid_tables` #### + +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.). Alignments are not supported, nor are cells that span multiple +columns or rows. Grid tables can be created easily using [Emacs table mode]. + +[Emacs table mode]: http://table.sourceforge.net/ + +#### Extension: `pipe_tables` #### + +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 printable content is wider than the column width (see +`--columns`), then the cell contents will wrap, with the +relative cell widths determined by the widths of the separator +lines. + +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. + +[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table + +Metadata blocks +--------------- + +#### Extension: `pandoc_title_block` #### + +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. + +#### Extension: `yaml_metadata_block` #### + +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 +`...`.) + +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.) + +A document may contain multiple metadata blocks. The metadata fields will +be combined through a *left-biased union*: if two metadata blocks attempt +to set the same field, the value from the first 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. 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: + + --- + title: 'This is the title: it contains a colon' + author: + - name: Author One + affiliation: University of Somewhere + - name: Author Two + affiliation: University of Nowhere + tags: [nothing, nothingness] + abstract: | + This is the abstract. + + It consists of two paragraphs. + ... + +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.

+ +Note: The `author` variable in the default templates expects a simple list or +string. To use the structured authors in the example, you would need a +custom template. For example: + + $for(author)$ + $if(author.name)$ + $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$ + $else$ + $author$ + $endif$ + $endfor$ + + +Backslash escapes +----------------- + +#### Extension: `all_symbols_escapable` #### + +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. It will +appear in TeX output as `~` and in HTML and XML as `\ ` or +`\ `. + +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. + +Smart punctuation +----------------- + +#### Extension #### + +If the `--smart` option is specified, pandoc will produce typographically +correct output, converting straight quotes to curly quotes, `---` to +em-dashes, `--` to en-dashes, and `...` to ellipses. Nonbreaking spaces +are inserted after certain abbreviations, such as "Mr." + +Note: if your LaTeX template or any included header file call for the +[`csquotes`] package, pandoc will detect this automatically and use +`\enquote{...}` for quoted text. + +Inline formatting +----------------- + +### Emphasis ### + +To *emphasize* some text, surround it with `*`s or `_`, like this: + + This text is _emphasized with underscores_, and this + is *emphasized with asterisks*. + +Double `*` or `_` produces **strong emphasis**: + + 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\*. + +#### Extension: `intraword_underscores` #### + +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*. + + +### Strikeout ### + +#### Extension: `strikeout` #### + +To strikeout a section of text with a horizontal line, begin and end it +with `~~`. Thus, for example, + + This ~~is deleted text.~~ + + +### Superscripts and subscripts ### + +#### Extension: `superscript`, `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. + +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 `^`.) +Thus, if you want the letter P with 'a cat' in subscripts, use +`P~a\ cat~`, not `P~a cat~`. + + +### Verbatim ### + +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: `\*`. + +#### Extension: `inline_code_attributes` #### + +Attributes can be attached to verbatim text, just as with +[fenced code blocks]: + + `<$>`{.haskell} + +### Small caps ### + +To write small caps, you can use an HTML span tag: + + Small caps + +(The semicolon is optional and there may be space after the +colon.) This will work in all output formats that support small caps. + +Math +---- + +#### Extension: `tex_math_dollars` #### + +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. + +TeX math will be printed in all output formats. How it is rendered +depends on the output format: + +Markdown, LaTeX, Emacs Org mode, ConTeXt, ZimWiki + ~ It will appear verbatim between `$` characters. + +reStructuredText + ~ It will be rendered using an [interpreted text role `:math:`]. + +AsciiDoc + ~ It will be rendered as `latexmath:[...]`. + +Texinfo + ~ It will be rendered inside a `@math` command. + +groff man + ~ It will be rendered verbatim without `$`'s. + +MediaWiki, DokuWiki + ~ It will be rendered inside `` tags. + +Textile + ~ It will be rendered inside `` tags. + +RTF, OpenDocument, ODT + ~ It will be rendered, if possible, using unicode characters, + and will otherwise appear verbatim. + +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 Google Charts 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: + + 1. The default is to render TeX math as far as possible using unicode + characters, as with RTF, DocBook, and OpenDocument output. Formulas + are put inside a `span` with `class="math"`, so that they may be + styled differently from the surrounding text if needed. + + 2. If the `--latexmathml` option is used, TeX math will be displayed + between `$` or `$$` characters and put in `` tags with class `LaTeX`. + The [LaTeXMathML] script will be used to render it as formulas. + (This trick does not work in all browsers, but it works in Firefox. + In browsers that do not support LaTeXMathML, TeX math will appear + verbatim between `$` characters.) + + 3. If the `--jsmath` option is used, TeX math will be put inside + `` tags (for inline math) or `
` tags (for display math) + with class `math`. The [jsMath] script will be used to render + it. + + 4. If the `--mimetex` option is used, the [mimeTeX] CGI script will + be called to generate images for each TeX formula. This should + work in all browsers. The `--mimetex` option takes an optional URL + as argument. If no URL is specified, it will be assumed that the + mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`. + + 5. If the `--gladtex` option is used, TeX formulas will be enclosed + in `` tags in the HTML output. The resulting `htex` file may then + be processed by [gladTeX], which will produce image files for each + formula and an HTML file with links to these images. So, the + procedure is: + + pandoc -s --gladtex myfile.txt -o myfile.htex + gladtex -d myfile-images myfile.htex + # produces myfile.html and images in myfile-images + + 6. If the `--webtex` option is used, TeX formulas will be converted + 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. If no URL is specified, the Google Chart + API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`). + + 7. If the `--mathjax` option is used, TeX math will be displayed + between `\(...\)` (for inline math) or `\[...\]` (for display + math) and put in `` tags with class `math`. + The [MathJax] script will be used to render it as formulas. + +[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math + +Raw HTML +-------- + +#### Extension: `raw_html` #### + +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, Emacs Org mode, and Textile output, and suppressed +in other formats. + +#### Extension: `markdown_in_html_blocks` #### + +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](http://google.com)
+ +into + + + + + + +
onea link
+ +whereas `Markdown.pl` will preserve it as is. + +There is one exception to this rule: text between `