Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Merge pull request #2445 from adunning/patch-2

Browse source 
Improve links and cross-references in README.
This commit is contained in:
John MacFarlane 2015-10-09 23:24:33 -07:00
commit 087f8757b5
1 changed files with 306 additions and 215 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

521
README
View file

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