diff options
Diffstat (limited to 'MANUAL.txt')
| -rw-r--r-- | MANUAL.txt | 2024 |
1 files changed, 1228 insertions, 796 deletions
diff --git a/MANUAL.txt b/MANUAL.txt index ba6f25a3e..168f1784e 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,6 +1,6 @@ % Pandoc User's Guide % John MacFarlane -% January 29, 2017 +% March 2, 2018 Synopsis ======== @@ -11,36 +11,42 @@ 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 -further 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 +another, and a command-line tool that uses this library. + +Pandoc can read [Markdown], [CommonMark], [PHP Markdown Extra], +[GitHub-Flavored Markdown], [MultiMarkdown], and (subsets of) [Textile], +[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki +markup], [TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML], +[Emacs Org mode], [DocBook], [JATS], [Muse], [txt2tags], [Vimwiki], +[EPUB], [ODT], and [Word docx]. + +Pandoc 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], [JATS], [OpenDocument], [ODT], [Word docx], [GNU Texinfo], +[MediaWiki markup], [DokuWiki markup], [ZimWiki markup], [Haddock +markup], [EPUB] \(v2 or v3\), [FictionBook2], [Textile], [groff man], +[groff ms], [Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI +Simple], [Muse], [PowerPoint] slide shows and [Slidy], [Slideous], +[DZSlides], [reveal.js] or [S5] HTML slide shows. It can also produce +[PDF] output on systems where LaTeX, ConTeXt, `pdfroff`, +`wkhtmltopdf`, `prince`, or `weasyprint` is installed. + +Pandoc's enhanced version of Markdown includes syntax for [tables], +[definition lists], [metadata blocks], [`Div` blocks][Extension: +`fenced_divs`], [footnotes] and [citations], embedded +[LaTeX][Extension: `raw_tex`] (including [math]), [Markdown inside HTML +block elements][Extension: `markdown_in_html_blocks`], and much more. +These enhancements, described further under [Pandoc's Markdown], +can be disabled using the `markdown_strict` format. + +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 +(like an _abstract syntax tree_ or AST), and a set of writers, which convert this native representation into a target format. Thus, adding an input -or output format requires only adding a reader or writer. +or output format requires only adding a reader or writer. Users can also +run custom [pandoc filters] to modify the intermediate AST. Because pandoc's intermediate representation of a document is less expressive than many of the formats it converts between, one should @@ -63,6 +69,7 @@ Markdown can be expected to be lossy. [Slideous]: http://goessner.net/articles/slideous/ [HTML]: http://www.w3.org/html/ [HTML5]: http://www.w3.org/TR/html5/ +[polyglot markup]: https://www.w3.org/TR/html-polyglot/ [XHTML]: http://www.w3.org/TR/xhtml1/ [LaTeX]: http://latex-project.org [`beamer`]: https://ctan.org/pkg/beamer @@ -70,6 +77,7 @@ Markdown can be expected to be lossy. [ConTeXt]: http://www.contextgarden.net/ [RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format [DocBook]: http://docbook.org +[JATS]: https://jats.nlm.nih.gov [txt2tags]: http://txt2tags.org [EPUB]: http://idpf.org/epub [OPML]: http://dev.opml.org/spec2.html @@ -80,8 +88,11 @@ Markdown can be expected to be lossy. [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 +[TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax [Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html +[Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0 [groff man]: http://man7.org/linux/man-pages/man7/groff_man.7.html +[groff ms]: http://man7.org/linux/man-pages/man7/groff_ms.7.html [Haskell]: https://www.haskell.org [GNU Texinfo]: http://www.gnu.org/software/texinfo/ [Emacs Org mode]: http://orgmode.org @@ -91,44 +102,41 @@ Markdown can be expected to be lossy. [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 +[InDesign ICML]: http://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf [TEI Simple]: https://github.com/TEIC/TEI-Simple +[Muse]: https://amusewiki.org/library/manual +[PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint +[Vimwiki]: https://vimwiki.github.io 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: +If no *input-files* are specified, input is read from *stdin*. +Output goes to *stdout* by default. 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: +By default, pandoc produces a document fragment. To produce a standalone +document (e.g. a valid HTML file including `<head>` and `<body>`), +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 +[Templates] below. 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`. +blank lines between them) before parsing. (Use `--file-scope` to parse files +individually.) + +Specifying formats +------------------ 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: +`-f/--from` option, the output format using the `-t/--to` option. +Thus, to convert `hello.txt` from Markdown to LaTeX, you could type: pandoc -f markdown -t latex hello.txt @@ -136,14 +144,15 @@ 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. +Supported input and output formats are listed below under [Options] +(see `-f` for input formats and `-t` for output formats). You +can also use `pandoc --list-input-formats` and +`pandoc --list-output-formats` to print lists of supported +formats. If the input or output format is not specified explicitly, `pandoc` -will attempt to guess it from the extensions of -the input and output filenames. Thus, for example, +will attempt to guess it from the extensions of the filenames. +Thus, for example, pandoc -o hello.tex hello.txt @@ -152,7 +161,10 @@ 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. +be assumed to be Markdown. + +Character encoding +------------------ Pandoc uses the UTF-8 character encoding for both input and output. If your local character encoding is not UTF-8, you @@ -170,45 +182,56 @@ will only be included if you use the `-s/--standalone` option. 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: +To produce a PDF, specify an output file with a `.pdf` extension: 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. +By default, pandoc will use LaTeX to create the PDF, which requires +that a LaTeX engine be installed (see `--pdf-engine` below). + +Alternatively, pandoc can use [ConTeXt], `pdfroff`, or any of the +following HTML/CSS-to-PDF-engines, to create a PDF: [`wkhtmltopdf`], +[`weasyprint`] or [`prince`]. +To do this, specify an output file with a `.pdf` extension, as before, +but add the `--pdf-engine` option or `-t context`, `-t html`, or `-t ms` +to the command line (`-t html` defaults to `--pdf-engine=wkhtmltopdf`). PDF output can be controlled using [variables for LaTeX] (if LaTeX is used) and [variables for ConTeXt] (if ConTeXt is used). +When using an HTML/CSS-to-PDF-engine, `--css` affects the output. If `wkhtmltopdf` is used, then the variables `margin-left`, -`margin-right`, `margin-top`, `margin-bottom`, and `papersize` -will affect the output, as will `--css`. +`margin-right`, `margin-top`, `margin-bottom`, `footer-html`, +`header-html` and `papersize` will affect the output. + +To debug the PDF creation, it can be useful to look at the intermediate +representation: instead of `-o test.pdf`, use for example `-s -o test.tex` +to output the generated LaTeX. You can then test it with `pdflatex test.tex`. + +When using LaTeX, the following packages need to be available +(they are included with all recent versions of [TeX Live]): +[`amsfonts`], [`amsmath`], [`lm`], [`unicode-math`], +[`ifxetex`], [`ifluatex`], [`listings`] (if the +`--listings` option is used), [`fancyvrb`], [`longtable`], +[`booktabs`], [`graphicx`] and [`grffile`] (if the document +contains images), [`hyperref`], [`xcolor`] (with `colorlinks`), +[`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 +[`polyglossia`] (with `lang`), [`xecjk`], and [`bidi`] (with the +`dir` variable set). If the `mathspec` variable is set, +`xelatex` will use [`mathspec`] instead of [`unicode-math`]. +The [`upquote`] and [`microtype`] packages are used if +available, and [`csquotes`] will be used for [typography] +if added to the template or included in any header file. The +[`natbib`], [`biblatex`], [`bibtex`], and [`biber`] packages can +optionally be used for [citation rendering]. [`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 @@ -223,6 +246,7 @@ will affect the output, as will `--css`. [`babel`]: https://ctan.org/pkg/babel [`bidi`]: https://ctan.org/pkg/bidi [`mathspec`]: https://ctan.org/pkg/mathspec +[`unicode-math`]: https://ctan.org/pkg/unicode-math [`polyglossia`]: https://ctan.org/pkg/polyglossia [`fontspec`]: https://ctan.org/pkg/fontspec [`upquote`]: https://ctan.org/pkg/upquote @@ -233,6 +257,23 @@ will affect the output, as will `--css`. [`bibtex`]: https://ctan.org/pkg/bibtex [`biber`]: https://ctan.org/pkg/biber [TeX Live]: http://www.tug.org/texlive/ +[`wkhtmltopdf`]: https://wkhtmltopdf.org +[`weasyprint`]: http://weasyprint.org +[`prince`]: https://www.princexml.com/ + +Reading from the Web +-------------------- + +Instead of an input file, an absolute URI may be given. In this case +pandoc will fetch the content using HTTP: + + pandoc -f html -t markdown http://www.fsf.org + +It is possible to supply a custom User-Agent string or other +header when requesting a document from a URL: + + pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \ + http://www.fsf.org Options ======= @@ -245,23 +286,20 @@ General options : 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), + Markdown), `markdown_phpextra` (PHP Markdown Extra), + `markdown_mmd` (MultiMarkdown), `gfm` (GitHub-Flavored Markdown), `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 + markup), `tikiwiki` (TikiWiki markup), `creole` (Creole 1.0), + `haddock` (Haddock markup), or `latex` (LaTeX). + (`markdown_github` provides deprecated and less accurate support + for Github-Flavored Markdown; please use `gfm` instead, unless you + need to use extensions other than `smart`.) + Extensions can be individually enabled or disabled by + appending `+EXTENSION` or `-EXTENSION` to the format name. + See [Extensions] below, for a list of extensions and their names. See `--list-input-formats` and `--list-extensions`, below. @@ -271,46 +309,45 @@ General options `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`. - See `--list-output-formats` and `--list-extensions`, below. + Extra), `markdown_mmd` (MultiMarkdown), `gfm` (GitHub-Flavored + Markdown), `commonmark` (CommonMark Markdown), `rst` + (reStructuredText), `html4` (XHTML 1.0 Transitional), `html` or + `html5` (HTML5/XHTML [polyglot markup]), `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` or + `docbook4` (DocBook 4), `docbook5` (DocBook 5), `jats` (JATS XML), + `opendocument` (OpenDocument), `odt` (OpenOffice text document), + `docx` (Word docx), `haddock` (Haddock markup), `rtf` (rich text + format), `epub2` (EPUB v2 book), `epub` or `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), `pptx` (PowerPoint slide show) or + the path of a custom lua writer (see [Custom writers], + below). (`markdown_github` provides deprecated and less accurate + support for Github-Flavored Markdown; please use `gfm` instead, + unless you use extensions that do not work with `gfm`.) Note that + `odt`, `docx`, and `epub` output will not be directed to *stdout* + unless forced with `-o -`. Extensions can be individually enabled or + disabled by appending `+EXTENSION` or `-EXTENSION` to the format + name. See [Extensions] below, for a list of extensions and their + names. See `--list-output-formats` and `--list-extensions`, below. `-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.) + `-`, output will go to *stdout*, even if a non-textual format + (`docx`, `odt`, `epub2`, `epub3`) is specified. `--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: + will be used. This is, in UNIX: $HOME/.pandoc @@ -333,13 +370,27 @@ General options : Generate a bash completion script. To enable bash completion with pandoc, add this to your `.bashrc`: - eval "$(pandoc --bash-completion)" + eval "$(pandoc --bash-completion)" `--verbose` : Give verbose debugging output. Currently this only has an effect with PDF output. +`--quiet` + +: Suppress warning messages. + +`--fail-if-warnings` + +: Exit with error status if there are any warnings. + +`--log=`*FILE* + +: Write log messages in machine-readable JSON format to + *FILE*. All messages above DEBUG level will be written, + regardless of verbosity settings (`--verbose`, `--quiet`). + `--list-input-formats` : List supported input formats, one per line. @@ -348,11 +399,12 @@ General options : List supported output formats, one per line. -`--list-extensions` +`--list-extensions`[`=`*FORMAT*] -: List supported Markdown extensions, one per line, followed +: List supported extensions, one per line, preceded by a `+` or `-` indicating whether it is enabled by default - in pandoc's Markdown. + in *FORMAT*. If *FORMAT* is not specified, defaults for + pandoc's Markdown are given. `--list-highlight-languages` @@ -375,36 +427,17 @@ General options 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). +`--strip-empty-paragraphs` + +: *Deprecated. Use the `+empty_paragraphs` extension instead.* + Ignore paragraphs with no content. This option is useful + for converting word processing documents where users have + used empty paragraphs to create inter-paragraph space. + `--indented-code-classes=`*CLASSES* : Specify classes to use for indented code blocks--for example, @@ -448,7 +481,7 @@ Reader options 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]. + [JavaScript/node.js]. In order of preference, pandoc will look for filters in @@ -456,9 +489,39 @@ Reader options non-executable) 2. `$DATADIR/filters` (executable or non-executable) + where `$DATADIR` is the user data directory (see + `--data-dir`, above). 3. `$PATH` (executable only) + Filters and lua-filters are applied in the order specified + on the command line. + +`--lua-filter=`*SCRIPT* + +: Transform the document in a similar fashion as JSON filters (see + `--filter`), but use pandoc's build-in lua filtering system. The given + lua script is expected to return a list of lua filters which will be + applied in order. Each lua filter must contain element-transforming + functions indexed by the name of the AST element on which the filter + function should be applied. + + The `pandoc` lua module provides helper functions for element + creation. It is always loaded into the script's lua environment. + + The following is an example lua script for macro-expansion: + + function expand_hello_world(inline) + if inline.c == '{{helloworld}}' then + return pandoc.Emph{ pandoc.Str "Hello, World" } + else + return inline + end + end + + return {{Str = expand_hello_world}} + + `-M` *KEY*[`=`*VAL*], `--metadata=`*KEY*[`:`*VAL*] : Set the metadata field *KEY* to the value *VAL*. A value specified @@ -470,11 +533,6 @@ Reader options 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). @@ -496,20 +554,41 @@ Reader options `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. + from a certain reviewer, say, or before a certain date. If a + paragraph is inserted or deleted, `track-changes=all` produces a + span with the class `paragraph-insertion`/`paragraph-deletion` + before the affected paragraph break. This option only affects the + docx reader. `--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. +: Extract images and other media contained in or linked from + the source document to the path *DIR*, creating it if + necessary, and adjust the images references in the document + so they point to the extracted files. If the source format is + a binary container (docx, epub, or odt), the media is + extracted from the container and the original + filenames are used. Otherwise the media is read from the + file system or downloaded, and new filenames are constructed + based on SHA1 hashes of the contents. + +`--abbreviations=`*FILE* + +: Specifies a custom abbreviations file, with abbreviations + one to a line. If this option is not specified, pandoc will + read the data file `abbreviations` from the user data + directory or fall back on a system default. To see the + system default, use + `pandoc --print-default-data-file=abbreviations`. The only + use pandoc makes of this list is in the Markdown reader. + Strings ending in a period that are found in this list will + be followed by a nonbreaking space, so that the period will + not produce sentence-ending space in formats like LaTeX. [`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 +[JavaScript/node.js]: https://github.com/mvhenderson/pandoc-filter-node General writer options ---------------------- @@ -553,7 +632,15 @@ General writer options : Print a system default data file. Files in the user data directory are ignored. +`--eol=crlf`|`lf`|`native` + +: Manually specify line endings: `crlf` (Windows), `lf` + (macOS/Linux/UNIX), or `native` (line endings appropriate + to the OS on which pandoc is being run). The default is + `native`. + `--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). @@ -570,10 +657,6 @@ General writer options will be nonsemantic newlines in the output as well). Automatic wrapping does not currently work in HTML output. -`--no-wrap` - -: Deprecated synonym for `--wrap=none`. - `--columns=`*NUMBER* : Specify length of lines in characters. This affects text wrapping @@ -583,9 +666,10 @@ General writer options `--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. + the case of `latex`, `context`, `docx`, `odt`, + `opendocument`, `rst`, or `ms`, an instruction to create + one) in the output document. This option has no effect on + `man`, `docbook4`, `docbook5`, or `jats` output. `--toc-depth=`*NUMBER* @@ -593,12 +677,20 @@ General writer options of contents. The default is 3 (which means that level 1, 2, and 3 headers will be listed in the contents). +`--strip-comments` + +: Strip out HTML comments in the Markdown or Textile source, + rather than passing them on to Markdown, Textile or HTML + output as raw HTML. This does not apply to HTML comments + inside raw HTML blocks when the `markdown_in_html_blocks` + extension is not set. + `--no-highlight` : Disables syntax highlighting for code blocks and inlines, even when a language attribute is given. -`--highlight-style=`*STYLE* +`--highlight-style=`*STYLE*|*FILE* : Specifies the coloring style to be used in highlighted source code. Options are `pygments` (the default), `kate`, `monochrome`, @@ -607,6 +699,28 @@ General writer options [Syntax highlighting], below. See also `--list-highlight-styles`. + Instead of a *STYLE* name, a JSON file with extension + `.theme` may be supplied. This will be parsed as a KDE + syntax highlighting theme and (if valid) used as the + highlighting style. + + To generate the JSON version of an existing style, + use `--print-highlight-style`. + +`--print-highlight-style=`*STYLE*|*FILE* + +: Prints a JSON version of a highlighting style, which can + be modified, saved with a `.theme` extension, and used + with `--highlight-style`. + +`--syntax-definition=`*FILE* + +: Instructs pandoc to load a KDE XML syntax definition file, + which will be used for syntax highlighting of appropriately + marked code blocks. This can be used to add support for + new languages or to use altered syntax definitions for + existing languages. + `-H` *FILE*, `--include-in-header=`*FILE* : Include contents of *FILE*, verbatim, at the end of the header. @@ -632,6 +746,25 @@ General writer options repeatedly to include multiple files. They will be included in the order specified. Implies `--standalone`. +`--resource-path=`*SEARCHPATH* + +: List of paths to search for images and other resources. + The paths should be separated by `:` on Linux, UNIX, and + macOS systems, and by `;` on Windows. If `--resource-path` + is not specified, the default resource path is the working + directory. Note that, if `--resource-path` is specified, + the working directory must be explicitly listed or it + will not be searched. For example: + `--resource-path=.:test` will search the working directory + and the `test` subdirectory, in that order. + +`--request-header=`*NAME*`:`*VAL* + +: Set the request header *NAME* to the value *VAL* when making + HTTP requests (for example, when a URL is given on the + command line, or when resources used in a document must be + downloaded). + Options affecting specific writers ---------------------------------- @@ -639,19 +772,22 @@ Options affecting specific writers : 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 + images, and videos. Implies `--standalone`. The resulting file should be + "self-contained," in the sense that it needs no external files and no net + access to be displayed properly by a browser. This option works only with + HTML output formats, including `html4`, `html5`, `html+lhs`, `html5+lhs`, + `s5`, `slidy`, `slideous`, `dzslides`, and `revealjs`. Scripts, images, + and stylesheets at absolute URLs will be downloaded; those at relative + URLs will be sought relative to the working directory (if the first source file is local) or relative to the base URL (if the first source - file is remote). 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. + file is remote). Elements with the attribute + `data-external="1"` will be left alone; the documents they + link to will not be incorporated in the document. + Limitation: resources that are loaded dynamically through + JavaScript cannot be incorporated; as a result, + `--self-contained` does not work with `--mathjax`, and some + advanced features (e.g. zoom or speaker notes) may not work + in an offline "self-contained" `reveal.js` slide show. `--html-q-tags` @@ -659,8 +795,8 @@ Options affecting specific writers `--ascii` -: Use only ASCII characters in output. Currently supported only - for HTML output (which uses numerical entities instead of +: Use only ASCII characters in output. Currently supported only for + HTML and DocBook output (which uses numerical entities instead of UTF-8 when this option is selected). `--reference-links` @@ -681,10 +817,7 @@ Options affecting specific writers : 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` - -: Deprecated synonym for `--top-level-division=chapter`. + (Note: for `gfm` output, ATX headers are always used.) `--top-level-division=[default|section|chapter|part]` @@ -717,22 +850,6 @@ Options affecting specific writers 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 @@ -748,14 +865,16 @@ Options affecting specific writers 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]. + subheads within a slide. Note that content that is + not contained under slide-level headers will not appear in + the slide show. The default is to set the slide level based + on the contents of the document; see [Structuring the slide + show]. `--section-divs` -: Wrap sections in `<div>` tags (or `<section>` tags in HTML5), - and attach identifiers to the enclosing `<div>` (or `<section>`) +: Wrap sections in `<section>` tags (or `<div>` tags for `html4`), + and attach identifiers to the enclosing `<section>` (or `<div>`) rather than the header itself. See [Header identifiers], below. @@ -769,10 +888,10 @@ Options affecting specific writers `--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. +: Specify a prefix to be added to all identifiers and internal links + in HTML and DocBook output, and to footnote numbers in Markdown + and Haddock output. This is useful for preventing duplicate + identifiers when generating fragments to be included in other pages. `-T` *STRING*, `--title-prefix=`*STRING* @@ -786,59 +905,87 @@ Options affecting specific writers : 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. - - To produce a custom `reference.odt`, first get a copy of - the default `reference.odt`: `pandoc - --print-default-data-file reference.odt > - custom-reference.odt`. Then open `custom-reference.docx` in - LibreOffice, modify the styles as you wish, and save the - file. - -`--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. - - To produce a custom `reference.docx`, first get a copy of - the default `reference.docx`: `pandoc - --print-default-data-file reference.docx > - custom-reference.docx`. Then open `custom-reference.docx` - in Word, modify the styles as you wish, and save the file. - For best results, do not make changes to this file other - than modifying the styles used by pandoc: [paragraph] 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 + A stylesheet is required for generating EPUB. If none is + provided using this option (or the `stylesheet` metadata + field), 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. +`--reference-doc=`*FILE* + +: Use the specified file as a style reference in producing a + docx or ODT file. + + Docx + + : For best results, the reference docx should be a modified + version of a docx file produced using pandoc. The contents + of the reference docx are ignored, but its stylesheets and + document properties (including margins, page size, header, + and footer) are used in the new docx. If no reference docx + is specified on the command line, pandoc will look for a + file `reference.docx` in the user data directory (see + `--data-dir`). If this is not found either, sensible + defaults will be used. + + To produce a custom `reference.docx`, first get a copy of + the default `reference.docx`: `pandoc + --print-default-data-file reference.docx > + custom-reference.docx`. Then open `custom-reference.docx` + in Word, modify the styles as you wish, and save the file. + For best results, do not make changes to this file other + than modifying the styles used by pandoc: [paragraph] + Normal, Body Text, First Paragraph, Compact, Title, + Subtitle, Author, Date, Abstract, Bibliography, Heading 1, + Heading 2, Heading 3, Heading 4, Heading 5, Heading 6, + Heading 7, Heading 8, Heading 9, Block Text, Footnote Text, + Definition Term, Definition, Caption, Table Caption, + Image Caption, Figure, Captioned Figure, TOC Heading; + [character] Default Paragraph Font, Body Text Char, + Verbatim Char, Footnote Reference, Hyperlink; [table] + Table. + + ODT + + : For best results, the reference ODT should be a modified + version of an ODT produced using pandoc. The contents of + the reference ODT are ignored, but its stylesheets are used + in the new ODT. If no reference ODT is specified on the + command line, pandoc will look for a file `reference.odt` in + the user data directory (see `--data-dir`). If this is not + found either, sensible defaults will be used. + + To produce a custom `reference.odt`, first get a copy of + the default `reference.odt`: `pandoc + --print-default-data-file reference.odt > + custom-reference.odt`. Then open `custom-reference.odt` in + LibreOffice, modify the styles as you wish, and save the + file. + + PowerPoint + + : Any template included with a recent install of Microsoft + PowerPoint (either with `.pptx` or `.potx` extension) should + work, as will most templates derived from these. + + The specific requirement is that the template should contain + the following four layouts as its first four layouts: + + 1. Title Slide + 2. Title and Content + 3. Section Header + 4. Two Content + + All templates included with a recent version of MS PowerPoint + will fit these criteria. (You can click on `Layout` under the + `Home` menu to check.) + + You can also modify the default `reference.pptx`: first run + `pandoc --print-default-data-file reference.pptx > + custom-reference.pptx`, and then modify + `custom-reference.pptx` in MS PowerPoint (pandoc will use the + first four layout slides, as mentioned above). + `--epub-cover-image=`*FILE* : Use the specified image as the EPUB cover. It is recommended @@ -875,7 +1022,7 @@ Options affecting specific writers 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`): + to your CSS (see `--css`): @font-face { font-family: DejaVuSans; @@ -913,15 +1060,21 @@ Options affecting specific writers documents with few level 1 headers, one might want to use a chapter level of 2 or 3. -`--latex-engine=pdflatex`|`lualatex`|`xelatex` +`--epub-subdirectory=`*DIRNAME* + +: Specify the subdirectory in the OCF container that is to hold + the EPUB-specific contents. The default is `EPUB`. To put + the EPUB contents in the top level, use an empty string. -: Use the specified LaTeX engine when producing PDF output. +`--pdf-engine=pdflatex`|`lualatex`|`xelatex`|`wkhtmltopdf`|`weasyprint`|`prince`|`context`|`pdfroff` + +: Use the specified 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* +`--pdf-engine-opt=`*STRING* -: Use the given string as a command-line argument to the `latex-engine`. +: Use the given string as a command-line argument to the `pdf-engine`. If used multiple times, the arguments are provided with spaces between them. Note that no check for duplicate options is done. @@ -971,55 +1124,37 @@ Citation rendering 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. +The default is to render TeX math as far as possible using Unicode characters. +Formulas are put inside a `span` with `class="math"`, so that they may be styled +differently from the surrounding text if needed. However, this gives acceptable +results only for basic math, usually you will want to use `--mathjax` or another +of the following options. `--mathjax`[`=`*URL*] : Use [MathJax] to display embedded TeX math in HTML output. + TeX math will be put between `\(...\)` (for inline math) + or `\[...\]` (for display math) and wrapped in `<span>` tags + with class `math`. Then the MathJax JavaScript will render it. The *URL* should point to the `MathJax.js` load script. - If a *URL* is not provided, a link to the MathJax CDN will + If a *URL* is not provided, a link to the Cloudflare CDN will be inserted. -`--gladtex` - -: Enclose TeX math in `<eq>` tags in HTML output. These can then - be processed by [gladTeX] to produce links to images of the typeset - formulas. - -`--mimetex`[`=`*URL*] +`--mathml` -: 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`. +: Convert TeX math to [MathML] (in `epub3`, `docbook4`, `docbook5`, `jats`, + `html4` and `html5`). This is the default in `odt` output. Note that + currently only Firefox and Safari (and select e-book readers) natively + support MathML. `--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 CodeCogs will be used. +: Convert TeX formulas to `<img>` tags that link to an external script + that converts formulas to images. The formula will be URL-encoded + and concatenated with the URL provided. For SVG images you can for + example use `--webtex https://latex.codecogs.com/svg.latex?`. + If no URL is specified, the CodeCogs URL generating PNGs + will be used (`https://latex.codecogs.com/png.latex?`). Note: the `--webtex` option will affect Markdown output as well as HTML, which is useful if you're targeting a version of Markdown without native math support. @@ -1027,9 +1162,8 @@ Math rendering in 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 + The *URL* is the base URL for the KaTeX library. If a *URL* is not provided, a link to the KaTeX CDN will be inserted. - Note: [KaTeX] seems to work best with `html5` output. `--katex-stylesheet=`*URL* @@ -1037,6 +1171,48 @@ Math rendering in HTML not specified, a link to the KaTeX CDN will be inserted. Note that this option does not imply `--katex`. +`-m` [*URL*], `--latexmathml`[`=`*URL*] + +: *Deprecated.* + Use the [LaTeXMathML] script to display embedded TeX math in HTML output. + TeX math will be displayed between `$` or `$$` characters and put in + `<span>` tags with class `LaTeX`. The LaTeXMathML JavaScript will then + change it to MathML. Note that currently only Firefox and Safari + (and select e-book readers) natively support MathML. + To insert a link the `LaTeXMathML.js` script, provide a *URL*. + +`--jsmath`[`=`*URL*] + +: *Deprecated.* + Use [jsMath] (the predecessor of MathJax) to display embedded TeX + math in HTML output. TeX math will be put inside `<span>` tags + (for inline math) or `<div>` tags (for display math) with class + `math` and rendered by the jsMath script. The *URL* should point to + the 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. + +`--gladtex` + +: *Deprecated.* + Enclose TeX math in `<eq>` tags in HTML output. The resulting HTML + can then be processed by [gladTeX] to produce images of the typeset + formulas and an HTML file with links to these images. + So, the procedure is: + + pandoc -s --gladtex input.md -o myfile.htex + gladtex -d myfile-images myfile.htex + # produces myfile.html and images in myfile-images + +`--mimetex`[`=`*URL*] + +: *Deprecated.* + Render TeX math using the [mimeTeX] CGI script, which generates an + image for each TeX formula. This should work in all browsers. If + *URL* is not specified, it is assumed that the script is at + `/cgi-bin/mimetex.cgi`. + [MathML]: http://www.w3.org/Math/ [LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/ [jsMath]: http://www.math.union.edu/~dpvc/jsmath/ @@ -1088,10 +1264,11 @@ 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`). + (or the `default.context` template, if you use `-t context`, + or the `default.ms` template, if you use `-t ms`, or the + `default.html5` template, if you use `-t html5`). - `docx` has no template (however, you can use - `--reference-docx` to customize the output). + `--reference-doc` 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 @@ -1107,6 +1284,22 @@ Some variables are set automatically by pandoc. These vary somewhat depending on the output format, but include metadata fields as well as the following: +`sourcefile`, `outputfile` +: source and destination filenames, as given on the command line. + `sourcefile` can also be a list if input comes from multiple files, or empty + if input is from stdin. You can use the following snippet in your template + to distinguish them: + + $if(sourcefile)$ + $for(sourcefile)$ + $sourcefile$ + $endfor$ + $else$ + (stdin) + $endif$ + + Similarly, `outputfile` can be `-` if output goes to the terminal. + `title`, `author`, `date` : allow identification of basic aspects of the document. Included in PDF metadata through LaTeX and ConTeXt. These can be set @@ -1144,7 +1337,8 @@ as the following: : non-null value if `--toc/--table-of-contents` was specified `toc-title` -: title of table of contents (works only with EPUB and docx) +: title of table of contents (works only with EPUB, + opendocument, odt, docx, pptx) `include-before` : contents specified by `-B/--include-before-body` (may have @@ -1158,7 +1352,8 @@ as the following: : body of document `meta-json` -: JSON representation of all of the document's metadata +: JSON representation of all of the document's metadata. Field + values are transformed to the selected output format. [^subtitle]: To make `subtitle` work with other LaTeX document classes, you can add the following to `header-includes`: @@ -1179,21 +1374,12 @@ Language variables 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 + Native pandoc Spans and Divs 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. + that range. In LaTeX output, `babel-otherlangs` and + `polyglossia-otherlangs` variables will be generated + automatically based on the `lang` attributes of Spans + and Divs in the document. `dir` : the base direction of the document, either `rtl` (right-to-left) @@ -1207,7 +1393,7 @@ Language variables [Unicode Bidirectional Algorithm]. When using LaTeX for bidirectional documents, only the `xelatex` engine - is fully supported (use `--latex-engine=xelatex`). + is fully supported (use `--pdf-engine=xelatex`). [BCP 47]: https://tools.ietf.org/html/bcp47 [Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics @@ -1218,9 +1404,15 @@ Variables for slides Variables are available for [producing slide shows with pandoc], including all [reveal.js configuration options]. +`titlegraphic` +: title graphic for Beamer documents + +`logo` +: logo for Beamer documents + `slidy-url` : base URL for Slidy documents (defaults to - `http://www.w3.org/Talks/Tools/Slidy2`) + `https://www.w3.org/Talks/Tools/Slidy2`) `slideous-url` : base URL for Slideous documents (defaults to `slideous`) @@ -1250,13 +1442,10 @@ including all [reveal.js configuration options]. : when true, the `beamerarticle` package is loaded (for producing an article from beamer slides). -`colorlinks` -: add color to link text; automatically enabled if any of `linkcolor`, `citecolor`, - `urlcolor`, or `toccolor` are set (for beamer only). - -`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] (for beamer only). +`aspectratio` +: aspect ratio of slides (for beamer only, `1610` for 16:10, `169` for 16:9, + `149` for 14:9, `141` for 1.41:1, `54` for 5:4, `43` for 4:3 which is the + default, and `32` for 3:2). [reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration @@ -1266,7 +1455,7 @@ Variables for LaTeX LaTeX variables are used when [creating a PDF]. `papersize` -: paper size, e.g. `letter`, `A4` +: paper size, e.g. `letter`, `a4` `fontsize` : font size for body text (e.g. `10pt`, `12pt`) @@ -1325,7 +1514,7 @@ LaTeX variables are used when [creating a PDF]. `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] + uses options allowed by [`xcolor`], including the `dvipsnames`, `svgnames`, and `x11names` lists `links-as-notes` : causes links to be printed as footnotes @@ -1365,12 +1554,20 @@ LaTeX variables are used when [creating a PDF]. `biblatexoptions` : list of options for biblatex. +`natbiboptions` +: list of options for natbib. + +`pagestyle` +: An option for LaTeX's `\pagestyle{}`. The default article class + supports 'plain' (default), 'empty', and 'headings'; headings puts + section titles in the header. + [`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 +[`xcolor`]: https://ctan.org/pkg/xcolor [LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/ [`mathpazo`]: https://ctan.org/pkg/mathpazo [LaTeX font encodings]: https://ctan.org/pkg/encguide @@ -1456,6 +1653,21 @@ Variables for man pages `hyphenate` : if `true` (the default), hyphenation will be used +Variables for ms +---------------- + +`pointsize` +: point size (e.g. `10p`) + +`lineheight` +: line height (e.g. `12p`) + +`fontfamily` +: font family (e.g. `T` or `P`) + +`indent` +: paragraph indent (e.g. `2m`) + Using variables in templates ---------------------------- @@ -1505,8 +1717,292 @@ 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. +Templates may contain comments: anything on a line after `$--` +will be treated as a comment and ignored. + [pandoc-templates]: https://github.com/jgm/pandoc-templates +Extensions +========== + +The behavior of some of the readers and writers can be adjusted by +enabling or disabling various extensions. + +An extension can be enabled by adding `+EXTENSION` +to the format name and disabled by adding `-EXTENSION`. For example, +`--from markdown_strict+footnotes` is strict Markdown with footnotes +enabled, while `--from markdown-footnotes-pipe_tables` is pandoc's +Markdown without footnotes or pipe tables. + +The markdown reader and writer make by far the most use of extensions. +Extensions only used by them are therefore covered in the +section [Pandoc's Markdown] below (See [Markdown variants] for +`commonmark` and `gfm`.) In the following, extensions that also work +for other formats are covered. + +Typography +---------- + +#### Extension: `smart` #### + +Interpret straight quotes as curly quotes, `---` as em-dashes, +`--` as en-dashes, and `...` as ellipses. Nonbreaking spaces are +inserted after certain abbreviations, such as "Mr." + +This extension can be enabled/disabled for the following formats: + +input formats +: `markdown`, `commonmark`, `latex`, `mediawiki`, `org`, `rst`, `twiki` + +output formats +: `markdown`, `latex`, `context`, `rst` + +enabled by default in +: `markdown`, `latex`, `context` (both input and output) + +Note: If you are *writing* Markdown, then the `smart` extension +has the reverse effect: what would have been curly quotes comes +out straight. + +In LaTeX, `smart` means to use the standard TeX ligatures +for quotation marks (` `` ` and ` '' ` for double quotes, +`` ` `` and `` ' `` for single quotes) and dashes (`--` for +en-dash and `---` for em-dash). If `smart` is disabled, +then in reading LaTeX pandoc will parse these characters +literally. In writing LaTeX, enabling `smart` tells pandoc +to use the ligatures when possible; if `smart` is disabled +pandoc will use unicode quotation mark and dash characters. + +Headers and sections +-------------------- + +#### Extension: `auto_identifiers` #### + +A header without an explicitly specified identifier will be +automatically assigned a unique identifier based on the header text. + +This extension can be enabled/disabled for the following formats: + +input formats +: `markdown`, `latex`, `rst`, `mediawiki`, `textile` + +output formats +: `markdown`, `muse` + +enabled by default in +: `markdown`, `muse` + +The algorithm used to derive the identifier from the header text is: + + - 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 `section` (or a `div`, if `html4` was specified), +and the identifier will be attached to the enclosing `<section>` +(or `<div>`) tag rather than the header itself. This allows entire +sections to be manipulated using JavaScript or treated differently in +CSS. + +#### Extension: `ascii_identifiers` #### + +Causes the identifiers produced by `auto_identifiers` to be pure ASCII. +Accents are stripped off of accented Latin letters, and non-Latin +letters are omitted. + +Math Input +---------- + +The extensions [`tex_math_dollars`](#extension-tex_math_dollars), +[`tex_math_single_backslash`](#extension-tex_math_single_backslash), and +[`tex_math_double_backslash`](#extension-tex_math_double_backslash) +are described in the section about Pandoc's Markdown. + +However, they can also be used with HTML input. This is handy for +reading web pages formatted using MathJax, for example. + +Raw HTML/TeX +------------ + +The following extensions (especially how they affect Markdown +input/output) are also described in more detail in their respective +sections of [Pandoc's Markdown]. + +#### [Extension: `raw_html`] {#raw_html} + +When converting from HTML, parse elements to raw HTML which are not +representable in pandoc's AST. +By default, this is disabled for HTML input. + +#### [Extension: `raw_tex`] {#raw_tex} + +Allows raw LaTeX, TeX, and ConTeXt to be included in a document. + +This extension can be enabled/disabled for the following formats +(in addition to `markdown`): + +input formats +: `latex`, `org`, `textile` + +output formats +: `textile` + +#### [Extension: `native_divs`] {#native_divs} + +This extension is enabled by default for HTML input. This means that +`div`s are parsed to pandoc native elements. (Alternatively, you +can parse them to raw HTML using `-f html-native_divs+raw_html`.) + +When converting HTML to Markdown, for example, you may want to drop all +`div`s and `span`s: + + pandoc -f html-native_divs-native_spans -t markdown + +#### [Extension: `native_spans`] {#native_spans} + +Analogous to `native_divs` above. + + +Literate Haskell support +------------------------ + +#### Extension: `literate_haskell` #### + +Treat the document as literate Haskell source. + +This extension can be enabled/disabled for the following formats: + +input formats +: `markdown`, `rst`, `latex` + +output formats +: `markdown`, `rst`, `latex`, `html` + +If you append `+lhs` (or `+literate_haskell`) to one of the formats +above, pandoc will treat the document as literate Haskell source. +This means that + + - In Markdown input, "bird track" sections will be parsed as Haskell + code rather than block quotations. Text between `\begin{code}` + and `\end{code}` will also be treated as Haskell code. For + ATX-style headers the character '=' will be used instead of '#'. + + - In Markdown output, code blocks with classes `haskell` and `literate` + will be rendered using bird tracks, and block quotations will be + indented one space, so they will not be treated as Haskell code. + In addition, headers will be rendered setext-style (with underlines) + rather than ATX-style (with '#' characters). (This is because ghc + treats '#' characters in column 1 as introducing line numbers.) + + - In restructured text input, "bird track" sections will be parsed + as Haskell code. + + - In restructured text output, code blocks with class `haskell` will + be rendered using bird tracks. + + - In LaTeX input, text in `code` environments will be parsed as + Haskell code. + + - In LaTeX output, code blocks with class `haskell` will be rendered + inside `code` environments. + + - In HTML output, code blocks with class `haskell` will be rendered + with class `literatehaskell` and bird tracks. + +Examples: + + pandoc -f markdown+lhs -t html + +reads literate Haskell source formatted with Markdown conventions and writes +ordinary HTML (without bird tracks). + + pandoc -f markdown+lhs -t html+lhs + +writes HTML with the Haskell code in bird tracks, so it can be copied +and pasted as literate Haskell source. + +Note that GHC expects the bird tracks in the first column, so indentend literate +code blocks (e.g. inside an itemized environment) will not be picked up by the +Haskell compiler. + +Other extensions +---------------- + +#### Extension: `empty_paragraphs` #### + +Allows empty paragraphs. By default empty paragraphs are +omitted. + +This extension can be enabled/disabled for the following formats: + +input formats +: `docx`, `html` + +output formats +: `markdown`, `docx`, `odt`, `opendocument`, `html` + +#### Extension: `styles` #### {#ext-styles} + +Read all docx styles as divs (for paragraph styles) and spans (for +character styles) regardless of whether pandoc understands the meaning +of these styles. This can be used with [docx custom +styles](#custom-styles-in-docx). Disabled by default. + +input formats +: `docx` + +#### Extension: `amuse` #### + +In the `muse` input format, this enables Text::Amuse +extensions to Emacs Muse markup. + +#### Extension: `citations` {#org-citations} + +Some aspects of [Pandoc's Markdown citation syntax](#citations) are also accepted +in `org` input. + +#### Extension: `ntb` #### + +In the `context` output format this enables the use of [Natural Tables +(TABLE)](http://wiki.contextgarden.net/TABLE) instead of the default +[Extreme Tables (xtables)](http://wiki.contextgarden.net/xtables). +Natural tables allow more fine-grained global customization but come +at a performance penalty compared to extreme tables. + + Pandoc's Markdown ================= @@ -1514,11 +2010,9 @@ 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. +of `markdown`. Extensions can be enabled or disabled to specify the +behavior more granularly. They are described in the following. See also +[Extensions] above, for extensions that work also on other formats. Philosophy ---------- @@ -1601,9 +2095,17 @@ wrapping). Consider, for example: I like several of their flavors of ice cream: #22, for example, and #5. +#### Extension: `space_in_atx_header` #### + +Many Markdown implementations do not require a space between the +opening `#`s of an ATX header and the header text, so that +`#5 bolt` and `#hashtag` count as headers. With this extension, +pandoc does require the space. ### Header identifiers ### +See also the [`auto_identifiers` extension](#extension-auto_identifiers) above. + #### Extension: `header_attributes` #### Headers can be assigned attributes using this syntax at the end @@ -1640,55 +2142,6 @@ 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 `<div>` -(or `<section>`) 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. @@ -1846,11 +2299,11 @@ this syntax: 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, type -`pandoc --list-highlight-languages`.) Otherwise, the code block above will -appear as follows: +that uses this information are HTML, LaTeX, Docx, Ms, and PowerPoint. If +highlighting is supported for your output format and language, then the code +block above will appear highlighted, with numbered lines. (To see which +languages are supported, type `pandoc --list-highlight-languages`.) Otherwise, +the code block above will appear as follows: <pre id="mycode" class="haskell numberLines" startFrom="100"> <code> @@ -1858,6 +2311,12 @@ appear as follows: </code> </pre> +The `numberLines` (or `number-lines`) class will cause the lines +of the code block to be numbered, starting with `1` or the value +of the `startFrom` attribute. The `lineAnchors` (or +`line-anchors`) class will cause the lines to be clickable +anchors in HTML output. + A shortcut form can also be used for specifying the language of the code block: @@ -1949,12 +2408,12 @@ But Markdown also allows a "lazy" format: list item. * and my second. -### The four-space rule ### +### Block content in list items ### 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: +and indented to line up with the first non-space content after +the list marker. * First paragraph. @@ -1965,19 +2424,29 @@ paragraph is aligned with the rest: { code } +Exception: if the list marker is followed by an indented code +block, which must begin 5 spaces after the list marker, then +subsequent paragraphs must begin two columns after the last +character of the list marker: + + * code + + continuation paragraph + List items may include other lists. In this case the preceding blank -line is optional. The nested list must be indented four spaces or -one tab: +line is optional. The nested list must be indented to line up with +the first non-space character after the list marker of the +containing list item. * fruits - + apples - - macintosh - - red delicious - + pears - + peaches + + apples + - macintosh + - red delicious + + pears + + peaches * vegetables - + broccoli - + chard + + 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 @@ -1992,21 +2461,6 @@ other blocks in a list item, the first line of each must be indented. 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 @@ -2172,6 +2626,12 @@ document: The label can be any string of alphanumeric characters, underscores, or hyphens. +Note: continuation paragraphs in example lists must always +be indented four spaces, regardless of the length of the +list marker. That is, example lists always behave as if the +`four_space_rule` extension is set. This is because example +labels tend to be long, and indenting content to the +first non-space character after the label would be awkward. ### Compact and loose lists ### @@ -2180,9 +2640,9 @@ cases" involving lists. Consider this source: + First + Second: - - Fee - - Fie - - Foe + - Fee + - Fie + - Foe + Third @@ -2394,6 +2854,18 @@ For headerless tables, the colons go on the top line instead: | Right | Left | Centered | +---------------+---------------+--------------------+ +##### Grid Table Limitations ##### + +Pandoc does not support grid tables with row spans or column spans. +This means that neither variable numbers of columns across rows nor +variable numbers of rows across columns are supported by Pandoc. +All grid tables must have the same number of columns in each row, +and the same number of rows in each column. For example, the +Docutils [sample grid tables] will not render as expected with +Pandoc. + +[sample grid tables]: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables + #### Extension: `pipe_tables` #### @@ -2428,7 +2900,10 @@ 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. +lines. (In this case, the table will take up the full text +width.) If no lines are wider than column width, then +cell contents will not be wrapped, and the cells will be sized +to their contents. Note: pandoc also recognizes pipe tables of the following form, as can be produced by Emacs' orgtbl-mode: @@ -2557,7 +3032,7 @@ 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: +when the field contains blank lines or block-level formatting: --- title: 'This is the title: it contains a colon' @@ -2604,6 +3079,17 @@ template: $endif$ $endfor$ +Raw content to include in the document's header may be specified +using `header-includes`; however, it is important to mark up +this content as raw code for a particular output format, using +the [`raw_attribute` extension](#extension-raw_attribute)), or it +will be interpreted as markdown. For example: + + header-includes: + - ```{=latex} + \let\oldsection\section + \renewcommand{\section}[1]{\clearpage\oldsection{#1}} + ``` Backslash escapes ----------------- @@ -2644,20 +3130,6 @@ 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 ----------------- @@ -2746,16 +3218,20 @@ Attributes can be attached to verbatim text, just as with ### Small caps ### -To write small caps, you can use an HTML span tag: +To write small caps, use the `smallcaps` class: - <span style="font-variant:small-caps;">Small caps</span> + [Small caps]{.smallcaps} -(The semicolon is optional and there may be space after the -colon.) This will work in all output formats that support small caps. +Or, without the `bracketed_spans` extension: -Alternatively, you can also use the new `bracketed_spans` syntax: + <span class="smallcaps">Small caps</span> + +For compatibility with other Markdown flavors, CSS is also supported: + + <span style="font-variant:small-caps;">Small caps</span> + +This will work in all output formats that support small caps. - [Small caps]{style="font-variant:small-caps;"} Math ---- @@ -2794,10 +3270,13 @@ MediaWiki, DokuWiki Textile ~ It will be rendered inside `<span class="math">` tags. -RTF, OpenDocument, ODT +RTF, OpenDocument ~ It will be rendered, if possible, using Unicode characters, and will otherwise appear verbatim. +ODT + ~ It will be rendered, if possible, using MathML. + DocBook ~ If the `--mathml` flag is used, it will be rendered using MathML in an `inlineequation` or `informalequation` tag. Otherwise it @@ -2813,51 +3292,8 @@ FictionBook2 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 `<span>` 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 - `<span>` tags (for inline math) or `<div>` 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 `<eq>` 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 `<img>` 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 CodeCogs - will be used (`https://latex.codecogs.com/png.latex?`). - - 7. If the `--mathjax` option is used, TeX math will be displayed - between `\(...\)` (for inline math) or `\[...\]` (for display - math) and put in `<span>` tags with class `math`. - The [MathJax] script will be used to render it as formulas. + command-line options selected. Therefore see [Math rendering in HTML] + above. [interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math @@ -2928,9 +3364,6 @@ For the most part this should give the same output as `raw_html`, but it makes it easier to write pandoc filters to manipulate groups of inlines. -Raw TeX -------- - #### Extension: `raw_tex` #### In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be @@ -2955,23 +3388,58 @@ LaTeX, not as Markdown. Inline LaTeX is ignored in output formats other than Markdown, LaTeX, Emacs Org mode, and ConTeXt. +### Generic raw attribute ### + +#### Extension: `raw_attribute` #### + +Inline spans and fenced code blocks with a special +kind of attribute will be parsed as raw content with the +designated format. For example, the following produces a raw +groff `ms` block: + + ```{=ms} + .MYMACRO + blah blah + ``` +And the following produces a raw `html` inline element: + + This is `<a>html</a>`{=html} + +The format name should match the target format name (see +`-t/--to`, above, for a list, or use `pandoc +--list-output-formats`). + +This extension presupposes that the relevant kind of +inline code or fenced code block is enabled. Thus, for +example, to use a raw attribute with a backtick code block, +`backtick_code_blocks` must be enabled. + +The raw attribute cannot be combined with regular attributes. + LaTeX macros ------------ #### Extension: `latex_macros` #### -For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and -`\renewcommand` definitions and apply the resulting macros to all LaTeX -math. So, for example, the following will work in all output formats, -not just LaTeX: +For output formats other than LaTeX, pandoc will parse LaTeX +macro definitions and apply the resulting macros to all LaTeX +math and raw LaTeX. So, for example, the following will work in +all output formats, not just LaTeX: \newcommand{\tuple}[1]{\langle #1 \rangle} $\tuple{a, b, c}$ -In LaTeX output, the `\newcommand` definition will simply be passed -unchanged to the output. +Note that LaTeX macros will not be applied if they occur +inside inside a raw span or block marked with the +[`raw_attribute` extension](#extension-raw_attribute). +When `latex_macros` is disabled, the raw LaTeX and math will +not have macros applied. This is usually a better approach when +you are targeting LaTeX or PDF. + +Whether or not `latex_macros` is enabled, the macro definitions +will still be passed through as raw LaTeX. Links ----- @@ -3010,7 +3478,8 @@ definition, which may occur elsewhere in the document (either before or after the link). The link consists of link text in square brackets, followed by a label in -square brackets. (There can be space between the two.) The link definition +square brackets. (There cannot be space between the two unless the +`spaced_reference_links` extension is enabled.) The link definition consists of the bracketed label, followed by a colon and a space, followed by the URL, and optionally (after a space) a link title either in quotes or in parentheses. The label must not be parseable as a citation (assuming @@ -3095,23 +3564,26 @@ The link text will be used as the image's alt text: #### Extension: `implicit_figures` #### -An image occurring by itself in a paragraph will be rendered as -a figure with a caption.[^5] (In LaTeX, a figure environment will be -used; in HTML, the image will be placed in a `div` with class -`figure`, together with a caption in a `p` with class `caption`.) -The image's alt text will be used as the caption. +An image with nonempty alt text, occurring by itself in a +paragraph, will be rendered as a figure with a caption. The +image's alt text will be used as the caption.  -[^5]: This feature is not yet implemented for RTF, OpenDocument, or - ODT. In those formats, you'll just get an image in a paragraph by - itself, with no caption. +How this is rendered depends on the output format. Some output +formats (e.g. RTF) do not yet support figures. In those +formats, you'll just get an image in a paragraph by itself, with +no caption. If you just want a regular inline image, just make sure it is not the only thing in the paragraph. One way to do this is to insert a nonbreaking space after the image: - \ + \ + +Note that in reveal.js slide shows, an image in a paragraph +by itself that has the `stretch` class will fill the screen, +and the caption and figure tags will be omitted. #### Extension: `link_attributes` #### @@ -3156,13 +3628,59 @@ For example: is to look at the image resolution and the dpi metadata embedded in the image file. -Spans ------ +Divs and Spans +-------------- + +Using the `native_divs` and `native_spans` extensions +(see [above][Extension: `native_divs`]), HTML syntax can +be used as part of markdown to create native `Div` and `Span` +elements in the pandoc AST (as opposed to raw HTML). +However, there is also nicer syntax available: + +#### Extension: `fenced_divs` #### + +Allow special fenced syntax for native `Div` blocks. A Div +starts with a fence containing at least three consecutive +colons plus some attributes. The attributes may optionally +be followed by another string of consecutive colons. +The attribute syntax is exactly as in fenced code blocks (see +[Extension: `fenced_code_attributes`]). As with fenced +code blocks, one can use either attributes in curly braces +or a single unbraced word, which will be treated as a class +name. The Div ends with another line containing a string of at +least three consecutive colons. The fenced Div should be +separated by blank lines from preceding and following blocks. + +Example: + + ::::: {#special .sidebar} + Here is a paragraph. + + And another. + ::::: + +Fenced divs can be nested. Opening fences are distinguished +because they *must* have attributes: + + ::: Warning :::::: + This is a warning. + + ::: Danger + This is a warning within a warning. + ::: + :::::::::::::::::: + +Fences without attributes are always closing fences. Unlike +with fenced code blocks, the number of colons in the closing +fence need not match the number in the opening fence. However, +it can be helpful for visual clarity to use fences of different +lengths to distinguish nested divs from their parents. + #### Extension: `bracketed_spans` #### A bracketed sequence of inlines, as one would use to begin -a link, will be treated as a span with attributes if it is +a link, will be treated as a `Span` with attributes if it is followed immediately by attributes: [This is *some text*]{.class key="val"} @@ -3214,7 +3732,6 @@ they cannot contain multiple paragraphs). The syntax is as follows: Inline and regular footnotes may be mixed freely. - Citations --------- @@ -3415,6 +3932,13 @@ in pandoc, but may be enabled by adding `+EXTENSION` to the format name, where `EXTENSION` is the name of the extension. Thus, for example, `markdown+hard_line_breaks` is Markdown with hard line breaks. +#### Extension: `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 only has an effect if `smart` is enabled. It is +selected automatically for `textile` input. + #### Extension: `angle_brackets_escapable` #### Allow `<` and `>` to be backslash-escaped, as they can be in @@ -3426,6 +3950,19 @@ implied by pandoc's default `all_symbols_escapable`. Allow a list to occur right after a paragraph, with no intervening blank space. +#### Extension: `four_space_rule` #### + +Selects the pandoc <= 2.0 behavior for parsing lists, so that +four spaces indent are needed for list item continuation +paragraphs. + +#### Extension: `spaced_reference_links` #### + +Allow whitespace between the two components of a reference link, +for example, + + [foo] [bar]. + #### Extension: `hard_line_breaks` #### Causes all newlines within a paragraph to be interpreted as hard line @@ -3446,7 +3983,7 @@ between two East Asian wide characters. This is a better choice than `ignore_line_breaks` for texts that include a mix of East Asian wide characters and other characters. -##### Extension: `emoji` #### +#### Extension: `emoji` #### Parses textual emojis like `:smile:` as Unicode emoticons. @@ -3499,12 +4036,6 @@ simply skipped (as opposed to being parsed as paragraphs). Makes all absolute URIs into links, even when not surrounded by pointy braces `<...>`. -#### Extension: `ascii_identifiers` #### - -Causes the identifiers produced by `auto_identifiers` to be pure ASCII. -Accents are stripped off of accented Latin letters, and non-Latin -letters are omitted. - #### Extension: `mmd_link_attributes` #### Parses multimarkdown style key-value attributes on link @@ -3558,13 +4089,14 @@ variants are supported: : `footnotes`, `pipe_tables`, `raw_html`, `markdown_attribute`, `fenced_code_blocks`, `definition_lists`, `intraword_underscores`, `header_attributes`, `link_attributes`, `abbreviations`, - `shortcut_reference_links`. + `shortcut_reference_links`, `spaced_reference_links`. -`markdown_github` (GitHub-Flavored Markdown) -: `pipe_tables`, `raw_html`, `fenced_code_blocks`, `auto_identifiers`, +`markdown_github` (deprecated GitHub-Flavored Markdown) +: `pipe_tables`, `raw_html`, `fenced_code_blocks`, `gfm_auto_identifiers`, `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`, - `intraword_underscores`, `strikeout`, `hard_line_breaks`, `emoji`, - `shortcut_reference_links`, `angle_brackets_escapable`. + `space_in_atx_header`, `intraword_underscores`, `strikeout`, + `emoji`, `shortcut_reference_links`, `angle_brackets_escapable`, + `lists_without_preceding_blankline`. `markdown_mmd` (MultiMarkdown) : `pipe_tables`, `raw_html`, `markdown_attribute`, `mmd_link_attributes`, @@ -3572,24 +4104,28 @@ variants are supported: `mmd_title_block`, `footnotes`, `definition_lists`, `all_symbols_escapable`, `implicit_header_references`, `auto_identifiers`, `mmd_header_identifiers`, - `shortcut_reference_links`. + `shortcut_reference_links`, `implicit_figures`, + `superscript`, `subscript`, `backtick_code_blocks`, + `spaced_reference_links`, `raw_attribute`. `markdown_strict` (Markdown.pl) -: `raw_html` - -Extensions with formats other than Markdown -------------------------------------------- +: `raw_html`, `shortcut_reference_links`, + `spaced_reference_links`. -Some of the extensions discussed above can be used with formats -other than Markdown: +We also support `commonmark` and `gfm` (GitHub-Flavored Markdown, +which is implemented as a set of extensions on `commonmark`). -* `auto_identifiers` can be used with `latex`, `rst`, `mediawiki`, - and `textile` input (and is used by default). +Note, however, that `commonmark` and `gfm` have limited support +for extensions. Only those listed below (and `smart` and +`raw_tex`) will work. The extensions can, however, all be +individually disabled. +Also, `raw_tex` only affects `gfm` output, not input. -* `tex_math_dollars`, `tex_math_single_backslash`, and - `tex_math_double_backslash` can be used with `html` input. - (This is handy for reading web pages formatted using MathJax, - for example.) +`gfm` (GitHub-Flavored Markdown) +: `pipe_tables`, `raw_html`, `fenced_code_blocks`, `auto_identifiers`, + `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`, + `intraword_underscores`, `strikeout`, `hard_line_breaks`, `emoji`, + `shortcut_reference_links`, `angle_brackets_escapable`. Producing slide shows with pandoc ================================= @@ -3597,7 +4133,8 @@ Producing slide shows with pandoc You can use pandoc to produce an HTML + JavaScript slide presentation that can be viewed via a web browser. There are five ways to do this, using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js]. -You can also produce a PDF slide show using LaTeX [`beamer`]. +You can also produce a PDF slide show using LaTeX [`beamer`], or +slides shows in Microsoft [PowerPoint] format. Here's the Markdown source for a simple slide show, `habits.txt`: @@ -3659,6 +4196,10 @@ To produce a PDF slide show using beamer, type Note that a reveal.js slide show can also be converted to a PDF by printing it to a file from the browser. +To produce a Powerpoint slide show, type + + pandoc habits.txt -o habits.pptx + Structuring the slide show -------------------------- @@ -3683,6 +4224,9 @@ rules: "title slides," which just contain the section title and help to break the slide show into sections. + * Content *above* the slide level will not appear in the slide + show. + * A title page is constructed automatically from the document's title block, if present. (In the case of beamer, this can be disabled by commenting out some lines in the default template.) @@ -3704,14 +4248,38 @@ Incremental lists By default, these writers produce lists that display "all at once." If you want your lists to display incrementally (one item at a time), use the `-i` option. If you want a particular list to depart from the -default (that is, to display incrementally without the `-i` option and -all at once with the `-i` option), put it in a block quote: +default, put it in a `div` block with class `incremental` or +`nonincremental`. So, for example, using the `fenced div` syntax, the +following would be incremental regardless of the document default: + + ::: incremental + + - Eat spaghetti + - Drink wine + + ::: + +or + + ::: nonincremental + + - Eat spaghetti + - Drink wine + + ::: + +While using `incremental` and `nonincremental` divs are the +recommended method of setting incremental lists on a per-case basis, +an older method is also supported: putting lists inside a blockquote +will depart from the document default (that is, it will display +incrementally without the `-i` option and all at once with the `-i` +option): > - Eat spaghetti > - Drink wine -In this way incremental and nonincremental lists can be mixed in -a single document. +Both methods allow incremental and nonincremental lists to be mixed +in a single document. Inserting pauses ---------------- @@ -3766,21 +4334,41 @@ bibliographies: Speaker notes ------------- -reveal.js has good support for speaker notes. You can add notes to your -Markdown document thus: +Speaker notes are supported in reveal.js and PowerPoint (pptx) +output. You can add notes to your Markdown document thus: + + ::: notes - <div class="notes"> This is my note. - It can contain Markdown - like this list - </div> + ::: + +To show the notes window in reveal.js, press `s` while viewing the +presentation. Speaker notes in PowerPoint will be available, as usual, +in handouts and presenter view. -To show the notes window, press `s` while viewing the presentation. Notes are not yet supported for other slide formats, but the notes will not appear on the slides themselves. +Columns +------- + +To put material in side by side columns, you can use a native +div container with class `columns`, containing two or more div +containers with class `column` and a `width` attribute: + + :::::::::::::: {.columns} + ::: {.column width="40%"} + contents... + ::: + ::: {.column width="60%"} + contents... + ::: + :::::::::::::: + Frame attributes in beamer -------------------------- @@ -3822,6 +4410,8 @@ block][Extension: `yaml_metadata_block`]. Here is an example: text: doi:10.234234.234/33 publisher: My Press rights: © 2007 John Smith, CC BY-NC + ibooks: + version: 1.3.4 ... The following fields are recognized: @@ -3887,6 +4477,16 @@ The following fields are recognized: ~ Either `ltr` or `rtl`. Specifies the `page-progression-direction` attribute for the [`spine` element]. +`ibooks` + ~ iBooks-specific metadata, with the following fields: + + - `version`: (string) + - `specified-fonts`: `true`|`false` (default `false`) + - `ipad-orientation-lock`: `portrait-only`|`landscape-only` + - `iphone-orientation-lock`: `portrait-only`|`landscape-only` + - `binding`: `true`|`false` (default `true`) + - `scroll-axis`: `vertical`|`horizontal`|`default` + [MARC relators]: http://loc.gov/marc/relators/relaterm.html [`spine` element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem @@ -3905,74 +4505,78 @@ with the `src` attribute. For example: </source> </audio> -Literate Haskell support -======================== +Syntax highlighting +=================== -If you append `+lhs` (or `+literate_haskell`) to an appropriate input or output -format (`markdown`, `markdown_strict`, `rst`, or `latex` for input or output; -`beamer`, `html` or `html5` for output only), pandoc will treat the document as -literate Haskell source. This means that +Pandoc will automatically highlight syntax in [fenced code blocks] that +are marked with a language name. The Haskell library [skylighting] is +used for highlighting, which works in HTML, Docx, Ms, and LaTeX/PDF output. +To see a list of language names that pandoc will recognize, type +`pandoc --list-highlight-languages`. - - In Markdown input, "bird track" sections will be parsed as Haskell - code rather than block quotations. Text between `\begin{code}` - and `\end{code}` will also be treated as Haskell code. For - ATX-style headers the character '=' will be used instead of '#'. +The color scheme can be selected using the `--highlight-style` option. +The default color scheme is `pygments`, which imitates the default color +scheme used by the Python library pygments (though pygments is not actually +used to do the highlighting). To see a list of highlight styles, +type `pandoc --list-highlight-styles`. - - In Markdown output, code blocks with classes `haskell` and `literate` - will be rendered using bird tracks, and block quotations will be - indented one space, so they will not be treated as Haskell code. - In addition, headers will be rendered setext-style (with underlines) - rather than ATX-style (with '#' characters). (This is because ghc - treats '#' characters in column 1 as introducing line numbers.) +To disable highlighting, use the `--no-highlight` option. - - In restructured text input, "bird track" sections will be parsed - as Haskell code. +[skylighting]: https://github.com/jgm/skylighting - - In restructured text output, code blocks with class `haskell` will - be rendered using bird tracks. +Custom Styles in Docx +===================== - - In LaTeX input, text in `code` environments will be parsed as - Haskell code. +Input +----- - - In LaTeX output, code blocks with class `haskell` will be rendered - inside `code` environments. +The docx reader, by default, only reads those styles that it can +convert into pandoc elements, either by direct conversion or +interpreting the derivation of the input document's styles. - - In HTML output, code blocks with class `haskell` will be rendered - with class `literatehaskell` and bird tracks. +By enabling the [`styles` extension](#ext-styles) in the docx reader +(`-f docx+styles`), you can produce output that maintains the styles +of the input document, using the `custom-style` class. Paragraph +styles are interpreted as divs, while character styles are interpreted +as spans. -Examples: +For example, using the `custom-style-reference.docx` file in the test +directory, we have the following different outputs: - pandoc -f markdown+lhs -t html +Without the `+styles` extension: -reads literate Haskell source formatted with Markdown conventions and writes -ordinary HTML (without bird tracks). + $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown + This is some text. - pandoc -f markdown+lhs -t html+lhs + This is text with an *emphasized* text style. And this is text with a + **strengthened** text style. -writes HTML with the Haskell code in bird tracks, so it can be copied -and pasted as literate Haskell source. + > Here is a styled paragraph that inherits from Block Text. -Syntax highlighting -=================== +And with the extension: -Pandoc will automatically highlight syntax in [fenced code blocks] that -are marked with a language name. The Haskell library [highlighting-kate] is -used for highlighting, which works in HTML, Docx, and LaTeX/PDF output. -To see a list of language names that pandoc will recognize, type -`pandoc --list-highlight-languages`. + $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown -The color scheme can be selected using the `--highlight-style` option. -The default color scheme is `pygments`, which imitates the default color -scheme used by the Python library pygments (though pygments is not actually -used to do the highlighting). To see a list of highlight styles, -type `pandoc --list-highlight-styles`. + ::: {custom-style="FirstParagraph"} + This is some text. + ::: -To disable highlighting, use the `--no-highlight` option. + ::: {custom-style="BodyText"} + This is text with an [emphasized]{custom-style="Emphatic"} text style. + And this is text with a [strengthened]{custom-style="Strengthened"} + text style. + ::: -[highlighting-kate]: https://github.com/jgm/highlighting-kate + ::: {custom-style="MyBlockStyle"} + > Here is a styled paragraph that inherits from Block Text. + ::: -Custom Styles in Docx Output -============================ +With these custom styles, you can use your input document as a +reference-doc while creating docx output (see below), and maintain the +same styles in your input and output files. + +Output +------ By default, pandoc's docx output applies a predefined set of styles for blocks such as paragraphs and block quotes, and uses largely default @@ -3984,19 +4588,19 @@ using `div`s and `span`s, respectively. If you define a `div` or `span` with the attribute `custom-style`, pandoc will apply your specified style to the contained elements. So, -for example, +for example using the `bracketed_spans` syntax, - <span custom-style="Emphatically">Get out,</span> he said. + [Get out]{custom-style="Emphatically"}, he said. -would produce a docx file with "Get out," styled with character -style `Emphatically`. Similarly, +would produce a docx file with "Get out" styled with character +style `Emphatically`. Similarly, using the `fenced_divs` syntax, Dickinson starts the poem simply: - <div custom-style="Poetry"> + ::: {custom-style="Poetry"} | A Bird came down the Walk--- | He did not know I saw--- - </div> + ::: would style the two contained lines with the `Poetry` paragraph style. @@ -4012,7 +4616,7 @@ want all italics to be transformed to the `Emphasis` character style transform all italicized inlines to inlines within an `Emphasis` custom-style `span`. -[pandoc filters]: http://pandoc.org/scripting.html +[pandoc filters]: http://pandoc.org/filters.html Custom writers ============== @@ -4036,182 +4640,10 @@ which you can modify according to your needs, do Authors ======= -© 2006-2016 John MacFarlane (jgm@berkeley.edu). Released under the -[GPL], version 2 or greater. This software carries no warranty of -any kind. (See COPYRIGHT for full copyright and warranty notices.) - -Contributors include -Arata Mizuki, -Aaron Wolen, -Albert Krewinkel, -Alex Ivkin, -Alex Vong, -Alexander Kondratskiy, -Alexander Sulfrian, -Alexander V Vershilov, -Alfred Wechselberger, -Andreas Lööw, -Andrew Dunning, -Antoine Latter, -Arata Mizuki, -Arlo O'Keeffe, -Artyom Kazak, -B. Scott Michel, -Ben Gamari, -Beni Cherniavsky-Paskin, -Benoit Schweblin, -Bjorn Buckwalter, -Bradley Kuhn, -Brent Yorgey, -Bryan O'Sullivan, -Caleb McDaniel, -Calvin Beck, -Carlos Sosa, -Chris Black, -Christian Conkle, -Christoffer Ackelman, -Christoffer Sawicki, -Clare Macrae, -Clint Adams, -Conal Elliott, -Craig S. Bosma, -Daniel Bergey, -Daniel T. Staal, -Daniele D'Orazio, -David Lazar, -David Röthlisberger, -Denis Laxalde, -Douglas Calvert, -Emanuel Evans, -Emily Eisenberg, -Eric Kow, -Eric Seidel, -Felix Yan, -Florian Eitel, -François Gannaz, -Freiric Barral, -Freirich Raabe, -Frerich Raabe, -Fyodor Sheremetyev, -Gabor Pali, -Gavin Beatty, -Gottfried Haider, -Greg Maslov, -Greg Rundlett, -Grégory Bataille, -Gwern Branwen, -Hans-Peter Deifel, -Henrik Tramberend, -Henry de Valence, -Hubert Plociniczak, -Ilya V. Portnov, -Ivo Clarysse, -J. Lewis Muir, -Jaime Marquínez Ferrándiz, -Jakob Voß, -James Aspnes, -Jamie F. Olson, -Jan Larres, -Jan Schulz, -Jason Ronallo, -Jeff Arnold, -Jeff Runningen, -Jens Petersen, -Jesse Rosenthal, -Joe Hillenbrand, -John MacFarlane, -John Muccigrosso, -Jonas Smedegaard, -Jonathan Daugherty, -Jose Luis Duran, -Josef Svenningsson, -Julien Cretel, -Juliusz Gonera, -Justin Bogner, -Jérémy Bobbio, -Kelsey Hightower, -Kolen Cheung, -Konstantin Zudov, -Kristof Bastiaensen, -Lars-Dominik Braun, -Luke Plant, -Mark Szepieniec, -Mark Wright, -Martin Linn, -Masayoshi Takahashi, -Matej Kollar, -Mathias Schenner, -Mathieu Duponchelle, -Matthew Eddey, -Matthew Pickering, -Matthias C. M. Troffaes, -Mauro Bieg, -Max Bolingbroke, -Max Rydahl Andersen, -Merijn Verstraaten, -Michael Beaumont, -Michael Chladek, -Michael Snoyman, -Michael Thompson, -MinRK, -Morton Fox, -Nathan Gass, -Neil Mayhew, -Nick Bart, -Nicolas Kaiser, -Nikolay Yakimov, -Oliver Matthews, -Ophir Lifshitz, -Pablo Rodríguez, -Paul Rivier, -Paulo Tanimoto, -Peter Wang, -Philippe Ombredanne, -Phillip Alday, -Prayag Verma, -Puneeth Chaganti, -Ralf Stephan, -Raniere Silva, -Recai Oktaş, -RyanGlScott, -Scott Morrison, -Sergei Trofimovich, -Sergey Astanin, -Shahbaz Youssefi, -Shaun Attfield, -Sidarth Kapur, -Sidharth Kapur, -Simon Hengel, -Sumit Sahrawat, -Thomas Hodgson, -Thomas Weißschuh, -Tim Lin, -Timothy Humphries, -Tiziano Müller, -Todd Sifleet, -Tom Leese, -Uli Köhler, -Václav Zeman, -Viktor Kronvall, -Vincent, -Václav Haisman, -Václav Zeman, -Wandmalfarbe, -Waldir Pimenta, -Wikiwide, -Xavier Olive, -bumper314, -csforste, -infinity0x, -nkalvi, -qerub, -robabla, -roblabla, -rodja.trappe, -rski, -shreevatsa.public, -takahashim, -tgkokk, -thsutton. +Copyright 2006-2017 John MacFarlane (jgm@berkeley.edu). Released +under the [GPL], version 2 or greater. This software carries no +warranty of any kind. (See COPYRIGHT for full copyright and +warranty notices.) For a full list of contributors, see the file +AUTHORS.md in the pandoc source code. [GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License" |