diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 500 |
1 files changed, 285 insertions, 215 deletions
@@ -12,25 +12,26 @@ 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], and (subsets of) [Textile], -[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki -markup], [Haddock markup], [OPML], [Emacs Org-mode], [DocBook], +[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown], +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], [reStructuredText], [XHTML], [HTML 5], [LaTeX] (including -[beamer] slide shows), [ConTeXt], [RTF], [OPML], [DocBook], +[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown], +[reStructuredText], [XHTML], [HTML5], [LaTeX] (including +[`beamer`] slide shows), [ConTeXt], [RTF], [OPML], [DocBook], [OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki markup], [DokuWiki markup], [Haddock markup], [EPUB] (v2 or v3), -[FictionBook2], [Textile], [groff man] pages, [Emacs Org-Mode], +[FictionBook2], [Textile], [groff man] pages, [Emacs Org mode], [AsciiDoc], [InDesign ICML], and [Slidy], [Slideous], [DZSlides], [reveal.js] or [S5] HTML slide shows. It can also produce [PDF] output on systems where LaTeX is installed. -Pandoc's enhanced version of markdown includes syntax for footnotes, -tables, flexible ordered lists, definition lists, fenced code blocks, -superscript, subscript, strikeout, title blocks, automatic tables of -contents, embedded LaTeX math, citations, and markdown inside HTML block -elements. (These enhancements, described below under -[Pandoc's markdown](#pandocs-markdown), can be disabled using the +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][Math rendering in HTML], [citations], and [markdown inside HTML block +elements][Extension: `markdown_in_html_blocks`]. (These enhancements, described below under +[Pandoc's markdown], can be disabled using the `markdown_strict` input or output format.) In contrast to most existing tools for converting markdown to HTML, which @@ -50,6 +51,44 @@ model. While conversions from Pandoc's Markdown to all formats aspire to be perfect, conversions from formats more expressive than Pandoc's Markdown can be expected to be lossy. +[markdown]: http://daringfireball.net/projects/markdown/ +[CommonMark]: http://commonmark.org +[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/ +[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/ +[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +[S5]: http://meyerweb.com/eric/tools/s5/ +[Slidy]: http://www.w3.org/Talks/Tools/Slidy/ +[Slideous]: http://goessner.net/articles/slideous/ +[HTML]: http://www.w3.org/html/ +[HTML5]: http://www.w3.org/TR/html5/ +[XHTML]: http://www.w3.org/TR/xhtml1/ +[LaTeX]: http://latex-project.org +[`beamer`]: https://ctan.org/pkg/beamer +[ConTeXt]: http://pragma-ade.nl +[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format +[DocBook]: http://docbook.org +[txt2tags]: http://txt2tags.org +[EPUB]: http://idpf.org/epub +[OPML]: http://dev.opml.org/spec2.html +[OpenDocument]: http://opendocument.xml.org +[ODT]: http://en.wikipedia.org/wiki/OpenDocument +[Textile]: http://redcloth.org/textile +[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting +[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki +[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules +[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html +[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html +[Haskell]: https://www.haskell.org +[GNU Texinfo]: http://www.gnu.org/software/texinfo/ +[Emacs Org mode]: http://orgmode.org +[AsciiDoc]: http://www.methods.co.nz/asciidoc/ +[DZSlides]: http://paulrouget.com/dzslides/ +[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx +[PDF]: https://www.adobe.com/pdf/ +[reveal.js]: http://lab.hakim.se/reveal-js/ +[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1 +[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf + Using `pandoc` -------------- @@ -69,7 +108,7 @@ document, use the `-s` or `--standalone` flag: pandoc -s -o output.html input.txt For more information on how standalone documents are produced, see -[Templates](#templates), below. +[Templates], below. Instead of a file, an absolute URI may be given. In this case pandoc will fetch the content using HTTP: @@ -88,7 +127,7 @@ markdown to LaTeX, you could type: pandoc -f markdown -t latex hello.txt -To convert `hello.html` from html to markdown: +To convert `hello.html` from HTML to markdown: pandoc -f html -t markdown hello.html @@ -112,7 +151,7 @@ be assumed to be markdown unless explicitly specified. Pandoc uses the UTF-8 character encoding for both input and output. If your local character encoding is not UTF-8, you -should pipe input and output through `iconv`: +should pipe input and output through [`iconv`]: iconv -t utf-8 input.txt | pandoc | iconv -f utf-8 @@ -121,6 +160,8 @@ RTF, OPML, DocBook, and Texinfo), information about the character encoding is included in the document header, which will only be included if you use the `-s/--standalone` option. +[`iconv`]: http://www.gnu.org/software/libiconv/ + Creating a PDF -------------- @@ -130,13 +171,57 @@ Pandoc will use LaTeX to convert it to PDF: pandoc test.txt -o test.pdf Production of a PDF requires that a LaTeX engine be installed (see -`--latex-engine`, below), and assumes that the following LaTeX packages are -available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the -`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`, -`graphicx` and `grffile` (if the document contains images), -`hyperref`, `ulem`, `babel` or `polyglossia` (if the `lang` variable is set), -`fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra` -and `xunicode` (if `xelatex` is used). +`--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`], [`url`], [`graphicx`] and [`grffile`] (if the +document contains images), [`color`], [`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. The +[`natbib`], [`biblatex`], [`bibtex`], and [`biber`] packages can +optionally be used for [citation rendering]. These are included with +all recent versions of [TeX Live]. + +PDF output can be controlled using [variables for LaTeX]. + +[`amsfonts`]: https://ctan.org/pkg/amsfonts +[`amsmath`]: https://ctan.org/pkg/amsmath +[`lm`]: https://ctan.org/pkg/lm +[`ifxetex`]: https://ctan.org/pkg/ifxetex +[`ifluatex`]: https://ctan.org/pkg/ifluatex +[`eurosym`]: https://ctan.org/pkg/eurosym +[`listings`]: https://ctan.org/pkg/listings +[`fancyvrb`]: https://ctan.org/pkg/fancyvrb +[`longtable`]: https://ctan.org/pkg/longtable +[`booktabs`]: https://ctan.org/pkg/booktabs +[`url`]: https://ctan.org/pkg/url +[`graphicx`]: https://ctan.org/pkg/graphicx +[`grffile`]: https://ctan.org/pkg/grffile +[`geometry`]: https://ctan.org/pkg/geometry +[`setspace`]: https://ctan.org/pkg/setspace +[`color`]: http://ctan.org/pkg/color +[`xecjk`]: https://ctan.org/pkg/xecjk +[`hyperref`]: https://ctan.org/pkg/hyperref +[`ulem`]: https://ctan.org/pkg/ulem +[`babel`]: https://ctan.org/pkg/babel +[`bidi`]: https://ctan.org/pkg/bidi +[`mathspec`]: https://ctan.org/pkg/mathspec +[`polyglossia`]: https://ctan.org/pkg/polyglossia +[`fontspec`]: https://ctan.org/pkg/fontspec +[`upquote`]: https://ctan.org/pkg/upquote +[`microtype`]: https://ctan.org/pkg/microtype +[`csquotes`]: https://ctan.org/pkg/csquotes +[`natbib`]: https://ctan.org/pkg/natbib +[`biblatex`]: https://ctan.org/pkg/biblatex +[`bibtex`]: https://ctan.org/pkg/bibtex +[`biber`]: https://ctan.org/pkg/biber +[TeX Live]: http://www.tug.org/texlive/ `hsmarkdown` ------------ @@ -146,14 +231,10 @@ a symbolic link to the `pandoc` executable called `hsmarkdown`. When invoked under the name `hsmarkdown`, `pandoc` will behave as if invoked with `-f markdown_strict --email-obfuscation=references`, and all command-line options will be treated as regular arguments. -However, this approach does not work under Cygwin, due to problems with +This approach does not work under [Cygwin], due to problems with its simulation of symbolic links. -[Cygwin]: http://www.cygwin.com/ -[`iconv`]: http://www.gnu.org/software/libiconv/ -[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network" -[TeX Live]: http://www.tug.org/texlive/ -[MacTeX]: http://www.tug.org/mactex/ +[Cygwin]: https://cygwin.com Options ======= @@ -166,23 +247,23 @@ 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 extended - markdown), `markdown_github` (github extended markdown), + markdown), `markdown_phpextra` (PHP Markdown Extra), + `markdown_github` (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 + `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](#literate-haskell-support), below. Markdown + 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](#pandocs-markdown), below, for a list of extensions and + markdown], below, for a list of extensions and their names. `-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT* @@ -191,12 +272,12 @@ 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 extended markdown), `markdown_github` (GitHub-flavored - markdown), `commonmark` (CommonMark markdown), `rst` - (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex` + Extra), `markdown_github` (GitHub-Flavored + Markdown), `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), `textile` (Textile), `org` (Emacs Org-Mode), + (DokuWiki markup), `textile` (Textile), `org` (Emacs Org mode), `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook), `opendocument` (OpenDocument), `odt` (OpenOffice text document), `docx` (Word docx), `haddock` (Haddock markup), `rtf` (rich text @@ -207,13 +288,13 @@ General options 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](#custom-writers), below). Note that `odt`, `epub`, and + 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](#literate-haskell-support), below. Markdown syntax + 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`. @@ -334,12 +415,8 @@ Reader options Filters may be written in any language. `Text.Pandoc.JSON` exports `toJSONFilter` to facilitate writing filters in Haskell. Those who would prefer to write filters in python can use the - module `pandocfilters`, installable from PyPI. See - <http://github.com/jgm/pandocfilters> for the module and several - examples. There are also pandoc filter libraries in - [PHP](https://github.com/vinai/pandocfilters-php), - [perl](https://metacpan.org/pod/Pandoc::Filter), and - [javascript/node.js](https://github.com/mvhenderson/pandoc-filter-node). + module [`pandocfilters`], installable from PyPI. There are also + pandoc filter libraries in [PHP], [perl], and [javascript/node.js]. Note that the *EXECUTABLE* will be sought in the user's `PATH`, and not in the working directory, if no directory is @@ -391,6 +468,11 @@ Reader options references in the document so they point to the extracted files. This option only affects the docx and epub readers. +[`pandocfilters`]: https://github.com/jgm/pandocfilters +[PHP]: https://github.com/vinai/pandocfilters-php +[perl]: https://metacpan.org/pod/Pandoc::Filter +[javascript/node.js]: https://github.com/mvhenderson/pandoc-filter-node + General writer options ---------------------- @@ -404,7 +486,7 @@ General writer options `--template=`*FILE* : Use *FILE* as a custom template for the generated document. Implies - `--standalone`. See [Templates](#templates) below for a description + `--standalone`. See [Templates], below, for a description of template syntax. If no extension is specified, an extension corresponding to the writer will be added, so that `--template=special` looks for `special.html` for HTML output. If the template is not @@ -535,7 +617,7 @@ Options affecting specific writers `--atx-headers` -: Use ATX style headers in markdown and asciidoc output. The default is +: 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` @@ -577,7 +659,7 @@ Options affecting specific writers `--listings` -: Use the `listings` package for LaTeX code blocks +: Use the [`listings`] package for LaTeX code blocks `-i`, `--incremental` @@ -592,14 +674,14 @@ Options affecting specific writers 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](#structuring-the-slide-show), below. + [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>`) rather than the header itself. See - [Header identifiers](#header-identifiers), below. + [Header identifiers], below. `--email-obfuscation=none`|`javascript`|`references` @@ -674,8 +756,7 @@ Options affecting specific writers `--epub-metadata=`*FILE* : Look in the specified XML file for metadata for the EPUB. - The file should contain a series of Dublin Core elements, - as documented at <http://dublincore.org/documents/dces/>. + The file should contain a series of [Dublin Core elements]. For example: <dc:rights>Creative Commons</dc:rights> @@ -751,6 +832,9 @@ Options affecting specific writers If used multiple times, the arguments are provided with spaces between them. Note that no check for duplicate options is done. +[Dublin Core elements]: http://dublincore.org/documents/dces/ +[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime + Citation rendering ------------------ @@ -781,15 +865,15 @@ Citation rendering `--natbib` -: Use natbib for citations in LaTeX output. This option is not for use +: Use [`natbib`] for citations in LaTeX output. This option is not for use with the `pandoc-citeproc` filter or with PDF output. It is intended for - use in producing a LaTeX file that can be processed with bibtex. + use in producing a LaTeX file that can be processed with [`bibtex`]. `--biblatex` -: Use biblatex for citations in LaTeX output. This option is not for use +: Use [`biblatex`] for citations in LaTeX output. This option is not for use with the `pandoc-citeproc` filter or with PDF output. It is intended for - use in producing a LaTeX file that can be processed with bibtex or biber. + use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`]. Math rendering in HTML ---------------------- @@ -806,7 +890,7 @@ Math rendering in HTML `--mathml`[`=`*URL*] -: Convert TeX math to MathML (in `docbook` as well as `html` and `html5`). +: Convert TeX math to [MathML] (in `docbook` as well as `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. @@ -856,6 +940,14 @@ Math rendering in HTML not specified, a link to the KaTeX CDN will be inserted. Note that this option does not imply `--katex`. +[MathML]: http://www.w3.org/Math/ +[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/ +[jsMath]: http://www.math.union.edu/~dpvc/jsmath/ +[MathJax]: https://www.mathjax.org +[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/ +[mimeTeX]: http://www.forkosh.com/mimetex.html +[KaTeX]: https://github.com/Khan/KaTeX + Options for wrapper scripts --------------------------- @@ -881,13 +973,6 @@ Options for wrapper scripts pandoc -o foo.html -s -[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/ -[jsMath]: http://www.math.union.edu/~dpvc/jsmath/ -[MathJax]: http://www.mathjax.org/ -[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/ -[mimeTeX]: http://www.forkosh.com/mimetex.html -[CSL]: http://CitationStyles.org - Templates ========= @@ -907,7 +992,8 @@ customize the `default.latex` template. Templates contain *variables*, which allow for the inclusion of arbitrary information at any point in the file. Variables may be set -within the document using YAML metadata. They may also be set at the +within the document using [YAML metadata blocks][Extension: `yaml_metadata_block`]. +They may also be set at the command line using the `-V/--variable` option: variables set in this way override metadata fields with the same name. @@ -915,8 +1001,22 @@ Variables set by pandoc ----------------------- Some variables are set automatically by pandoc. These vary somewhat -depending on the output format, but include metadata fields (such -as `title`, `author`, and `date`) as well as the following: +depending on the output format, but include metadata fields as well as the following: + +`title`, `author`, `date` +: allow identification of basic aspects of the document. + Included in PDF metadata through LaTeX. + These can be set through a [pandoc title block][Extension: `pandoc_title_block`], + which allows for multiple authors, or through a YAML metadata block: + + --- + author: + - Aristotle + - Peter Abelard + ... + +`abstract` +: allows for specification of document summary in LaTeX and Word docx `header-includes` : contents specified by `-H/--include-in-header` (may have multiple @@ -963,14 +1063,17 @@ Language variables override the base direction in some output formats. This may not always be necessary if the final renderer (e.g. the browser, when generating HTML) supports the - [Unicode Bidirectional Algorithm][uba-basics]. + [Unicode Bidirectional Algorithm]. + + LaTeX and ConTeXt assume by default that all text is left-to-right. + Setting `dir: ltr` enables bidirectional text handling in a document + whose base direction is left-to-right but contains some right-to-left script. When using LaTeX for bidirectional documents, only the `xelatex` engine - is fully supported (see `--latex-engine`). - Setting the `dir` variable enables bidirectional text - handling in LaTeX and ConTeXt: set `dir: ltr` for - documents that also contain some right-to-left script, - even if the base direction is the default left-to-right. + is fully supported (use `--latex-engine=xelatex`). + +[BCP 47]: https://tools.ietf.org/html/bcp47 +[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics Variables for slides -------------------- @@ -992,69 +1095,67 @@ Variables for slides : reveal.js or LaTeX beamer theme `transition` -: reveal.js transition +: reveal.js transition: `cube`, `page`, `concave`, `zoom`, `linear`, `fade`, or `none` + +`center` +: enables vertical centering of slides in reveal.js + +`maxScale` +: bounds for smallest/largest possible content scale in reveal.js (default: 1.5) + +`slideNumber` +: enables display of the page number of the current slide in reveal.js + +`colortheme`, `fonttheme`, `innertheme`, `outertheme` +: themes for LaTeX [`beamer`] documents Variables for LaTeX ------------------- `fontsize` -: font size (10pt, 11pt, 12pt) for LaTeX documents +: font size (e.g. `10pt`, `12pt`) for LaTeX documents `documentclass` -: document class for LaTeX documents, e.g. `article`, `report`, `book` +: document class for LaTeX documents, e.g. [`article`], [`report`], [`book`], [`memoir`] `classoption` -: option for LaTeX documentclass, e.g. `oneside`; may be repeated +: option for LaTeX document class, e.g. `oneside`; may be repeated for multiple options `geometry` -: options for LaTeX `geometry` package, e.g. `margin=1in`; +: option for LaTeX [`geometry`] package, e.g. `margin=1in`; may be repeated for multiple options `linestretch` -: adjusts line spacing in LaTeX documents using the `setspace` +: adjusts line spacing in LaTeX documents using the [`setspace`] package, e.g. `onehalfspacing`, `doublespacing` `fontfamily` -: font package to use for LaTeX documents (with pdflatex): - TeX Live has `bookman` (Bookman), `utopia` or `fourier` (Utopia), - `fouriernc` (New Century Schoolbook), `times` or `txfonts` (Times), - `mathpazo` or `pxfonts` or `mathpple` (Palatino), - `libertine` (Linux Libertine), `arev` (Arev Sans), - and the default `lmodern`, among others. +: font package for LaTeX documents (with `pdflatex`): + [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. + The default is [Latin Modern][`lm`]. `fontfamilyoptions` -: options to use with `fontfamily` package: e.g. `osf,sc` with - `fontfamily` set to `mathpazo` provides Palatino with old-style +: options for package used as `fontfamily`: e.g. `osf,sc` with + `fontfamily` set to [`mathpazo`] provides Palatino with old-style figures and true small caps `mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` : fonts for LaTeX documents (works only with `xelatex` and `lualatex`): takes the name of any system font, using the - `fontspec` package. Note that if `CJKmainfont` is used, - the `xeCJK` package must be available. + [`fontspec`] package. Note that if `CJKmainfont` is used, + the [`xecjk`] package must be available. `mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions` : options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` in `xelatex` and `lualatex`. Allows for any choices - available through `fontspec`, such as the OpenType features + available through [`fontspec`], such as the OpenType features `Numbers=OldStyle,Numbers=Proportional`. -`colortheme`, `fonttheme`, `innertheme`, `outertheme` -: themes for LaTeX beamer documents - -`linkcolor` -: color for internal links in LaTeX documents, e.g. `red`, `green`, - `magenta`, `cyan`, `blue`, `black` - -`toccolor` -: color for links in table of contents in LaTeX documents - -`urlcolor` -: color for external links in LaTeX documents - -`citecolor` -: color for citation links in LaTeX documents +`linkcolor`, `toccolor`, `urlcolor`, `citecolor` +: color for internal links, links in table of contents, external links, + and citation links in LaTeX documents, using options available through + [`color`] package, e.g. `red`, `green`, `magenta`, `cyan`, `blue`, `black` `links-as-notes` : causes links to be printed as footnotes in LaTeX documents @@ -1080,6 +1181,13 @@ Variables for LaTeX `biblio-style` : bibliography style in LaTeX, when used with `--natbib` +[`article`]: https://ctan.org/pkg/article +[`report`]: https://ctan.org/pkg/report +[`book`]: https://ctan.org/pkg/book +[`memoir`]: https://ctan.org/pkg/memoir +[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/ +[`mathpazo`]: https://ctan.org/pkg/mathpazo + Variables for man pages ----------------------- @@ -1138,10 +1246,11 @@ an object as its value. So, for example: If you use custom templates, you may need to revise them as pandoc changes. We recommend tracking the changes in the default templates, and modifying your custom templates accordingly. An easy way to do this -is to fork the pandoc-templates repository -(<http://github.com/jgm/pandoc-templates>) and merge in changes after each +is to fork the [pandoc-templates] repository and merge in changes after each pandoc release. +[pandoc-templates]: https://github.com/jgm/pandoc-templates + Pandoc's markdown ================= @@ -1194,7 +1303,7 @@ are ignored. Headers ------- -There are two kinds of headers, Setext and atx. +There are two kinds of headers: Setext and ATX. ### Setext-style headers ### @@ -1208,12 +1317,12 @@ A setext-style header is a line of text "underlined" with a row of `=` signs ------------------ The header text can contain inline formatting, such as emphasis (see -[Inline formatting](#inline-formatting), below). +[Inline formatting], below). -### Atx-style headers ### +### ATX-style headers ### -An Atx-style header consists of one to six `#` signs and a line of +An ATX-style header consists of one to six `#` signs and a line of text, optionally followed by any number of `#` signs. The number of `#` signs at the beginning of the line is the header level: @@ -1237,7 +1346,7 @@ wrapping). Consider, for example: #22, for example, and #5. -### Header identifiers ### +### Header identifiers #### Extension: `header_attributes` #### @@ -1429,7 +1538,7 @@ of the verbatim text, and is removed in the output. Note: blank lines in the verbatim text need not begin with four spaces. -### Fenced code blocks ### +### Fenced code blocks #### Extension: `fenced_code_blocks` #### @@ -1636,7 +1745,7 @@ pandoc interprets it that way. [markdown syntax guide]: http://daringfireball.net/projects/markdown/syntax#list -### Ordered lists ### +### Ordered lists Ordered lists work just like bulleted lists, except that the items begin with enumerators rather than bullets. @@ -1716,7 +1825,7 @@ If default list markers are desired, use `#.`: #. three -### Definition lists ### +### Definition lists #### Extension: `definition_lists` #### @@ -1770,13 +1879,10 @@ definition: Note that space between items in a definition list is required. (A variant that loosens this requirement, but disallows "lazy" hard wrapping, can be activated with `compact_definition_lists`: see -[Non-pandoc extensions](#non-pandoc-extensions), below.) +[Non-pandoc extensions], below.) [^3]: I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html). -[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/ - - ### Numbered example lists ### #### Extension: `example_lists` #### @@ -2008,7 +2114,7 @@ arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). Alignments are not supported, nor are cells that span multiple columns or rows. Grid tables can be created easily using [Emacs table mode]. - [Emacs table mode]: http://table.sourceforge.net/ +[Emacs table mode]: http://table.sourceforge.net/ #### Extension: `pipe_tables` #### @@ -2022,7 +2128,7 @@ Pipe tables look like this: : Demonstration of pipe table syntax. -The syntax is [the same as in PHP markdown extra]. The beginning and +The syntax is identical to [PHP Markdown Extra tables]. The beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. The header cannot be omitted. To simulate a headerless table, include a header @@ -2044,9 +2150,6 @@ output, the cells produced by pipe tables will not wrap, since there is no information available about relative widths. If you want content to wrap within cells, use multiline or grid tables. - [the same as in PHP markdown extra]: - http://michelf.ca/projects/php-markdown/extra/#table - Note: Pandoc also recognizes pipe tables of the following form, as can be produced by Emacs' orgtbl-mode: @@ -2059,10 +2162,12 @@ The difference is that `+` is used instead of `|`. Other orgtbl features are not supported. In particular, to get non-default column alignment, you'll need to add colons as above. +[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table + Metadata blocks --------------- -#### Extension: `pandoc_title_block` #### +#### Extension: `pandoc_title_block` If the file begins with a title block @@ -2138,7 +2243,7 @@ will also have "Pandoc User Manuals" in the footer. will also have "Version 4.0" in the header. -#### Extension: `yaml_metadata_block` #### +#### Extension: `yaml_metadata_block` A YAML metadata block is a valid YAML object, delimited by a line of three hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots @@ -2257,8 +2362,8 @@ 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 uses the `csquotes` package, pandoc will -detect automatically this and use `\enquote{...}` for quoted text. +Note: if your LaTeX template calls for the [`csquotes`] package, pandoc will +detect this automatically and use `\enquote{...}` for quoted text. Inline formatting ----------------- @@ -2289,7 +2394,7 @@ just part of a word, use `*`: feas*ible*, not feas*able*. -### Strikeout ### +### Strikeout #### Extension: `strikeout` #### @@ -2299,7 +2404,7 @@ with `~~`. Thus, for example, This ~~is deleted text.~~ -### Superscripts and subscripts ### +### Superscripts and subscripts #### Extension: `superscript`, `subscript` #### @@ -2342,7 +2447,7 @@ work in verbatim contexts: #### Extension: `inline_code_attributes` #### Attributes can be attached to verbatim text, just as with -[fenced code blocks](#fenced-code-blocks): +[fenced code blocks]: `<$>`{.haskell} @@ -2371,12 +2476,11 @@ them and they won't be treated as math delimiters. TeX math will be printed in all output formats. How it is rendered depends on the output format: -Markdown, LaTeX, Org-Mode, ConTeXt +Markdown, LaTeX, Emacs Org mode, ConTeXt ~ It will appear verbatim between `$` characters. reStructuredText - ~ It will be rendered using an interpreted text role `:math:`, as described - [here](http://docutils.sourceforge.net/docs/ref/rst/roles.html#math) + ~ It will be rendered using an [interpreted text role `:math:`]. AsciiDoc ~ It will be rendered as `latexmath:[...]`. @@ -2397,8 +2501,8 @@ RTF, OpenDocument, ODT ~ It will be rendered, if possible, using unicode characters, and will otherwise appear verbatim. -Docbook - ~ If the `--mathml` flag is used, it will be rendered using mathml +DocBook + ~ If the `--mathml` flag is used, it will be rendered using MathML in an `inlineequation` or `informalequation` tag. Otherwise it will be rendered, if possible, using unicode characters. @@ -2440,7 +2544,7 @@ HTML, Slidy, DZSlides, S5, EPUB 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 + formula and an HTML file with links to these images. So, the procedure is: pandoc -s --gladtex myfile.txt -o myfile.htex @@ -2458,6 +2562,8 @@ HTML, Slidy, DZSlides, S5, EPUB math) and put in `<span>` tags with class `math`. The [MathJax] script will be used to render it as formulas. +[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math + Raw HTML -------- @@ -2473,7 +2579,7 @@ The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown, and Textile output, and suppressed in other formats. -#### Extension: `markdown_in_html_blocks` #### +#### Extension: `markdown_in_html_blocks` Standard markdown allows you to include HTML "blocks": blocks of HTML between balanced tags that are separated from the surrounding text @@ -2665,8 +2771,7 @@ be omitted entirely: ### Internal links ### To link to another section of the same document, use the automatically -generated identifier (see [Header identifiers](#header-identifiers), -below). For example: +generated identifier (see [Header identifiers]). For example: See the [Introduction](#introduction). @@ -2789,15 +2894,14 @@ The bibliography may have any of these formats: MODS .mods RIS .ris -Note that `.bib` can generally be used with both BibTeX and BibLaTeX -files, but you can use `.bibtex` to force BibTeX. +Note that `.bib` can be used with both BibTeX and BibLaTeX files; +use `.bibtex` to force BibTeX. Note that `pandoc-citeproc --bib2json` and `pandoc-citeproc --bib2yaml` can produce `.json` and `.yaml` files from any of the supported formats. -In-field markup: In bibtex and biblatex databases, pandoc-citeproc parses -(a subset of) LaTeX markup; in CSL JSON databases, an HTML-like markup -([specs](http://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields)); +In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc parses +a subset of LaTeX markup; in CSL JSON databases, an [HTML-like markup][CSL markup specs]; and in CSL YAML databases, pandoc markdown. `pandoc-citeproc -j` and `-y` interconvert these markup formats as far as possible. @@ -2835,13 +2939,11 @@ YAML-encoded references, for example: (`pandoc-citeproc --bib2yaml` can produce these from a bibliography file in one of the supported formats.) -By default, `pandoc-citeproc` will use the Chicago Manual of Style author-date -format for citations and references. To use another style, you will need to -specify a [CSL] 1.0 style file in the `csl` metadata field. A repository of CSL -styles can be found at <https://github.com/citation-style-language/styles>. See -also <http://zotero.org/styles> for easy browsing. A primer on creating and -modifying CSL styles can be found at -<http://citationstyles.org/downloads/primer.html>. +Citations and references can be formatted using any style supported by the +[Citation Style Language], listed in the [Zotero Style Repository]. +These files are specified using the `--csl` option or the `csl` metadata field. +By default, `pandoc-citeproc` will use the [Chicago Manual of Style] author-date +format. The CSL project provides further information on [finding and editing styles]. Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of '@' + the citation @@ -2856,17 +2958,15 @@ characters (`:.#$%&-+?<>~/`). Here are some examples: Blah blah [@smith04; @doe99]. -`pandoc-citeproc` detects locator terms based on the [CSL locale files]. +`pandoc-citeproc` detects locator terms in the [CSL locale files]. Either abbreviated or unabbreviated forms are accepted. In the `en-US` locale, locator terms include `book`, `bk.`; `chapter`, `chap.`; `column`, `col.`; -`figure`, `fig.`; `folio`, `f.`; `number`, `no.`; `line`, `l.`; `note`, `n.`; +`figure`, `fig.`; `folio`, `fol.`; `number`, `no.`; `line`, `l.`; `note`, `n.`; `opus`, `op.`; `page`, `p.`; `paragraph`, `para.`; `part`, `pt.`; `section`, `sec.`; `sub verbo`, `s.v.`; `verse`, `v.`; `volume`, `vol.` as well as the plural forms of all these. If no locator term is used, "page" is assumed. - [CSL locale files]: https://github.com/citation-style-language/locales - A minus sign (`-`) before the `@` will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text: @@ -2906,12 +3006,19 @@ In this example, the document will contain a citation for `item3` only, but the bibliography will contain entries for `item1`, `item2`, and `item3`. -For LaTeX or PDF output, you can also use NatBib or BibLaTeX +For LaTeX or PDF output, you can also use [`natbib`] or [`biblatex`] to render bibliography. In order to do so, specify bibliography files as outlined above, and add `--natbib` or `--biblatex` argument to `pandoc` invocation. Bear in mind that bibliography files have to be in respective format (either BibTeX or BibLaTeX). +[CSL markup specs]: http://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields +[Chicago Manual of Style]: http://chicagomanualofstyle.org +[Citation Style Language]: http://citationstyles.org +[Zotero Style Repository]: https://www.zotero.org/styles +[finding and editing styles]: http://citationstyles.org/styles/ +[CSL locale files]: https://github.com/citation-style-language/locales + Non-pandoc extensions --------------------- @@ -2971,13 +3078,13 @@ See the MultiMarkdown documentation for details. If `pandoc_title_block` or `yaml_metadata_block` is enabled, it will take precedence over `mmd_title_block`. - [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/ +[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/ #### Extension: `abbreviations` #### Parses PHP Markdown Extra abbreviation keys, like - *[HTML]: Hyper Text Markup Language + *[HTML]: Hypertext Markup Language Note that the pandoc document model does not support abbreviations, so if this extension is enabled, abbreviation keys are @@ -3008,7 +3115,7 @@ after the header but before any trailing `#`s in an ATX header). #### Extension: `compact_definition_lists` #### Activates the definition list syntax of pandoc 1.12.x and earlier. -This syntax differs from the one described [above](#definition-lists) +This syntax differs from the one described above under [Definition lists] in several respects: - No blank line is required between consecutive items of the @@ -3043,7 +3150,7 @@ variants are supported: `fenced_code_blocks`, `definition_lists`, `intraword_underscores`, `header_attributes`, `abbreviations`, `shortcut_reference_links`. -`markdown_github` (GitHub-flavored Markdown) +`markdown_github` (GitHub-Flavored Markdown) : `pipe_tables`, `raw_html`, `tex_math_single_backslash`, `fenced_code_blocks`, `auto_identifiers`, `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`, @@ -3081,7 +3188,7 @@ 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`]. Here's the markdown source for a simple slide show, `habits.txt`: @@ -3239,7 +3346,7 @@ using the `-V` option: Note that header attributes will turn into slide attributes (on a `<div>` or `<section>`) in HTML slide formats, allowing you -to style individual slides. In Beamer, the only header attribute +to style individual slides. In beamer, the only header attribute that affects slides is the `allowframebreaks` class, which sets the `allowframebreaks` option, causing multiple slides to be created if the content overfills the frame. This is recommended especially for @@ -3279,8 +3386,8 @@ EPUB Metadata ============= EPUB metadata may be specified using the `--epub-metadata` option, but -if the source document is markdown, it is better to use a YAML metadata -block. Here is an example: +if the source document is markdown, it is better to use a [YAML metadata +block][Extension: `yaml_metadata_block`]. Here is an example: --- title: @@ -3317,7 +3424,7 @@ The following fields are recognized: `creator` ~ Either a string value, or an object with fields `role`, `file-as`, and `text`, or a list of such objects. Valid values for `role` are - [marc relators](http://www.loc.gov/marc/relators/relaterm.html), but + [MARC relators], but pandoc will attempt to translate the human-readable versions (like "author" and "editor") to the appropriate marc relators. @@ -3361,7 +3468,10 @@ The following fields are recognized: `page-progression-direction` ~ Either `ltr` or `rtl`. Specifies the `page-progression-direction` - spine [attribute][EPUBspine]. + attribute for the [`spine` element]. + +[MARC relators]: http://loc.gov/marc/relators/relaterm.html +[`spine` element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem Literate Haskell support ======================== @@ -3374,13 +3484,13 @@ 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 '#'. + 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 + 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 @@ -3413,10 +3523,8 @@ and pasted as literate Haskell source. Syntax highlighting =================== -Pandoc will automatically highlight syntax in fenced code blocks that -are marked with a language name. (See [Extension: -`inline_code_attributes`] and [Extension: `fenced_code_attributes`], -above.) The Haskell library [highlighting-kate] is used for +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. The color scheme can be selected using the `--highlight-style` option. The default color scheme is `pygments`, which imitates the default color @@ -3428,6 +3536,8 @@ To see a list of language names that pandoc will recognize, type To disable highlighting, use the `--no-highlight` option. +[highlighting-kate]: https://github.com/jgm/highlighting-kate + Custom writers ============== @@ -3445,6 +3555,8 @@ which you can modify according to your needs, do pandoc --print-default-data-file sample.lua +[lua]: http://www.lua.org + Authors ======= @@ -3578,46 +3690,4 @@ Vincent, Wikiwide, and Xavier Olive. -[markdown]: http://daringfireball.net/projects/markdown/ -[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html -[S5]: http://meyerweb.com/eric/tools/s5/ -[Slidy]: http://www.w3.org/Talks/Tools/Slidy/ -[Slideous]: http://goessner.net/articles/slideous/ -[HTML]: http://www.w3.org/TR/html40/ -[HTML 5]: http://www.w3.org/TR/html5/ -[XHTML]: http://www.w3.org/TR/xhtml1/ -[LaTeX]: http://www.latex-project.org/ -[beamer]: https://ctan.org/pkg/beamer -[ConTeXt]: http://www.pragma-ade.nl/ -[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format -[DocBook]: http://www.docbook.org/ -[OPML]: http://dev.opml.org/spec2.html -[OpenDocument]: http://opendocument.xml.org/ -[ODT]: http://en.wikipedia.org/wiki/OpenDocument -[Textile]: http://redcloth.org/textile -[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting -[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki -[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules -[Haddock markup]: http://www.haskell.org/haddock/doc/html/ch03s08.html -[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html -[Haskell]: http://www.haskell.org/ -[GNU Texinfo]: http://www.gnu.org/software/texinfo/ -[Emacs Org-Mode]: http://orgmode.org -[AsciiDoc]: http://www.methods.co.nz/asciidoc/ [GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License" -[DZSlides]: http://paulrouget.com/dzslides/ -[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime -[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx -[PDF]: http://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 -[lua]: http://www.lua.org -[marc relators]: http://www.loc.gov/marc/relators/relaterm.html -[BCP 47]: https://tools.ietf.org/html/bcp47 -[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf -[txt2tags]: http://txt2tags.org/ -[EPUB]: http://idpf.org/epub -[EPUBspine]: http://www.idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem -[KaTeX]: https://github.com/Khan/KaTeX -[CommonMark]: http://commonmark.org -[highlighting-kate]: http://github.com/jgm/highlighting-kate |