diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 1025 |
1 files changed, 663 insertions, 362 deletions
@@ -1,6 +1,6 @@ % Pandoc User's Guide % John MacFarlane -% July 15, 2015 +% November 12, 2015 Synopsis ======== @@ -12,34 +12,84 @@ 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 +on systems where LaTeX or ConTeXt is installed. + +Pandoc's enhanced version of Markdown includes syntax for [footnotes], +[tables], flexible [ordered lists], [definition lists], [fenced code blocks], +[superscripts and subscripts], [strikeout], [metadata blocks], automatic tables of +contents, embedded LaTeX [math], [citations], and [Markdown inside HTML block +elements][Extension: `markdown_in_html_blocks`]. (These enhancements, described below under +[Pandoc's Markdown], can be disabled using the `markdown_strict` input or output format.) -In contrast to most existing tools for converting markdown to HTML, which -use regex substitutions, Pandoc has a modular design: it consists of a +In contrast to most existing tools for converting Markdown to HTML, which +use regex substitutions, pandoc has a modular design: it consists of a set of readers, which parse text in a given format and produce a native representation of the document, and a set of writers, which convert this native representation into a target format. Thus, adding an input or output format requires only adding a reader or writer. +Because pandoc's intermediate representation of a document is less +expressive than many of the formats it converts between, one should +not expect perfect conversions between every format and every other. +Pandoc attempts to preserve the structural elements of a document, but +not formatting details such as margin size. And some document elements, +such as complex tables, may not fit into pandoc's simple document +model. While conversions from pandoc's Markdown to all formats aspire +to be perfect, conversions from formats more expressive than pandoc's +Markdown can be expected to be lossy. + +[Markdown]: http://daringfireball.net/projects/markdown/ +[CommonMark]: http://commonmark.org +[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/ +[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/ +[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +[S5]: http://meyerweb.com/eric/tools/s5/ +[Slidy]: http://www.w3.org/Talks/Tools/Slidy/ +[Slideous]: http://goessner.net/articles/slideous/ +[HTML]: http://www.w3.org/html/ +[HTML5]: http://www.w3.org/TR/html5/ +[XHTML]: http://www.w3.org/TR/xhtml1/ +[LaTeX]: http://latex-project.org +[`beamer`]: https://ctan.org/pkg/beamer +[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf +[ConTeXt]: http://contextgarden.net/ +[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format +[DocBook]: http://docbook.org +[txt2tags]: http://txt2tags.org +[EPUB]: http://idpf.org/epub +[OPML]: http://dev.opml.org/spec2.html +[OpenDocument]: http://opendocument.xml.org +[ODT]: http://en.wikipedia.org/wiki/OpenDocument +[Textile]: http://redcloth.org/textile +[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting +[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki +[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` -------------- @@ -59,7 +109,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: @@ -74,11 +124,11 @@ 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: +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 @@ -93,16 +143,16 @@ the input and output filenames. Thus, for example, pandoc -o hello.tex hello.txt -will convert `hello.txt` from markdown to LaTeX. If no output file +will convert `hello.txt` from Markdown to LaTeX. If no output file is specified (so that output goes to *stdout*), or if the output file's extension is unknown, the output format will default to HTML. If no input file is specified (so that input comes from *stdin*), or if the input files' extensions are unknown, the input format will -be assumed to be markdown unless explicitly specified. +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 @@ -111,26 +161,71 @@ 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 -------------- -Earlier versions of pandoc came with a program, `markdown2pdf`, that -used pandoc and pdflatex to produce a PDF. This is no longer needed, -since `pandoc` can now produce `pdf` output itself. To produce a PDF, simply -specify an output file with a `.pdf` extension. Pandoc will create a latex -file and use pdflatex (or another engine, see `--latex-engine`) to convert it -to PDF: +To produce a PDF, specify an output file with a `.pdf` extension. +By default, pandoc will use LaTeX to convert it to PDF: pandoc test.txt -o test.pdf Production of a PDF requires that a LaTeX engine be installed (see -`--latex-engine`, below), and assumes that the following LaTeX packages are -available: `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` (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`], [`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. 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 to create a PDF. +To do this, specify an output file with a `.pdf` extension, +as before, but add `-t context` to the command line. + +PDF output can be controlled using [variables for LaTeX] +or [variables for ConTeXt]. + +[`amsfonts`]: https://ctan.org/pkg/amsfonts +[`amsmath`]: https://ctan.org/pkg/amsmath +[`lm`]: https://ctan.org/pkg/lm +[`ifxetex`]: https://ctan.org/pkg/ifxetex +[`ifluatex`]: https://ctan.org/pkg/ifluatex +[`eurosym`]: https://ctan.org/pkg/eurosym +[`listings`]: https://ctan.org/pkg/listings +[`fancyvrb`]: https://ctan.org/pkg/fancyvrb +[`longtable`]: https://ctan.org/pkg/longtable +[`booktabs`]: https://ctan.org/pkg/booktabs +[`graphicx`]: https://ctan.org/pkg/graphicx +[`grffile`]: https://ctan.org/pkg/grffile +[`geometry`]: https://ctan.org/pkg/geometry +[`setspace`]: https://ctan.org/pkg/setspace +[`xecjk`]: https://ctan.org/pkg/xecjk +[`hyperref`]: https://ctan.org/pkg/hyperref +[`ulem`]: https://ctan.org/pkg/ulem +[`babel`]: https://ctan.org/pkg/babel +[`bidi`]: https://ctan.org/pkg/bidi +[`mathspec`]: https://ctan.org/pkg/mathspec +[`polyglossia`]: https://ctan.org/pkg/polyglossia +[`fontspec`]: https://ctan.org/pkg/fontspec +[`upquote`]: https://ctan.org/pkg/upquote +[`microtype`]: https://ctan.org/pkg/microtype +[`csquotes`]: https://ctan.org/pkg/csquotes +[`natbib`]: https://ctan.org/pkg/natbib +[`biblatex`]: https://ctan.org/pkg/biblatex +[`bibtex`]: https://ctan.org/pkg/bibtex +[`biber`]: https://ctan.org/pkg/biber +[TeX Live]: http://www.tug.org/texlive/ `hsmarkdown` ------------ @@ -140,14 +235,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 ======= @@ -159,38 +250,38 @@ 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), - `commonmark` (CommonMark markdown), `textile` (Textile), `rst` + extended Markdown), `markdown_strict` (original unextended + 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 + 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* : Specify output format. *FORMAT* can be `native` (native Haskell), `json` (JSON version of native AST), `plain` (plain text), - `markdown` (pandoc's extended markdown), `markdown_strict` - (original unextended markdown), `markdown_phpextra` (PHP Markdown - extra extended markdown), `markdown_github` (github extended - markdown), `commonmark` (CommonMark markdown), `rst` - (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex` + `markdown` (pandoc's extended Markdown), `markdown_strict` + (original unextended Markdown), `markdown_phpextra` (PHP Markdown + 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 @@ -201,13 +292,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`. @@ -222,24 +313,31 @@ General options : 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 + will be used. This is, in Unix: $HOME/.pandoc - in unix, + in Windows XP: C:\Documents And Settings\USERNAME\Application Data\pandoc - in Windows XP, and + and in Windows Vista or later: C:\Users\USERNAME\AppData\Roaming\pandoc - in Windows 7. (You can find the default user data directory - on your system by looking at the output of `pandoc --version`.) - A `reference.odt`, `reference.docx`, `default.csl`, - `epub.css`, `templates`, `slidy`, `slideous`, or `s5` directory + You can find the default user data directory on your system by + looking at the output of `pandoc --version`. + A `reference.odt`, `reference.docx`, `epub.css`, `templates`, + `slidy`, `slideous`, or `s5` directory placed in this directory will override pandoc's normal defaults. +`--bash-completion` + +: Generate a bash completion script. To enable bash completion + with pandoc, add this to your `.bashrc`: + + eval "$(pandoc --bash-completion)" + `--verbose` : Give verbose debugging output. Currently this only has an effect @@ -260,9 +358,9 @@ Reader options : 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, HTML, + input. Raw HTML can be printed in Markdown, reStructuredText, HTML, Slidy, Slideous, DZSlides, reveal.js, and S5 output; raw LaTeX - can be printed in markdown, reStructuredText, LaTeX, and ConTeXt output. + can be printed in Markdown, reStructuredText, 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.) @@ -272,11 +370,9 @@ Reader options : 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 significant only when - the input format is `markdown`, `markdown_strict`, `textile` or `twiki`. - It is selected automatically when the input format is `textile` or the - output format is `latex` or `context`, unless `--no-tex-ligatures` - is used.) + 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` @@ -299,12 +395,12 @@ Reader options : Specify a default extension to use when image paths/URLs have no extension. This allows you to use the same source for formats that require different kinds of images. Currently this option only affects - the markdown and LaTeX readers. + the Markdown and LaTeX readers. `--filter=`*EXECUTABLE* : Specify an executable to be used as a filter transforming the - Pandoc AST after the input is parsed and before the output is + pandoc AST after the input is parsed and before the output is written. The executable should read JSON from stdin and write JSON to stdout. The JSON must be formatted like pandoc's own JSON input and output. The name of the output format will be @@ -321,12 +417,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 @@ -362,7 +454,7 @@ Reader options `--track-changes=accept`|`reject`|`all` : Specifies what to do with insertions and deletions produced by the MS - Word "track-changes" feature. `accept` (the default), inserts all + Word "Track Changes" feature. `accept` (the default), inserts all insertions, and ignores all deletions. `reject` inserts all deletions and ignores insertions. `all` puts in both insertions and deletions, wrapped in spans with `insertion` and `deletion` @@ -378,6 +470,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 ---------------------- @@ -391,7 +488,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 @@ -525,19 +622,19 @@ Options affecting specific writers `--reference-links` -: Use reference-style links, rather than inline links, in writing markdown +: Use reference-style links, rather than inline links, in writing Markdown or reStructuredText. By default inline links are used. `--atx-headers` -: Use ATX style headers in markdown and asciidoc output. The default is +: Use ATX-style headers in Markdown and asciidoc output. The default is to use setext-style headers for levels 1-2, and then ATX headers. `--chapters` : Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook - output. When the LaTeX template uses the report, book, or - memoir class, this option is implied. If `beamer` is the output + output. When the LaTeX document class is set to `report`, `book`, or + `memoir`, this option is implied. If `beamer` is the output format, top-level headers will become `\part{..}`. `-N`, `--number-sections` @@ -560,19 +657,23 @@ Options affecting specific writers `--no-tex-ligatures` -: Do not convert quotation marks, apostrophes, and dashes to - the TeX ligatures when writing LaTeX or ConTeXt. Instead, just - use literal unicode characters. This is needed for using advanced - OpenType features with XeLaTeX and LuaLaTeX. 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`. +: 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 listings package for LaTeX code blocks +: Use the [`listings`] package for LaTeX code blocks `-i`, `--incremental` @@ -587,26 +688,27 @@ 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` : Specify a method for obfuscating `mailto:` links in HTML documents. `none` leaves `mailto:` links as they are. `javascript` obfuscates them using javascript. `references` obfuscates them by printing their - letters as decimal or hexadecimal character references. + letters as decimal or hexadecimal character references. The default + is `javascript`. `--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. + 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. @@ -663,14 +765,13 @@ Options affecting specific writers : Use the specified image as the EPUB cover. It is recommended that the image be less than 1000px in width and height. Note that - in a markdown source document you can also specify `cover-image` + in a Markdown source document you can also specify `cover-image` in a YAML metadata block (see [EPUB Metadata], below). `--epub-metadata=`*FILE* : Look in the specified XML file for metadata for the EPUB. - The file should contain a series of Dublin Core elements, - 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> @@ -684,7 +785,7 @@ Options affecting specific writers id="BookId">` (a randomly generated UUID). Any of these may be overridden by elements in the metadata file. - Note: if the source document is markdown, a YAML metadata block + Note: if the source document is Markdown, a YAML metadata block in the document can be used instead. See below under [EPUB Metadata]. @@ -746,6 +847,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 ------------------ @@ -776,17 +880,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 pdflatex and - 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 pdflatex and - bibtex or biber. + use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`]. Math rendering in HTML ---------------------- @@ -803,7 +905,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. @@ -853,6 +955,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 --------------------------- @@ -864,13 +974,13 @@ Options for wrapper scripts with the `-o` option, or `-` (for *stdout*) if no output file was specified. The remaining lines contain the command-line arguments, one per line, in the order they appear. These do not include regular - Pandoc options and their arguments, but do include any options appearing + pandoc options and their arguments, but do include any options appearing after a `--` separator at the end of the line. `--ignore-args` : Ignore command-line arguments (for use in wrapper scripts). - Regular Pandoc options are not ignored. Thus, for example, + Regular pandoc options are not ignored. Thus, for example, pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1 @@ -878,13 +988,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 ========= @@ -892,30 +995,49 @@ When the `-s/--standalone` option is used, pandoc uses a template to add header and footer material that is needed for a self-standing document. To see the default template that is used, just type - pandoc -D FORMAT + pandoc -D *FORMAT* -where `FORMAT` is the name of the output format. A custom template +where *FORMAT* is the name of the output format. A custom template can be specified using the `--template` option. You can also override -the system default templates for a given output format `FORMAT` -by putting a file `templates/default.FORMAT` in the user data +the system default templates for a given output format *FORMAT* +by putting a file `templates/default.*FORMAT*` in the user data directory (see `--data-dir`, above). *Exceptions:* For `odt` output, customize the `default.opendocument` template. For `pdf` output, customize the `default.latex` template. -Templates may contain *variables*. Variable names are sequences of -alphanumerics, `-`, and `_`, starting with a letter. A variable name -surrounded by `$` signs will be replaced by its value. For example, -the string `$title$` in +Templates contain *variables*, which allow for the inclusion of +arbitrary information at any point in the file. Variables may be set +within the document using [YAML metadata blocks][Extension: +`yaml_metadata_block`]. They may also be set at the +command line using the `-V/--variable` option: variables set in this +way override metadata fields with the same name. - <title>$title$</title> +Variables set by pandoc +----------------------- -will be replaced by the document title. +Some variables are set automatically by pandoc. These vary somewhat +depending on the output format, but include metadata fields as well as the following: -To write a literal `$` in a template, use `$$`. +`title`, `author`, `date` +: allow identification of basic aspects of the document. + Included in PDF metadata through LaTeX and ConTeXt. + These can be set through a [pandoc title block][Extension: `pandoc_title_block`], + which allows for multiple authors, or through a YAML metadata block: -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: + --- + author: + - Aristotle + - Peter Abelard + ... + +`subtitle` +: document subtitle; also used as subject in PDF metadata + +`abstract` +: document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx + +`keywords` +: list of keywords to be included in HTML, PDF, and AsciiDoc metadata; may be repeated as for `author`, above `header-includes` : contents specified by `-H/--include-in-header` (may have multiple @@ -924,6 +1046,9 @@ as `title`, `author`, and `date`) as well as the following: `toc` : non-null value if `--toc/--table-of-contents` was specified +`toc-title` +: title of table of contents (works only with EPUB and docx) + `include-before` : contents specified by `-B/--include-before-body` (may have multiple values) @@ -935,8 +1060,54 @@ as `title`, `author`, and `date`) as well as the following: `body` : body of document +Language variables +------------------ + `lang` -: language code for HTML or LaTeX documents +: identifies the main language of the document, + using a code according to [BCP 47] (e.g. `en` or `en-GB`). + For some output formats, pandoc will convert it to an appropriate + format stored in the additional variables `babel-lang`, + `polyglossia-lang` (LaTeX) and `context-lang` (ConTeXt). + + Native pandoc `span`s and `div`s with the lang attribute + (value in BCP 47) can be used to switch the language in + that range. + +`otherlangs` +: a list of other languages used in the document + in the YAML metadata, according to [BCP 47]. For example: + `otherlangs: [en-GB, fr]`. + This is automatically generated from the `lang` attributes + in all `span`s and `div`s but can be overriden. + Currently only used by LaTeX through the generated + `babel-otherlangs` and `polyglossia-otherlangs` variables. + The LaTeX writer outputs polyglossia commands in the text but + the `babel-newcommands` variable contains mappings for them + to the corresponding babel. + +`dir` +: the base direction of the document, either `rtl` (right-to-left) + or `ltr` (left-to-right). + + For bidirectional documents, native pandoc `span`s and `div`s + with the `dir` attribute (value `rtl` or `ltr`) can be used to + override the base direction in some output formats. + This may not always be necessary if the final renderer + (e.g. the browser, when generating HTML) supports the + [Unicode Bidirectional Algorithm]. + + When using LaTeX for bidirectional documents, only the `xelatex` engine + is fully supported (use `--latex-engine=xelatex`). + +[BCP 47]: https://tools.ietf.org/html/bcp47 +[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics + +Variables for slides +-------------------- + +Variables are available for [producing slide shows with pandoc], +including all [reveal.js configuration options]. `slidy-url` : base URL for Slidy documents (defaults to @@ -951,84 +1122,168 @@ as `title`, `author`, and `date`) as well as the following: `revealjs-url` : base URL for reveal.js documents (defaults to `reveal.js`) -`theme` -: reveal.js or LaTeX beamer theme +`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` +: themes for LaTeX [`beamer`] documents + +`navigation` +: controls navigation symbols in `beamer` documents + (default is `empty` for no navigation symbols; other valid values + are `frame`, `vertical`, and `horizontal`). -`transition` -: reveal.js transition +[reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration + +Variables for LaTeX +------------------- + +LaTeX variables are used when [creating a PDF]. `fontsize` -: font size (10pt, 11pt, 12pt) for LaTeX documents +: font size for body text (e.g. `10pt`, `12pt`) `documentclass` -: document class for LaTeX documents +: document class, e.g. [`article`], [`report`], [`book`], [`memoir`] `classoption` -: option for LaTeX documentclass, e.g. `oneside`; may be repeated +: option for document class, e.g. `oneside`; may be repeated for multiple options `geometry` -: options for LaTeX `geometry` class, e.g. `margin=1in`; +: option for [`geometry`] package, e.g. `margin=1in`; may be repeated for multiple options `linestretch` -: adjusts line spacing (requires the `setspace` package) +: adjusts line spacing using the [`setspace`] + package, e.g. `1.25`, `1.5` `fontfamily` -: font package to use for LaTeX documents (with pdflatex): - TeXLive 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 use with `pdflatex`: + [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. + The default is [Latin Modern][`lm`]. + +`fontfamilyoptions` +: options for package used as `fontfamily`: e.g. `osf,sc` with + `fontfamily` set to [`mathpazo`] provides Palatino with old-style + figures and true small caps; may be repeated for multiple options `mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont` -: fonts for LaTeX documents (works only with xelatex - and lualatex). Note that if `CJKmainfont` is used, - the `xeCJK` package must be available. +: font families for use with `xelatex` or + `lualatex`: take the name of any system font, using the + [`fontspec`] package. Note that if `CJKmainfont` is used, + the [`xecjk`] package must be available. -`colortheme` -: colortheme for LaTeX beamer documents +`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions` +: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, + `CJKmainfont` in `xelatex` and `lualatex`. Allow for any choices + available through [`fontspec`], such as the OpenType features + `Numbers=OldStyle,Numbers=Proportional`. May be repeated for multiple options. -`fonttheme` -: fonttheme for LaTeX beamer documents +`fontenc` +: allows font encoding to be specified through `fontenc` package (with `pdflatex`); + default is `T1` (see guide to [LaTeX font encodings]) -`linkcolor` -: color for internal links in LaTeX documents (`red`, `green`, - `magenta`, `cyan`, `blue`, `black`) +`colorlinks` +: add color to link text; automatically enabled if any of `linkcolor`, `citecolor`, + `urlcolor`, or `toccolor` are set -`toccolor` -: color for links in table of contents in LaTeX documents +`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] -`urlcolor` -: color for external links in LaTeX documents +`links-as-notes` +: causes links to be printed as footnotes -`citecolor` -: color for citation links in LaTeX documents +`indent` +: uses document class settings for indentation (the default LaTeX template + otherwise removes indentation and adds space between paragraphs) -`links-as-notes` -: causes links to be printed as footnotes in LaTeX documents +`subparagraph` +: disables default behavior of LaTeX template that redefines (sub)paragraphs + as sections, changing the appearance of nested headings in some classes `toc` -: include table of contents in LaTeX documents +: include table of contents (can also be set using `--toc/--table-of-contents`) `toc-depth` -: level of section to include in table of contents in LaTeX documents - -`toc-title` -: title of table of contents (works only with EPUB and docx) - -`lof` -: include list of figures in LaTeX documents +: level of section to include in table of contents -`lot` -: include list of tables in LaTeX documents +`lof`, `lot` +: include list of figures, list of tables `bibliography` : bibliography to use for resolving references `biblio-style` -: bibliography style in LaTeX, when used with `--natbib` +: bibliography style, 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 +[predefined LaTeX colors]: https://en.wikibooks.org/wiki/LaTeX/Colors#Predefined_colors +[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/ +[`mathpazo`]: https://ctan.org/pkg/mathpazo +[LaTeX font encodings]: https://ctan.org/pkg/encguide + +Variables for ConTeXt +--------------------- + +`papersize` +: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]); + may be repeated for multiple options + +`layout` +: options for page margins and text arrangement (see [ConTeXt Layout]); + may be repeated for multiple options + +`fontsize` +: font size for body text (e.g. `10pt`, `12pt`) + +`mainfont`, `sansfont`, `monofont`, `mathfont` +: font families: take the name of any system font (see [ConTeXt Font Switching]) + +`linkcolor`, `contrastcolor` +: color for links outside and inside a page, e.g. `red`, `blue` (see [ConTeXt Color]) + +`linkstyle` +: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`, `type`, `cap`, `small` + +`indenting` +: controls indentation of paragraphs, e.g. `yes,small,next` (see [ConTeXt Indentation]); + may be repeated for multiple options + +`whitespace` +: spacing between paragraphs, e.g. `none`, `small` (using [`setupwhitespace`]) + +`interlinespace` +: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); + may be repeated for multiple options + +`headertext`, `footertext` +: text to be placed in running header or footer (see [ConTeXt Headers and Footers]); + may be repeated up to four times for different placement + +`pagenumbering` +: page number style and location (using [`setuppagenumbering`]); + may be repeated for multiple options + +`toc` +: include table of contents (can also be set using `--toc/--table-of-contents`) + +`lof`, `lot` +: include list of figures, list of tables + +[ConTeXt Paper Setup]: http://wiki.contextgarden.net/PaperSetup +[ConTeXt Layout]: http://wiki.contextgarden.net/Layout +[ConTeXt Font Switching]: http://wiki.contextgarden.net/Font_Switching +[ConTeXt Color]: http://wiki.contextgarden.net/Color +[ConTeXt Headers and Footers]: http://wiki.contextgarden.net/Headers_and_Footers +[ConTeXt Indentation]: http://wiki.contextgarden.net/Indentation +[`setupwhitespace`]: http://wiki.contextgarden.net/Command/setupwhitespace +[`setupinterlinespace`]: http://wiki.contextgarden.net/Command/setupinterlinespace +[`setuppagenumbering`]: http://wiki.contextgarden.net/Command/setuppagenumbering + +Variables for man pages +----------------------- `section` : section number in man pages @@ -1039,9 +1294,25 @@ as `title`, `author`, and `date`) as well as the following: `footer` : footer in man pages -Variables may be set at the command line using the `-V/--variable` -option. Variables set in this way override metadata fields with -the same name. +`adjusting` +: adjusts text to left (`l`), right (`r`), center (`c`), + or both (`b`) margins + +`hyphenate` +: if `true` (the default), hyphenation will be used + +Using variables in templates +---------------------------- + +Variable names are sequences of alphanumerics, `-`, and `_`, +starting with a letter. A variable name surrounded by `$` signs +will be replaced by its value. For example, the string `$title$` in + + <title>$title$</title> + +will be replaced by the document title. + +To write a literal `$` in a template, use `$$`. Templates may contain conditionals. The syntax is as follows: @@ -1076,22 +1347,23 @@ 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's markdown +[pandoc-templates]: https://github.com/jgm/pandoc-templates + +Pandoc's Markdown ================= Pandoc understands an extended and slightly revised version of -John Gruber's [markdown] syntax. This document explains the syntax, -noting differences from standard markdown. Except where noted, these +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 +`markdown_strict+footnotes` is strict Markdown with footnotes enabled, while `markdown-footnotes-pipe_tables` is pandoc's -markdown without footnotes or pipe tables. +Markdown without footnotes or pipe tables. Philosophy ---------- @@ -1108,7 +1380,7 @@ This principle has guided pandoc's decisions in finding syntax for tables, footnotes, and other extensions. There is, however, one respect in which pandoc's aims are different -from the original aims of markdown. Whereas markdown was originally +from the original aims of Markdown. Whereas Markdown was originally designed with HTML generation in mind, pandoc is designed for multiple output formats. Thus, while pandoc allows the embedding of raw HTML, it discourages it, and provides other, non-HTMLish ways of representing @@ -1132,7 +1404,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 ### @@ -1146,12 +1418,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: @@ -1165,7 +1437,7 @@ As with setext-style headers, the header text can contain formatting: #### Extension: `blank_before_header` #### -Standard markdown syntax does not require a blank line before a header. +Standard Markdown syntax does not require a blank line before a header. Pandoc does require this (except, of course, at the beginning of the document). The reason for the requirement is that it is all too easy for a `#` to end up at the beginning of a line by accident (perhaps through line @@ -1232,11 +1504,11 @@ 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` + `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 @@ -1303,8 +1575,8 @@ Block quotations Markdown uses email conventions for quoting blocks of text. A block quotation is one or more paragraphs or other block elements (such as lists or headers), with each line preceded by a `>` character -and a space. (The `>` need not start at the left margin, but it should -not be indented more than three spaces.) +and an optional space. (The `>` need not start at the left margin, but +it should not be indented more than three spaces.) > This is a block quote. This > paragraph has two lines. @@ -1328,9 +1600,16 @@ other block quotes. That is, block quotes can be nested: > > > A block quote within a block quote. +If the `>` character is followed by an optional space, that space +will be considered part of the block quote marker and not part of +the indentation of the contents. Thus, to put an indented code +block in a block quote, you need five spaces after the `>`: + + > code + #### Extension: `blank_before_blockquote` #### -Standard markdown syntax does not require a blank line before a block +Standard Markdown syntax does not require a blank line before a block quote. Pandoc does require this (except, of course, at the beginning of the document). The reason for the requirement is that it is all too easy for a `>` to end up at the beginning of a line by accident (perhaps through line @@ -1364,7 +1643,7 @@ Note: blank lines in the verbatim text need not begin with four spaces. #### Extension: `fenced_code_blocks` #### -In addition to standard indented code blocks, Pandoc supports +In addition to standard indented code blocks, pandoc supports *fenced* code blocks. These begin with a row of three or more tildes (`~`) and end with a row of tildes that must be at least as long as the starting row. Everything between these lines is treated as code. No @@ -1449,7 +1728,7 @@ Line blocks A line block is a sequence of lines beginning with a vertical bar (`|`) followed by a space. The division into lines will be preserved in the output, as will any leading spaces; otherwise, the lines will -be formatted as markdown. This is useful for verse and addresses: +be formatted as Markdown. This is useful for verse and addresses: | The limerick packs laughs anatomical | In space that is quite economical. @@ -1503,7 +1782,7 @@ line (after the bullet): list item. * and my second. -But markdown also allows a "lazy" format: +But Markdown also allows a "lazy" format: * here is my first list item. @@ -1539,7 +1818,7 @@ one tab: + broccoli + chard -As noted above, markdown allows you to write list items "lazily," instead of +As noted above, Markdown allows you to write list items "lazily," instead of indenting continuation lines. However, if there are multiple paragraphs or other blocks in a list item, the first line of each must be indented. @@ -1553,18 +1832,18 @@ other blocks in a list item, the first line of each must be indented. list item. **Note:** Although the four-space rule for continuation paragraphs -comes from the official [markdown syntax guide], the reference implementation, +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 +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]: + [Markdown syntax guide]: http://daringfireball.net/projects/markdown/syntax#list ### Ordered lists ### @@ -1572,7 +1851,7 @@ pandoc interprets it that way. Ordered lists work just like bulleted lists, except that the items begin with enumerators rather than bullets. -In standard markdown, enumerators are decimal numbers followed +In standard Markdown, enumerators are decimal numbers followed by a period and a space. The numbers themselves are ignored, so there is no difference between this list: @@ -1588,7 +1867,7 @@ and this one: #### Extension: `fancy_lists` #### -Unlike standard markdown, Pandoc allows ordered list items to be marked +Unlike standard Markdown, pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to arabic numerals. List markers may be enclosed in parentheses or followed by a single right-parentheses or period. They must be separated from the @@ -1675,7 +1954,7 @@ A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. The body of the definition (including the first line, aside from the colon or tilde) should be indented four spaces. However, -as with other markdown lists, you can "lazily" omit indentation except +as with other Markdown lists, you can "lazily" omit indentation except at the beginning of a paragraph or other block element: Term 1 @@ -1701,13 +1980,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` #### @@ -1750,14 +2026,14 @@ cases" involving lists. Consider this source: + Third Pandoc transforms this into a "compact list" (with no `<p>` tags around -"First", "Second", or "Third"), while markdown puts `<p>` tags around +"First", "Second", or "Third"), while Markdown puts `<p>` tags around "Second" and "Third" (but not "First"), because of the blank space around "Third". Pandoc follows a simple rule: if the text is followed by a blank line, it is treated as a paragraph. Since "Second" is followed by a list, and not a blank line, it isn't treated as a paragraph. The fact that the list is followed by a blank line is irrelevant. (Note: Pandoc works this way even when the `markdown_strict` format is specified. This -behavior is consistent with the official markdown syntax description, +behavior is consistent with the official Markdown syntax description, even though it is different from that of `Markdown.pl`.) @@ -1770,7 +2046,7 @@ What if you want to put an indented code block after a list? { my code block } -Trouble! Here pandoc (like other markdown implementations) will treat +Trouble! Here pandoc (like other Markdown implementations) will treat `{ my code block }` as the second paragraph of item two, and not as a code block. @@ -1898,7 +2174,7 @@ These work like simple tables, but with the following differences: In multiline tables, the table parser pays attention to the widths of the columns, and the writers try to reproduce these relative widths in the output. So, if you find that one of the columns is too narrow in the -output, try widening it in the markdown source. +output, try widening it in the Markdown source. Headers may be omitted in multiline tables as well as simple tables: @@ -1939,7 +2215,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` #### @@ -1953,7 +2229,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 @@ -1975,10 +2251,7 @@ 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 +Note: pandoc also recognizes pipe tables of the following form, as can be produced by Emacs' orgtbl-mode: | One | Two | @@ -1990,6 +2263,8 @@ 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 --------------- @@ -2077,7 +2352,7 @@ hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots document, but if it is not at the beginning, it must be preceded by a blank line. (Note that, because of the way pandoc concatenates input files when several are provided, you may also keep the metadata in a separate YAML file -and pass it to pandoc as an argument, along with your markdown files: +and pass it to pandoc as an argument, along with your Markdown files: pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html @@ -2086,7 +2361,7 @@ Just be sure that the YAML file begins with `---` and ends with `---` or Metadata will be taken from the fields of the YAML object and added to any existing document metadata. Metadata can contain lists and objects (nested -arbitrarily), but all string scalars will be interpreted as markdown. Fields +arbitrarily), but all string scalars will be interpreted as Markdown. Fields with names ending in an underscore will be ignored by pandoc. (They may be given a role by external processors.) @@ -2094,7 +2369,7 @@ A document may contain multiple metadata blocks. The metadata fields will be combined through a *left-biased union*: if two metadata blocks attempt to set the same field, the value from the first block will be taken. -When pandoc is used with `-t markdown` to create a markdown document, +When pandoc is used with `-t markdown` to create a Markdown document, a YAML metadata block will be produced only if the `-s/--standalone` option is used. All of the metadata will appear in a single block at the beginning of the document. @@ -2121,7 +2396,7 @@ when the field contains blank lines: Template variables will be set automatically from the metadata. Thus, for example, in writing HTML, the variable `abstract` will be set to the HTML -equivalent of the markdown in the `abstract` field: +equivalent of the Markdown in the `abstract` field: <p>This is the abstract.</p> <p>It consists of two paragraphs.</p> @@ -2158,12 +2433,12 @@ instead of <strong>hello</strong> -This rule is easier to remember than standard markdown's rule, +This rule is easier to remember than standard Markdown's rule, which allows only the following characters to be backslash-escaped: \`*_{}[]()>#+-.! -(However, if the `markdown_strict` format is used, the standard markdown rule +(However, if the `markdown_strict` format is used, the standard Markdown rule will be used.) A backslash-escaped space is parsed as a nonbreaking space. It will @@ -2173,7 +2448,7 @@ appear in TeX output as `~` and in HTML and XML as `\ ` or A backslash-escaped newline (i.e. a backslash occurring at the end of a line) is parsed as a hard line break. It will appear in TeX output as `\\` and in HTML as `<br />`. This is a nice alternative to -markdown's "invisible" way of indicating hard line breaks using +Markdown's "invisible" way of indicating hard line breaks using two trailing spaces on a line. Backslash escapes do not work in verbatim contexts. @@ -2188,8 +2463,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 ----------------- @@ -2265,7 +2540,7 @@ of consecutive backticks (optionally followed by a space) and ends with a string of the same number of backticks (optionally preceded by a space). -Note that backslash-escapes (and other markdown constructs) do not +Note that backslash-escapes (and other Markdown constructs) do not work in verbatim contexts: This is a backslash followed by an asterisk: `\*`. @@ -2273,7 +2548,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} @@ -2302,12 +2577,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:[...]`. @@ -2328,8 +2602,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. @@ -2371,7 +2645,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 @@ -2389,6 +2663,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 -------- @@ -2397,7 +2673,7 @@ Raw HTML Markdown allows you to insert raw HTML (or DocBook) anywhere in a document (except verbatim contexts, where `<`, `>`, and `&` are interpreted literally). (Technically this is not an extension, since standard -markdown allows it, but it has been made an extension so that it can +Markdown allows it, but it has been made an extension so that it can be disabled if desired.) The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, @@ -2406,15 +2682,15 @@ formats. #### Extension: `markdown_in_html_blocks` #### -Standard markdown allows you to include HTML "blocks": blocks +Standard Markdown allows you to include HTML "blocks": blocks of HTML between balanced tags that are separated from the surrounding text with blank lines, and start and end at the left margin. Within -these blocks, everything is interpreted as HTML, not markdown; +these blocks, everything is interpreted as HTML, not Markdown; so (for example), `*` does not signify emphasis. Pandoc behaves this way when the `markdown_strict` format is used; but -by default, pandoc interprets material between HTML block tags as markdown. -Thus, for example, Pandoc will turn +by default, pandoc interprets material between HTML block tags as Markdown. +Thus, for example, pandoc will turn <table> <tr> @@ -2435,12 +2711,12 @@ into whereas `Markdown.pl` will preserve it as is. There is one exception to this rule: text between `<script>` and -`<style>` tags is not interpreted as markdown. +`<style>` tags is not interpreted as Markdown. -This departure from standard markdown should make it easier to mix -markdown with HTML block elements. For example, one can surround -a block of markdown text with `<div>` tags without preventing it -from being interpreted as markdown. +This departure from standard Markdown should make it easier to mix +Markdown with HTML block elements. For example, one can surround +a block of Markdown text with `<div>` tags without preventing it +from being interpreted as Markdown. #### Extension: `native_divs` #### @@ -2478,7 +2754,7 @@ Note that in LaTeX environments, like \end{tabular} the material between the begin and end tags will be interpreted as raw -LaTeX, not as markdown. +LaTeX, not as Markdown. Inline LaTeX is ignored in output formats other than Markdown, LaTeX, and ConTeXt. @@ -2574,7 +2850,7 @@ empty: [my website]: http://foo.bar.baz -Note: In `Markdown.pl` and most other markdown implementations, +Note: In `Markdown.pl` and most other Markdown implementations, reference link definitions cannot occur in nested constructions such as list items or block quotes. Pandoc lifts this arbitrary seeming restriction. So the following is fine in pandoc, though @@ -2596,8 +2872,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). @@ -2640,7 +2915,7 @@ 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: - \ + \ #### Extension: `common_link_attributes` #### @@ -2691,7 +2966,7 @@ Footnotes #### Extension: `footnotes` #### -Pandoc's markdown allows footnotes, using the following syntax: +Pandoc's Markdown allows footnotes, using the following syntax: Here is a footnote reference,[^1] and another.[^longnote] @@ -2763,17 +3038,35 @@ 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)); -and in CSL YAML databases, pandoc markdown. `pandoc-citeproc -j` and `-y` -interconvert these markup formats as far as possible. +In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc parses +a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown; and in CSL JSON databases, an [HTML-like markup][CSL markup specs]: + +`<i>...</i>` +: italics + +`<b>...</b>` +: bold + +`<span style="font-variant:small-caps;">...</span>` or `<sc>...</sc>` +: small capitals + +`<sub>...</sub>` +: subscript + +`<sup>...</sup>` +: superscript + +`<span class="nocase">...</span>` +: prevent a phrase from being capitalized as title case + +`pandoc-citeproc -j` and `-y` interconvert the CSL JSON +and CSL YAML formats as far as possible. As an alternative to specifying a bibliography file, you can include the citation data directly in the `references` field of the @@ -2809,13 +3102,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 @@ -2824,12 +3115,23 @@ a locator, and a suffix. The citation key must begin with a letter, digit, or `_`, and may contain alphanumerics, `_`, and internal punctuation characters (`:.#$%&-+?<>~/`). Here are some examples: - Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1]. + Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1]. Blah blah [@doe99, pp. 33-35, 38-39 and *passim*]. Blah blah [@smith04; @doe99]. +`pandoc-citeproc` detects locator terms in the [CSL locale files]. +Either abbreviated or unabbreviated forms are accepted. In the `en-US` +locale, locator terms can be written in either singular or plural forms, +as `book`, `bk.`/`bks.`; `chapter`, `chap.`/`chaps.`; `column`, +`col.`/`cols.`; `figure`, `fig.`/`figs.`; `folio`, `fol.`/`fols.`; +`number`, `no.`/`nos.`; `line`, `l.`/`ll.`; `note`, `n.`/`nn.`; `opus`, +`op.`/`opp.`; `page`, `p.`/`pp.`; `paragraph`, `para.`/`paras.`; `part`, +`pt.`/`pts.`; `section`, `sec.`/`secs.`; `sub verbo`, `s.v.`/`s.vv.`; +`verse`, `v.`/`vv.`; `volume`, `vol.`/`vols.`; `¶`/`¶¶`; `§`/`§§`. If no +locator term is used, "page" is assumed. + 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: @@ -2869,19 +3171,26 @@ 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 --------------------- -The following markdown syntax extensions are not enabled by default +The following Markdown syntax extensions are not enabled by default 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. +example, `markdown+hard_line_breaks` is Markdown with hard line breaks. #### Extension: `lists_without_preceding_blankline` #### @@ -2900,6 +3209,10 @@ treated as spaces or as hard line breaks. This option is intended for use with East Asian languages where spaces are not used between words, but text is divided into lines for readability. +#### Extension: `emoji` #### + +Parses textual emojis like `:smile:` as Unicode emoticons. + #### Extension: `tex_math_single_backslash` #### Causes anything between `\(` and `\)` to be interpreted as inline @@ -2915,8 +3228,8 @@ as display TeX math. #### Extension: `markdown_attribute` #### -By default, pandoc interprets material inside block-level tags as markdown. -This extension changes the behavior so that markdown is only parsed +By default, pandoc interprets material inside block-level tags as Markdown. +This extension changes the behavior so that Markdown is only parsed inside block-level tags if the tags have the attribute `markdown=1`. #### Extension: `mmd_title_block` #### @@ -2934,13 +3247,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 @@ -2976,7 +3289,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 @@ -3003,7 +3316,7 @@ in several respects: Markdown variants ----------------- -In addition to pandoc's extended markdown, the following markdown +In addition to pandoc's extended Markdown, the following Markdown variants are supported: `markdown_phpextra` (PHP Markdown Extra) @@ -3012,11 +3325,11 @@ variants are supported: `header_attributes`, `common_link_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`, - `intraword_underscores`, `strikeout`, `hard_line_breaks`, + `intraword_underscores`, `strikeout`, `hard_line_breaks`, `emoji`, `shortcut_reference_links`. `markdown_mmd` (MultiMarkdown) @@ -3030,11 +3343,11 @@ variants are supported: `markdown_strict` (Markdown.pl) : `raw_html` -Extensions with formats other than markdown +Extensions with formats other than Markdown ------------------------------------------- Some of the extensions discussed above can be used with formats -other than markdown: +other than Markdown: * `auto_identifiers` can be used with `latex`, `rst`, `mediawiki`, and `textile` input (and is used by default). @@ -3044,15 +3357,15 @@ other than markdown: (This is handy for reading web pages formatted using MathJax, for example.) -Producing slide shows with Pandoc +Producing slide shows with pandoc ================================= -You can use Pandoc to produce an HTML + javascript slide presentation +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`: +Here's the Markdown source for a simple slide show, `habits.txt`: % Habits % John Doe @@ -3097,7 +3410,7 @@ For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with the assumed to be available at the relative path `s5/default` (for S5), `slideous` (for Slideous), `reveal.js` (for reveal.js), or at the Slidy website at `w3.org` (for Slidy). (These paths can be changed by setting the `slidy-url`, -`slideous-url`, `revealjs-url`, or `s5-url` variables; see `--variable`, +`slideous-url`, `revealjs-url`, or `s5-url` variables; see [Variables for slides], above.) For DZSlides, the (relatively short) javascript and css are included in the file by default. @@ -3194,21 +3507,21 @@ files it does not find in the user data directory. For dzslides, the CSS is included in the HTML file itself, and may be modified there. -For reveal.js, themes can be used by setting the `theme` variable, -for example: +All [reveal.js configuration options] can be set through variables. +For example, themes can be used by setting the `theme` variable: -V theme=moon Or you can specify a custom stylesheet using the `--css` option. -To style beamer slides, you can specify a beamer "theme" or "colortheme" -using the `-V` option: +To style beamer slides, you can specify a `theme`, `colortheme`, +`fonttheme`, `innertheme`, and `outertheme`, using the `-V` option: pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf 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 @@ -3220,12 +3533,12 @@ Speaker notes ------------- reveal.js has good support for speaker notes. You can add notes to your -markdown document thus: +Markdown document thus: <div class="notes"> This is my note. - - It can contain markdown + - It can contain Markdown - like this list </div> @@ -3234,8 +3547,8 @@ 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. -Marking frames "fragile" in beamer ----------------------------------- +Frame attributes in beamer +-------------------------- Sometimes it is necessary to add the LaTeX `[fragile]` option to a frame in beamer (for example, when using the `minted` environment). @@ -3244,12 +3557,20 @@ introducing the slide: # Fragile slide {.fragile} +All of the other frame attributes described in Section 8.1 of +the [Beamer User's Guide] may also be used: `allowdisplaybreaks`, +`allowframebreaks`, `b`, `c`, `t`, `environment`, `label`, `plain`, +`shrink`. + +Creating EPUBs with pandoc +========================== + 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: @@ -3286,7 +3607,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. @@ -3297,8 +3618,8 @@ The following fields are recognized: ~ A string value in `YYYY-MM-DD` format. (Only the year is necessary.) Pandoc will attempt to convert other common date formats. -`language` - ~ A string value in [RFC5646] format. Pandoc will default to the local +`lang` (or legacy: `language`) + ~ A string value in [BCP 47] format. Pandoc will default to the local language if nothing is specified. `subject` @@ -3330,7 +3651,25 @@ 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 + +Linked media +------------ + +By default, pandoc will download linked media (including audio and +video) and include it in the EPUB container, yielding a completely +self-contained EPUB. If you want to link to external media resources +instead, use raw HTML in your source and add `data-external="1"` to the tag +with the `src` attribute. For example: + + <audio controls="1"> + <source src="http://example.com/music/toccata.mp3" + data-external="1" type="audio/mpeg"> + </source> + </audio> Literate Haskell support ======================== @@ -3340,15 +3679,16 @@ 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 - - In markdown input, "bird track" sections will be parsed as Haskell + - 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. + 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` + - 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 @@ -3370,7 +3710,7 @@ Examples: pandoc -f markdown+lhs -t html -reads literate Haskell source formatted with markdown conventions and writes +reads literate Haskell source formatted with Markdown conventions and writes ordinary HTML (without bird tracks). pandoc -f markdown+lhs -t html+lhs @@ -3381,10 +3721,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 @@ -3396,6 +3734,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 ============== @@ -3413,6 +3753,8 @@ which you can modify according to your needs, do pandoc --print-default-data-file sample.lua +[lua]: http://www.lua.org + Authors ======= @@ -3430,6 +3772,7 @@ Alfred Wechselberger, Andreas Lööw, Andrew Dunning, Antoine Latter, +Arata Mizuki, Arlo O'Keeffe, Artyom Kazak, Ben Gamari, @@ -3471,7 +3814,7 @@ Hans-Peter Deifel, Henry de Valence, Ilya V. Portnov, infinity0x, -Jaime Marquínez Ferrándiz, +Jaime Marquínez Ferrándiz, James Aspnes, Jamie F. Olson, Jan Larres, @@ -3546,46 +3889,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]: http://www.tex.ac.uk/CTAN/macros/latex/contrib/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 -[RFC5646]: http://tools.ietf.org/html/rfc5646 -[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 |