diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 534 |
1 files changed, 390 insertions, 144 deletions
@@ -1,6 +1,6 @@ % Pandoc User's Guide % John MacFarlane -% January 19, 2013 +% August 30, 2014 Synopsis ======== @@ -13,14 +13,16 @@ 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] and (subsets of) [Textile], [reStructuredText], [HTML], -[LaTeX], [MediaWiki markup], [Haddock markup], [OPML], and [DocBook]; and -it can write plain text, [markdown], [reStructuredText], [XHTML], [HTML 5], -[LaTeX] (including [beamer] slide shows), [ConTeXt], [RTF], [OPML], [DocBook], -[OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki markup], -[EPUB] (v2 or v3), [FictionBook2], [Textile], [groff man] pages, [Emacs -Org-Mode], [AsciiDoc], and [Slidy], [Slideous], [DZSlides], [reveal.js] -or [S5] HTML slide shows. It can also produce [PDF] output on systems -where LaTeX is installed. +[LaTeX], [MediaWiki markup], [TWiki markup], [Haddock markup], [OPML], +[Emacs Org-mode], [DocBook], [txt2tags], [EPUB] and [Word docx]; and +it can write plain text, [markdown], [reStructuredText], [XHTML], +[HTML 5], [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], [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, @@ -49,13 +51,23 @@ default (though output to *stdout* is disabled for the `odt`, `docx`, pandoc -o output.html input.txt +By default, pandoc produces a document fragment, not a standalone +document with a proper header and footer. To produce a standalone +document, use the `-s` or `--standalone` flag: + + pandoc -s -o output.html input.txt + +For more information on how standalone documents are produced, see +[Templates](#templates), below. + Instead of a file, an absolute URI may be given. In this case pandoc will fetch the content using HTTP: pandoc -f html -t markdown http://www.fsf.org If multiple input files are given, `pandoc` will concatenate them all (with -blank lines between them) before parsing. +blank lines between them) before parsing. This feature is disabled for + binary input formats such as `EPUB` and `docx`. The format of the input and output can be specified explicitly using command-line options. The input format can be specified using the @@ -93,6 +105,11 @@ should pipe input and output through `iconv`: iconv -t utf-8 input.txt | pandoc | iconv -f utf-8 +Note that in some output formats (such as HTML, LaTeX, ConTeXt, +RTF, OPML, DocBook, and Texinfo), information about +the character encoding is included in the document header, which +will only be included if you use the `-s/--standalone` option. + Creating a PDF -------------- @@ -143,14 +160,15 @@ General options `markdown_phpextra` (PHP Markdown Extra extended markdown), `markdown_github` (github extended markdown), `textile` (Textile), `rst` (reStructuredText), `html` (HTML), - `docbook` (DocBook), `opml` (OPML), `mediawiki` (MediaWiki 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 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` + `docbook` (DocBook), `t2t` (txt2tags), `docx` (docx), `epub` (EPUB), + `opml` (OPML), `org` (Emacs Org-mode), `mediawiki` (MediaWiki markup), + `twiki` (TWiki markup), `haddock` (Haddock markup), or `latex` (LaTeX). + If `+lhs` is appended to `markdown`, `rst`, + `latex`, or `html`, the input will be treated as literate Haskell + source: see [Literate Haskell support](#literate-haskell-support), + below. Markdown syntax extensions can be individually enabled or + disabled by appending `+EXTENSION` or `-EXTENSION` to the format + name. So, for example, `markdown_strict+footnotes+definition_lists` is strict markdown with footnotes and definition lists enabled, and `markdown-pipe_tables+hard_line_breaks` is pandoc's markdown without pipe tables and with hard line breaks. See [Pandoc's @@ -166,24 +184,25 @@ General options `rst` (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex` (LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt), `man` (groff man), `mediawiki` (MediaWiki markup), + `dokuwiki` (DokuWiki markup), `textile` (Textile), `org` (Emacs Org-Mode), `texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook), `opendocument` (OpenDocument), `odt` - (OpenOffice text document), `docx` (Word docx), - `rtf` (rich text format), `epub` (EPUB v2 book), `epub3` - (EPUB v3), `fb2` (FictionBook2 e-book), `asciidoc` (AsciiDoc), `slidy` - (Slidy HTML and javascript slide show), `slideous` (Slideous HTML and - javascript slide show), `dzslides` (DZSlides HTML5 + javascript slide - show), `revealjs` (reveal.js HTML5 + javascript slide show), `s5` - (S5 HTML and javascript slide show), or the path of a custom - lua writer (see [Custom writers](#custom-writers), below). Note that - `odt`, `epub`, and `epub3` output will not be directed to *stdout*; an - output filename must be specified using the `-o/--output` option. If - `+lhs` is appended to `markdown`, `rst`, `latex`, `beamer`, `html`, or - `html5`, the output will be rendered as literate Haskell source: see - [Literate Haskell support](#literate-haskell-support), below. Markdown - syntax extensions can be individually enabled or disabled by appending - `+EXTENSION` or `-EXTENSION` to the format name, as described above - under `-f`. + (OpenOffice text document), `docx` (Word docx), `haddock` (Haddock + markup), `rtf` (rich text format), `epub` (EPUB v2 book), `epub3` + (EPUB v3), `fb2` (FictionBook2 e-book), `asciidoc` (AsciiDoc), + `icml` (InDesign ICML), `slidy` (Slidy HTML and javascript slide show), + `slideous` (Slideous HTML and javascript slide show), `dzslides` + (DZSlides HTML5 + javascript slide show), `revealjs` (reveal.js + HTML5 + javascript slide show), `s5` (S5 HTML and javascript slide show), + or the path of a custom lua writer (see [Custom writers](#custom-writers), + below). Note that `odt`, `epub`, and `epub3` output will not be directed + to *stdout*; an output filename must be specified using the `-o/--output` + option. If `+lhs` is appended to `markdown`, `rst`, `latex`, `beamer`, + `html`, or `html5`, the output will be rendered as literate Haskell + source: see [Literate Haskell support](#literate-haskell-support), below. + Markdown syntax extensions can be individually enabled or disabled by + appending `+EXTENSION` or `-EXTENSION` to the format name, as described + above under `-f`. `-o` *FILE*, `--output=`*FILE* : Write output to *FILE* instead of *stdout*. If *FILE* is @@ -235,8 +254,8 @@ Reader options 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`, or `textile`. It - is selected automatically when the input format is `textile` or the + 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.) @@ -307,6 +326,23 @@ Reader options `--tab-stop=`*NUMBER* : Specify the number of spaces per tab (default is 4). +`--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 + 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` + classes, respectively. The author and time of change is + included. *all* is useful for scripting: only accepting changes + from a certain reviewer, say, or before a certain date. This + option only affects the docx reader. + +`--extract-media=`*DIR* +: Extract images and other media contained in a docx or epub container + to the path *DIR*, creating it if necessary, and adjust the images + references in the document so they point to the extracted files. + This option only affects the docx and epub readers. + General writer options ---------------------- @@ -403,10 +439,9 @@ Options affecting specific writers formats, including `html`, `html5`, `html+lhs`, `html5+lhs`, `s5`, `slidy`, `slideous`, `dzslides`, and `revealjs`. Scripts, images, and stylesheets at absolute URLs will be downloaded; those at relative URLs - will be sought first relative to the working directory, then relative to - the user data directory (see `--data-dir`), and finally relative to - pandoc's default data directory. `--self-contained` does not - work with `--mathjax`. + will be sought relative to the working directory (if the first source + file is local) or relative to the base URL (if the first source + file is remote). `--self-contained` does not work with `--mathjax`. `--offline` : Deprecated synonym for `--self-contained`. @@ -506,7 +541,7 @@ Options affecting specific writers `-c` *URL*, `--css=`*URL* : Link to a CSS style sheet. This option can be be used repeatedly to - include multiple files. They will be included in the order specified. + include multiple files. They will be included in the order specified. `--reference-odt=`*FILE* : Use the specified file as a style reference in producing an ODT. @@ -522,16 +557,17 @@ Options affecting specific writers : Use the specified file as a style reference in producing a docx file. For best results, the reference docx should be a modified version of a docx file produced using pandoc. The contents of the reference docx - are ignored, but its stylesheets are used in the new docx. If no + are ignored, but its stylesheets and document properties (including + margins, page size, header, and footer) are used in the new docx. If no reference docx is specified on the command line, pandoc will look for a file `reference.docx` in the user data directory (see `--data-dir`). If this is not found either, sensible defaults will be used. The following styles are used by pandoc: [paragraph] - Normal, Compact, Title, Authors, Date, Heading 1, Heading 2, Heading 3, - Heading 4, Heading 5, Block Quote, Definition Term, Definition, - Body Text, Table Caption, Image Caption; [character] Default - Paragraph Font, Body Text Char, Verbatim Char, Footnote Ref, - Link. + Normal, Compact, Title, Subtitle, Authors, Date, Abstract, Heading 1, + Heading 2, Heading 3, Heading 4, Heading 5, Block Quote, Definition Term, + Definition, Bibliography, Body Text, Table Caption, Image Caption; + [character] Default Paragraph Font, Body Text Char, Verbatim Char, + Footnote Ref, Link. `--epub-stylesheet=`*FILE* : Use the specified CSS file to style the EPUB. If no stylesheet @@ -632,10 +668,16 @@ Citation rendering `--metadata citation-abbreviations=FILE`.) `--natbib` -: Use natbib for citations in LaTeX output. +: 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. `--biblatex` -: Use biblatex for citations in LaTeX output. +: 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. Math rendering in HTML ---------------------- @@ -683,6 +725,16 @@ Math rendering in HTML formulas to images. The formula will be concatenated with the URL provided. If *URL* is not specified, the Google Chart API will be used. +`--katex`[=*URL*] +: Use [KaTeX] to display embedded TeX math in HTML output. + The *URL* should point to the `katex.js` load script. If a *URL* is + not provided, a link to the KaTeX CDN will be inserted. + +`--katex-stylesheet=*URL*` +: The *URL* should point to the `katex.css` stylesheet. If this option is + not specified, a link to the KaTeX CDN will be inserted. Note that this + option does not imply `--katex`. + Options for wrapper scripts --------------------------- @@ -748,65 +800,115 @@ as `title`, `author`, and `date`) as well as the following: `header-includes` : contents specified by `-H/--include-in-header` (may have multiple values) + `toc` : non-null value if `--toc/--table-of-contents` was specified + `include-before` : contents specified by `-B/--include-before-body` (may have multiple values) + `include-after` : contents specified by `-A/--include-after-body` (may have multiple values) + `body` : body of document + `lang` : language code for HTML or LaTeX documents + `slidy-url` : base URL for Slidy documents (defaults to `http://www.w3.org/Talks/Tools/Slidy2`) + `slideous-url` -: base URL for Slideous documents (defaults to `default`) +: base URL for Slideous documents (defaults to `slideous`) + `s5-url` -: base URL for S5 documents (defaults to `ui/default`) +: base URL for S5 documents (defaults to `s5/default`) + `revealjs-url` : base URL for reveal.js documents (defaults to `reveal.js`) + `theme` : reveal.js or LaTeX beamer theme + `transition` : reveal.js transition + `fontsize` : font size (10pt, 11pt, 12pt) for LaTeX documents + `documentclass` : document class for LaTeX documents + `classoption` : option for LaTeX documentclass, e.g. `oneside`; may be repeated for multiple options + `geometry` : options for LaTeX `geometry` class, e.g. `margin=1in`; may be repeated for multiple options + +`linestretch` +: adjusts line spacing (requires the `setspace` package) + +`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. + `mainfont`, `sansfont`, `monofont`, `mathfont` : fonts for LaTeX documents (works only with xelatex and lualatex) + `colortheme` : colortheme for LaTeX beamer documents + `fonttheme` : fonttheme for LaTeX beamer documents + `linkcolor` : color for internal links in LaTeX documents (`red`, `green`, `magenta`, `cyan`, `blue`, `black`) + `urlcolor` : color for external links in LaTeX documents + `citecolor` : color for citation links in LaTeX documents + `links-as-notes` : causes links to be printed as footnotes in LaTeX documents + +`toc` +: include table of contents in LaTeX documents + +`toc-depth` +: level of section to include in table of contents in LaTeX documents + +`lof` +: include list of figures in LaTeX documents + +`lot` +: include list of tables in LaTeX documents + `biblio-style` : bibliography style in LaTeX, when used with `--natbib` + `biblio-files` : bibliography files to use in LaTeX, with `--natbib` or `--biblatex` + `section` : section number in man pages + `header` : header in man pages + `footer` : footer in man pages @@ -893,7 +995,7 @@ A paragraph is one or more lines of text followed by one or more blank line. Newlines are treated as spaces, so you can reflow your paragraphs as you like. If you need a hard line break, put two or more spaces at the end of a line. -**Extension: `escaped_line_breaks`** +#### Extension: `escaped_line_breaks` #### A backslash followed by a newline is also a hard line break. Note: in multiline and grid table cells, this is the only way @@ -934,7 +1036,7 @@ As with setext-style headers, the header text can contain formatting: # A level-one header with a [link](/url) and *emphasis* -**Extension: `blank_before_header`** +#### Extension: `blank_before_header` #### Standard markdown syntax does not require a blank line before a header. Pandoc does require this (except, of course, at the beginning of the @@ -948,17 +1050,15 @@ wrapping). Consider, for example: ### Header identifiers in HTML, LaTeX, and ConTeXt ### -**Extension: `header_attributes`** +#### Extension: `header_attributes` #### Headers can be assigned attributes using this syntax at the end of the line containing the header text: {#identifier .class .class key=value key=value} -Although this syntax allows assignment of classes and key/value attributes, -only identifiers currently have any affect in the writers (and only in some -writers: HTML, LaTeX, ConTeXt, Textile, AsciiDoc). Thus, for example, -the following headers will all be assigned the identifier `foo`: +Thus, for example, the following headers will all be assigned the identifier +`foo`: # My header {#foo} @@ -969,6 +1069,12 @@ the following headers will all be assigned the identifier `foo`: (This syntax is compatible with [PHP Markdown Extra].) +Note that although this syntax allows assignment of classes and key/value +attributes, writers generally don't use all of this information. Identifiers, +classes, and key/value attributes are used in HTML and HTML-based formats such +as EPUB and slidy. Identifiers are used for labels and link anchors in the +LaTeX, ConTeXt, Textile, and AsciiDoc writers. + Headers with the class `unnumbered` will not be numbered, even if `--number-sections` is specified. A single hyphen (`-`) in an attribute context is equivalent to `.unnumbered`, and preferable in non-English @@ -980,7 +1086,7 @@ is just the same as # My header {.unnumbered} -**Extension: `auto_identifiers`** +#### Extension: `auto_identifiers` #### A header without an explicitly specified identifier will be automatically assigned a unique identifier based on the header text. @@ -1029,7 +1135,7 @@ and the identifier will be attached to the enclosing `<div>` sections to be manipulated using javascript or treated differently in CSS. -**Extension: `implicit_header_references`** +#### Extension: `implicit_header_references` #### Pandoc behaves as if reference links have been defined for each header. So, instead of @@ -1088,7 +1194,7 @@ other block quotes. That is, block quotes can be nested: > > > A block quote within a block quote. -**Extension: `blank_before_blockquote`** +#### Extension: `blank_before_blockquote` #### Standard markdown syntax does not require a blank line before a block quote. Pandoc does require this (except, of course, at the beginning of the @@ -1122,7 +1228,7 @@ Note: blank lines in the verbatim text need not begin with four spaces. ### Fenced code blocks ### -**Extension: `fenced_code_blocks`** +#### Extension: `fenced_code_blocks` #### In addition to standard indented code blocks, Pandoc supports *fenced* code blocks. These begin with a row of three or more @@ -1148,6 +1254,8 @@ row of tildes or backticks at the start and end: ~~~~~~~~~~ ~~~~~~~~~~~~~~~~ +#### Extension: `fenced_code_attributes` #### + Optionally, you may attach attributes to the code block using this syntax: @@ -1184,13 +1292,18 @@ This is equivalent to: qsort [] = [] ``` +If the `fenced_code_attributes` extension is disabled, but +input contains class attribute(s) for the codeblock, the first +class attribute will be printed after the opening fence as a bare +word. + To prevent all highlighting, use the `--no-highlight` flag. To set the highlighting style, use `--highlight-style`. Line blocks ----------- -**Extension: `line_blocks`** +#### Extension: `line_blocks` #### A line block is a sequence of lines beginning with a vertical bar (`|`) followed by a space. The division into lines will be preserved in @@ -1332,7 +1445,7 @@ and this one: 7. two 1. three -**Extension: `fancy_lists`** +#### Extension: `fancy_lists` #### Unlike standard markdown, Pandoc allows ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to @@ -1363,7 +1476,7 @@ ordered list marker in place of a numeral: #. one #. two -**Extension: `startnum`** +#### Extension: `startnum` #### Pandoc also pays attention to the type of list marker used, and to the starting number, and both of these are preserved where possible in the @@ -1395,10 +1508,10 @@ If default list markers are desired, use `#.`: ### Definition lists ### -**Extension: `definition_lists`** +#### Extension: `definition_lists` #### -Pandoc supports definition lists, using a syntax inspired by -[PHP Markdown Extra] and [reStructuredText]:[^3] +Pandoc supports definition lists, using the syntax of +[PHP Markdown Extra] with some extensions.[^3] Term 1 @@ -1415,32 +1528,48 @@ Pandoc supports definition lists, using a syntax inspired by Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one -or two spaces. The body of the definition (including the first line, -aside from the colon or tilde) should be indented four spaces. A term may have -multiple definitions, and each definition may consist of one or more block -elements (paragraph, code block, list, etc.), each indented four spaces or one -tab stop. - -If you leave space after the definition (as in the example above), -the blocks of the definitions will be considered paragraphs. In some +or two spaces. + +A term may have multiple definitions, and each definition may consist of one or +more block elements (paragraph, code block, list, etc.), each indented four +spaces or one tab stop. The body of the definition (including the first line, +aside from the colon or tilde) should be indented four spaces. However, +as with other markdown lists, you can "lazily" omit indentation except +at the beginning of a paragraph or other block element: + + Term 1 + + : Definition + with lazy continuation. + + Second paragraph of the definition. + +If you leave space before the definition (as in the example above), +the text of the definition will be treated as a paragraph. In some output formats, this will mean greater spacing between term/definition -pairs. For a compact definition list, do not leave space between the -definition and the next term: +pairs. For a more compact definition list, omit the space before the +definition: Term 1 ~ Definition 1 + Term 2 ~ Definition 2a ~ Definition 2b -[^3]: I have also been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html). +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.) + +[^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`** +#### Extension: `example_lists` #### The special list marker `@` can be used for sequentially numbered examples. The first list item with a `@` marker will be numbered '1', @@ -1546,9 +1675,14 @@ Four kinds of tables may be used. The first three kinds presuppose the use of a fixed-width font, such as Courier. The fourth kind can be used with proportionally spaced fonts, as it does not require lining up columns. -### Simple tables +#### Extension: `table_captions` #### + +A caption may optionally be provided with all 4 kinds of tables (as +illustrated in the examples below). A caption is a paragraph beginning +with the string `Table:` (or just `:`), which will be stripped off. +It may appear either before or after the table. -**Extension: `simple_tables`, `table_captions`** +#### Extension: `simple_tables` #### Simple tables look like this: @@ -1577,10 +1711,7 @@ to the dashed line below it:[^4] [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html). The table must end with a blank line, or a line of dashes followed by -a blank line. A caption may optionally be provided (as illustrated in -the example above). A caption is a paragraph beginning with the string -`Table:` (or just `:`), which will be stripped off. It may appear either -before or after the table. +a blank line. The column headers may be omitted, provided a dashed line is used to end the table. For example: @@ -1595,9 +1726,7 @@ When headers are omitted, column alignments are determined on the basis of the first line of the table body. So, in the tables above, the columns would be right, left, center, and right aligned, respectively. -### Multiline tables - -**Extension: `multiline_tables`, `table_captions`** +#### Extension: `multiline_tables` #### Multiline tables allow headers and table rows to span multiple lines of text (but cells that span multiple columns or rows of the table are @@ -1647,9 +1776,7 @@ It is possible for a multiline table to have just one row, but the row should be followed by a blank line (and then the row of dashes that ends the table), or the table may be interpreted as a simple table. -### Grid tables - -**Extension: `grid_tables`, `table_captions`** +#### Extension: `grid_tables` #### Grid tables look like this: @@ -1673,9 +1800,7 @@ columns or rows. Grid tables can be created easily using [Emacs table mode]. [Emacs table mode]: http://table.sourceforge.net/ -### Pipe tables - -**Extension: `pipe_tables`, `table_captions`** +#### Extension: `pipe_tables` #### Pipe tables look like this: @@ -1685,7 +1810,7 @@ Pipe tables look like this: | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 | - : Demonstration of simple table syntax. + : Demonstration of pipe table syntax. The syntax is [the same as in PHP markdown extra]. The beginning and ending pipe characters are optional, but pipes are required between all @@ -1704,7 +1829,10 @@ legal (though ugly) pipe table: orange|3.09 The cells of pipe tables cannot contain block elements like paragraphs -and lists, and cannot span multiple lines. +and lists, and cannot span multiple lines. Note also that in LaTeX/PDF +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 @@ -1721,10 +1849,10 @@ 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. -Title block ------------ +Metadata blocks +--------------- -**Extension: `pandoc_title_block`** +#### Extension: `pandoc_title_block` #### If the file begins with a title block @@ -1800,16 +1928,20 @@ will also have "Pandoc User Manuals" in the footer. will also have "Version 4.0" in the header. -YAML metadata block -------------------- - -**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 (`...`) at the bottom. A YAML metadata block may occur anywhere in the document, but if it is not at the beginning, it must be preceded by a blank -line. +line. (Note that, because of the way pandoc concatenates input files when +several are provided, you may also keep the metadata in a separate YAML file +and pass it to pandoc as an argument, along with your markdown files: + + pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html + +Just be sure that the YAML file begins with `---` and ends with `---` or +`...`.) Metadata will be taken from the fields of the YAML object and added to any existing document metadata. Metadata can contain lists and objects (nested @@ -1821,6 +1953,11 @@ A document may contain multiple metadata blocks. The metadata fields will be combined through a *left-biased union*: if two metadata blocks attempt to set the same field, the value from the first block will be taken. +When pandoc is used with `-t markdown` to create a markdown document, +a YAML metadata block will be produced only if the `-s/--standalone` +option is used. All of the metadata will appear in a single block +at the beginning of the document. + Note that YAML escaping rules must be followed. Thus, for example, if a title contains a colon, it must be quoted. The pipe character (`|`) can be used to begin an indented block that will be interpreted @@ -1864,7 +2001,7 @@ custom template. For example: Backslash escapes ----------------- -**Extension: `all_symbols_escapable`** +#### Extension: `all_symbols_escapable` #### Except inside a code block or inline code, any punctuation or space character preceded by a backslash will be treated literally, even if it @@ -1903,7 +2040,7 @@ Backslash escapes do not work in verbatim contexts. Smart punctuation ----------------- -**Extension** +#### Extension #### If the `--smart` option is specified, pandoc will produce typographically correct output, converting straight quotes to curly quotes, `---` to @@ -1932,7 +2069,7 @@ will not trigger emphasis: This is * not emphasized *, and \*neither is this\*. -**Extension: `intraword_underscores`** +#### Extension: `intraword_underscores` #### Because `_` is sometimes used inside words and identifiers, pandoc does not interpret a `_` surrounded by alphanumeric @@ -1944,7 +2081,7 @@ just part of a word, use `*`: ### Strikeout ### -**Extension: `strikeout`** +#### Extension: `strikeout` #### To strikeout a section of text with a horizontal line, begin and end it with `~~`. Thus, for example, @@ -1954,7 +2091,7 @@ with `~~`. Thus, for example, ### Superscripts and subscripts ### -**Extension: `superscript`, `subscript`** +#### Extension: `superscript`, `subscript` #### Superscripts may be written by surrounding the superscripted text by `^` characters; subscripts may be written by surrounding the subscripted @@ -1992,21 +2129,31 @@ work in verbatim contexts: This is a backslash followed by an asterisk: `\*`. -**Extension: `inline_code_attributes`** +#### Extension: `inline_code_attributes` #### Attributes can be attached to verbatim text, just as with [fenced code blocks](#fenced-code-blocks): `<$>`{.haskell} +### Small caps ### + +To write small caps, you can use an HTML span tag: + + <span style="font-variant:small-caps;">Small caps</span> + +(The semicolon is optional and there may be space after the +colon.) This will work in all output formats that support small caps. + Math ---- -**Extension: `tex_math_dollars`** +#### Extension: `tex_math_dollars` #### Anything between two `$` characters will be treated as TeX math. The -opening `$` must have a character immediately to its right, while the -closing `$` must have a character immediately to its left. Thus, +opening `$` must have a non-space character immediately to its right, +while the closing `$` must have a non-space character immediately to its +left, and must not be followed immediately by a digit. Thus, `$20,000 and $30,000` won't parse as math. If for some reason you need to enclose text in literal `$` characters, backslash-escape them and they won't be treated as math delimiters. @@ -2030,7 +2177,7 @@ Texinfo groff man ~ It will be rendered verbatim without `$`'s. -MediaWiki +MediaWiki, DokuWiki ~ It will be rendered inside `<math>` tags. Textile @@ -2104,7 +2251,7 @@ HTML, Slidy, DZSlides, S5, EPUB Raw HTML -------- -**Extension: `raw_html`** +#### Extension: `raw_html` #### Markdown allows you to insert raw HTML (or DocBook) anywhere in a document (except verbatim contexts, where `<`, `>`, and `&` are interpreted @@ -2116,7 +2263,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 @@ -2154,10 +2301,24 @@ 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` #### + +Use native pandoc `Div` blocks for content inside `<div>` tags. +For the most part this should give the same output as +`markdown_in_html_blocks`, but it makes it easier to write pandoc +filters to manipulate groups of blocks. + +#### Extension: `native_spans` #### + +Use native pandoc `Span` blocks for content inside `<span>` tags. +For the most part this should give the same output as `raw_html`, +but it makes it easier to write pandoc filters to manipulate groups +of inlines. + Raw TeX ------- -**Extension: `raw_tex`** +#### Extension: `raw_tex` #### In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be included in a document. Inline TeX commands will be preserved and passed @@ -2184,7 +2345,7 @@ and ConTeXt. LaTeX macros ------------ -**Extension: `latex_macros`** +#### Extension: `latex_macros` #### For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and `\renewcommand` definitions and apply the resulting macros to all LaTeX @@ -2224,6 +2385,10 @@ be followed by a link title, in quotes.) There can be no space between the bracketed part and the parenthesized part. The link text can contain formatting (such as emphasis), but the title cannot. +Email addresses in inline links are not autodetected, so they have to be +prefixed with `mailto`: + + [Write me!](mailto:sam@green.eggs.ham) ### Reference links ### @@ -2276,7 +2441,7 @@ not in most other implementations: > > [quote]: /foo -### Internal links +### Internal links ### To link to another section of the same document, use the automatically generated identifier (see [Header identifiers in HTML, LaTeX, and @@ -2306,9 +2471,7 @@ The link text will be used as the image's alt text: [movie reel]: movie.gif -### Pictures with captions ### - -**Extension: `implicit_figures`** +#### Extension: `implicit_figures` #### An image occurring by itself in a paragraph will be rendered as a figure with a caption.[^5] (In LaTeX, a figure environment will be @@ -2332,7 +2495,7 @@ nonbreaking space after the image: Footnotes --------- -**Extension: `footnotes`** +#### Extension: `footnotes` #### Pandoc's markdown allows footnotes, using the following syntax: @@ -2363,7 +2526,7 @@ The footnotes themselves need not be placed at the end of the document. They may appear anywhere except inside other block elements (lists, block quotes, tables, etc.). -**Extension: `inline_notes`** +#### Extension: `inline_notes` #### Inline footnotes are also allowed (though, unlike regular notes, they cannot contain multiple paragraphs). The syntax is as follows: @@ -2378,7 +2541,7 @@ Inline and regular footnotes may be mixed freely. Citations --------- -**Extension: `citations`** +#### Extension: `citations` #### Using an external filter, `pandoc-citeproc`, pandoc can automatically generate citations and a bibliography in a number of styles. Basic usage is @@ -2443,7 +2606,9 @@ can be found at <https://github.com/citation-style-language/styles>. See also Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of '@' + the citation identifier from the database, and may optionally have a prefix, -a locator, and a suffix. Here are some examples: +a locator, and a suffix. The citation key must begin with a letter +or `_`, and may contain alphanumerics, `_`, and internal punctuation +characters (`:.#$%&-+?<>~/`). Here are some examples: Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1]. @@ -2471,7 +2636,24 @@ document with an appropriate header: # References -The bibliography will be inserted after this header. +The bibliography will be inserted after this header. Note that +the `unnumbered` class will be added to this header, so that the +section will not be numbered. + +If you want to include items in the bibliography without actually +citing them in the body text, you can define a dummy `nocite` metadata +field and put the citations there: + + --- + nocite: | + @item1, @item2 + ... + + @item3 + +In this example, the document will contain a citation for `item3` +only, but the bibliography will contain entries for `item1`, `item2`, and +`item3`. Non-pandoc extensions --------------------- @@ -2481,37 +2663,44 @@ in pandoc, but may be enabled by adding `+EXTENSION` to the format name, where `EXTENSION` is the name of the extension. Thus, for example, `markdown+hard_line_breaks` is markdown with hard line breaks. -**Extension: `lists_without_preceding_blankline`**\ +#### Extension: `lists_without_preceding_blankline` #### + Allow a list to occur right after a paragraph, with no intervening blank space. -**Extension: `hard_line_breaks`**\ +#### Extension: `hard_line_breaks` #### + Causes all newlines within a paragraph to be interpreted as hard line breaks instead of spaces. -**Extension: `ignore_line_breaks`**\ +#### Extension: `ignore_line_breaks` #### + Causes newlines within a paragraph to be ignored, rather than being 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: `tex_math_single_backslash`**\ +#### Extension: `tex_math_single_backslash` #### + Causes anything between `\(` and `\)` to be interpreted as inline TeX math, and anything between `\[` and `\]` to be interpreted as display TeX math. Note: a drawback of this extension is that it precludes escaping `(` and `[`. -**Extension: `tex_math_double_backslash`**\ +#### Extension: `tex_math_double_backslash` #### + Causes anything between `\\(` and `\\)` to be interpreted as inline TeX math, and anything between `\\[` and `\\]` to be interpreted as display TeX math. -**Extension: `markdown_attribute`**\ +#### 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 inside block-level tags if the tags have the attribute `markdown=1`. -**Extension: `mmd_title_block`**\ +#### Extension: `mmd_title_block` #### + Enables a [MultiMarkdown] style title block at the top of the document, for example: @@ -2527,7 +2716,8 @@ See the MultiMarkdown documentation for details. If `pandoc_title_block` or [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/ -**Extension: `abbreviations`**\ +#### Extension: `abbreviations` #### + Parses PHP Markdown Extra abbreviation keys, like *[HTML]: Hyper Text Markup Language @@ -2536,24 +2726,55 @@ Note that the pandoc document model does not support abbreviations, so if this extension is enabled, abbreviation keys are simply skipped (as opposed to being parsed as paragraphs). -**Extension: `autolink_bare_uris`**\ +#### Extension: `autolink_bare_uris` #### + Makes all absolute URIs into links, even when not surrounded by pointy braces `<...>`. -**Extension: `ascii_identifiers`**\ +#### Extension: `ascii_identifiers` #### + Causes the identifiers produced by `auto_identifiers` to be pure ASCII. Accents are stripped off of accented latin letters, and non-latin letters are omitted. -**Extension: `link_attributes`**\ +#### Extension: `link_attributes` #### + Parses multimarkdown style key-value attributes on link and image references. Note that pandoc's internal document model provides nowhere to put these, so they are presently just ignored. -**Extension: `mmd_header_identifiers`**\ +#### Extension: `mmd_header_identifiers` #### + Parses multimarkdown style header identifiers (in square brackets, 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) +in several respects: + + - No blank line is required between consecutive items of the + definition list. + - To get a "tight" or "compact" list, omit space between consecutive + items; the space between a term and its definition does not affect + anything. + - Lazy wrapping of paragraphs is not allowed: the entire definition must + be indented four spaces.[^6] + +[^6]: To see why laziness is incompatible with relaxing the requirement + of a blank line between items, consider the following example: + + bar + : definition + foo + : definition + + Is this a single list item with two definitions of "bar," the first of + which is lazily wrapped, or two list items? To remove the ambiguity + we must either disallow lazy wrapping or require a blank line between + list items. + Markdown variants ----------------- @@ -2567,7 +2788,7 @@ variants are supported: `markdown_github` (Github-flavored Markdown) : `pipe_tables`, `raw_html`, `tex_math_single_backslash`, - `fenced_code_blocks`, `fenced_code_attributes`, `auto_identifiers`, + `fenced_code_blocks`, `auto_identifiers`, `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`, `intraword_underscores`, `strikeout`, `hard_line_breaks` @@ -2807,7 +3028,7 @@ block. Here is an example: - scheme: DOI text: doi:10.234234.234/33 publisher: My Press - rights: (c) 2007 John Smith, CC BY-NC + rights: © 2007 John Smith, CC BY-NC ... The following fields are recognized: @@ -2818,43 +3039,61 @@ The following fields are recognized: `GTIN-13`, `UPC`, `ISMN-10`, `DOI`, `LCCN`, `GTIN-14`, `ISBN-13`, `Legal deposit number`, `URN`, `OCLC`, `ISMN-13`, `ISBN-A`, `JP`, `OLCC`. + `title` ~ Either a string value, or an object with fields `file-as` and `type`, or a list of such objects. Valid values for `type` are `main`, `subtitle`, `short`, `collection`, `edition`, `extended`. + `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 pandoc will attempt to translate the human-readable versions (like "author" and "editor") to the appropriate marc relators. + `contributor` ~ Same format as `creator`. + `date` ~ 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 language if nothing is specified. + `subject` ~ A string value or a list of such values. + `description` ~ A string value. + `type` ~ A string value. + `format` ~ A string value. + `relation` ~ A string value. + `coverage` ~ A string value. + `rights` ~ A string value. + `cover-image` ~ A string value (path to cover image). + `stylesheet` ~ A string value (path to CSS stylesheet). +`page-progression-direction` + ~ Either `ltr` or `rtl`. Specifies the `page-progression-direction` + spine [attribute][EPUBspine]. + Literate Haskell support ======================== @@ -2931,7 +3170,8 @@ Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner, qerub, Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine Latter, Ralf Stephan, Eric Seidel, B. Scott Michel, Gavin Beatty, Sergey Astanin, Arlo O'Keeffe, Denis Laxalde, Brent Yorgey, David Lazar, -Jamie F. Olson. +Jamie F. Olson, Matthew Pickering, Albert Krewinkel, mb21, Jesse +Rosenthal. [markdown]: http://daringfireball.net/projects/markdown/ [reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html @@ -2951,13 +3191,14 @@ Jamie F. Olson. [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/ -[EPUB]: http://www.idpf.org/ [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 @@ -2968,3 +3209,8 @@ Jamie F. Olson. [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 |