logo izquierdo de la pagina

PANDOC MANUAL

logo de la pagina

[<][<=][=>]Pandoc User's Guide

Synopsis
Description
    Using pandoc
    Specifying formats
    Character encoding
    Creating a PDF
    Reading from the Web
Options
    General options
    Reader options
    General writer options
    Options affecting specific writers
    Citation rendering
    Math rendering in HTML
    Options for wrapper scripts
Templates
    Metadata variables
    Language variables
    Variables for HTML slides
    Variables for Beamer slides
    Variables for LaTeX
        Layout
        Fonts
        Links
        Front matter
        BibLaTeX Bibliographies
    Variables for ConTeXt
    Variables for wkhtmltopdf
    Variables for man pages
    Variables for ms
    Structural variables
    Using variables in templates
Extensions
    Typography
            Extension: smart
    Headings and sections
            Extension: auto_identifiers
            Extension: ascii_identifiers
            Extension: gfm_auto_identifiers
    Math Input
    Raw HTML/TeX
            Extension: raw_html
            Extension: raw_tex
            Extension: native_divs
            Extension: native_spans
    Literate Haskell support
            Extension: literate_haskell
    Other extensions
            Extension: empty_paragraphs
            Extension: styles
            Extension: amuse
            Extension: citations
            Extension: ntb
Pandoc's Markdown
    Philosophy
    Paragraphs
            Extension: escaped_line_breaks
    Headings
        Setext-style headings
        ATX-style headings
            Extension: blank_before_header
            Extension: space_in_atx_header
        Heading identifiers
            Extension: header_attributes
            Extension: implicit_header_references
    Block quotations
            Extension: blank_before_blockquote
    Verbatim (code) blocks
        Indented code blocks
        Fenced code blocks
            Extension: fenced_code_blocks
            Extension: backtick_code_blocks
            Extension: fenced_code_attributes
    Line blocks
            Extension: line_blocks
    Lists
        Bullet lists
        Block content in list items
        Ordered lists
            Extension: fancy_lists
            Extension: startnum
            Extension: task_lists
        Definition lists
            Extension: definition_lists
        Numbered example lists
            Extension: example_lists
        Compact and loose lists
        Ending a list
    Horizontal rules
    Tables
            Extension: table_captions
            Extension: simple_tables
            Extension: multiline_tables
            Extension: grid_tables
                Grid Table Limitations
            Extension: pipe_tables
    Metadata blocks
            Extension: pandoc_title_block
            Extension: yaml_metadata_block
    Backslash escapes
            Extension: all_symbols_escapable
    Inline formatting
        Emphasis
            Extension: intraword_underscores
        Strikeout
            Extension: strikeout
        Superscripts and subscripts
            Extension: superscript, subscript
        Verbatim
            Extension: inline_code_attributes
        Small caps
    Math
            Extension: tex_math_dollars
    Raw HTML
            Extension: raw_html
            Extension: markdown_in_html_blocks
            Extension: native_divs
            Extension: native_spans
            Extension: raw_tex
        Generic raw attribute
            Extension: raw_attribute
    LaTeX macros
            Extension: latex_macros
    Links
        Automatic links
        Inline links
        Reference links
            Extension: shortcut_reference_links
        Internal links
    Images
            Extension: implicit_figures
            Extension: link_attributes
    Divs and Spans
            Extension: fenced_divs
            Extension: bracketed_spans
    Footnotes
            Extension: footnotes
            Extension: inline_notes
    Citations
            Extension: citations
    Non-pandoc extensions
            Extension: old_dashes
            Extension: angle_brackets_escapable
            Extension: lists_without_preceding_blankline
            Extension: four_space_rule
            Extension: spaced_reference_links
            Extension: hard_line_breaks
            Extension: ignore_line_breaks
            Extension: east_asian_line_breaks
            Extension: emoji
            Extension: tex_math_single_backslash
            Extension: tex_math_double_backslash
            Extension: markdown_attribute
            Extension: mmd_title_block
            Extension: abbreviations
            Extension: autolink_bare_uris
            Extension: mmd_link_attributes
            Extension: mmd_header_identifiers
            Extension: compact_definition_lists
    Markdown variants
Producing slide shows with pandoc
    Structuring the slide show
    Incremental lists
    Inserting pauses
    Styling the slides
    Speaker notes
    Columns
    Frame attributes in beamer
    Background in reveal.js and beamer
Creating EPUBs with pandoc
    EPUB Metadata
    The epub:type attribute
    Linked media
Creating Jupyter notebooks with pandoc
Syntax highlighting
Custom Styles
    Output
    Input
Custom writers
A note on security
Authors

[<][<=][=>][*]


W adorno

Templates

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*

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 directory (see --data-dir, above). Exceptions:

  • For odt output, customize the default.opendocument template.
  • For pdf output, customize the default.latex template (or the default.context template, if you use -t context, or the default.ms template, if you use -t ms, or the default.html template, if you use -t html).
  • docx and pptx have no template (however, you can use --reference-doc to customize the output).

Templates contain variables, which allow for the inclusion of arbitrary information at any point in the file. They may be set at the command line using the -V/--variable option. If a variable is not set, pandoc will look for the key in the document's metadata â€' which can be set using either YAML metadata blocks or with the -M/--metadata option.

Metadata variables

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, which allows for multiple authors, or through a YAML metadata block:

---
author:
- Aristotle
- Peter Abelard
...

Note that if you just want to set PDF or HTML metadata, without including a title block in the document itself, you can set the title-meta, author-meta, and date-meta variables. (By default these are set automatically, based on title, author, and date.)

subtitle

document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx documents

abstract

document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx documents

keywords

list of keywords to be included in HTML, PDF, ODT, pptx, docx and AsciiDoc metadata; repeat as for author, above

subject

document subject, included in ODT, PDF, docx and pptx metadata

description

document description, included in ODT, docx and pptx metadata. Some applications show this as Comments metadata.

category

document category, included in docx and pptx metadata

Additionally, any root-level string metadata, not included in ODT, docx or pptx metadata is added as a custom property. The following YAML metadata block for instance:

---
title:  'This is the title'
subtitle: "This is the subtitle"
author:
- Author One
- Author Two
description: |
    This is a long
    description.

    It consists of two paragraphs
...

will include title, author and description as standard document properties and subtitle as a custom property when converting to docx, ODT or pptx.

Language variables

lang

identifies the main language of the document using IETF language tags (following the BCP 47 standard), such as en or en-GB. The Language subtag lookup tool can look up or verify these tags. This affects most formats, and controls hyphenation in PDF output when using LaTeX (through babel and polyglossia) or ConTeXt.

Use native pandoc Divs and Spans with the lang attribute to switch the language:

---
lang: en-GB
...

Text in the main document language (British English).

::: {lang=fr-CA}
> Cette citation est écrite en français canadien.
:::

More text in English. ['Zitat auf Deutsch.']{lang=de}
dir

the base script direction, either rtl (right-to-left) or ltr (left-to-right).

For bidirectional documents, native pandoc spans and divs 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 --pdf-engine=xelatex).

Variables for HTML slides

These affect HTML output when [producing slide shows with pandoc]. All reveal.js configuration options are available as variables.

revealjs-url

base URL for reveal.js documents (defaults to reveal.js)

s5-url

base URL for S5 documents (defaults to s5/default)

slidy-url

base URL for Slidy documents (defaults to https://www.w3.org/Talks/Tools/Slidy2)

slideous-url

base URL for Slideous documents (defaults to slideous)

Variables for Beamer slides

These variables change the appearance of PDF slides using beamer.

aspectratio

slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)

beamerarticle

produce an article from Beamer slides

beameroption

add extra beamer option with \setbeameroption{}

institute

author affiliations: can be a list when there are multiple authors

logo

logo image for slides

navigation

controls navigation symbols (default is empty for no navigation symbols; other valid values are frame, vertical, and horizontal)

section-titles

enables "title pages" for new sections (default is true)

theme, colortheme, fonttheme, innertheme, outertheme

beamer themes:

themeoptions

options for LaTeX beamer themes (a list).

titlegraphic

image for title slide

Variables for LaTeX

Pandoc uses these variables when [creating a PDF] with a LaTeX engine.

Layout

block-headings

make \paragraph and \subparagraph (fourth- and fifth-level headings, or fifth- and sixth-level with book classes) free-standing rather than run-in; requires further formatting to distinguish from \subsubsection (third- or fourth-level headings). Instead of using this option, KOMA-Script can adjust headings more extensively:

---
documentclass: scrartcl
header-includes: |
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\itshape]{paragraph}
  \RedeclareSectionCommand[
    beforeskip=-10pt plus -2pt minus -1pt,
    afterskip=1sp plus -1sp minus 1sp,
    font=\normalfont\scshape,
    indent=0pt]{subparagraph}
...
classoption

option for document class, e.g. oneside; repeat for multiple options:

---
classoption:
- twocolumn
- landscape
...
documentclass

document class: usually one of the standard classes, article, book, and report; the KOMA-Script equivalents, scrartcl, scrbook, and scrreprt, which default to smaller margins; or memoir

geometry

option for geometry package, e.g. margin=1in; repeat for multiple options:

---
geometry:
- top=30mm
- left=20mm
- heightrounded
...
indent

uses document class settings for indentation (the default LaTeX template otherwise removes indentation and adds space between paragraphs)

linestretch

adjusts line spacing using the setspace package, e.g. 1.25, 1.5

margin-left, margin-right, margin-top, margin-bottom

sets margins if geometry is not used (otherwise geometry overrides these)

pagestyle

control \pagestyle{}: the default article class supports plain (default), empty (no running heads or page numbers), and headings (section titles in running heads)

papersize

paper size, e.g. letter, a4

secnumdepth

numbering depth for sections (with --number-sections option or numbersections variable)

Fonts

fontenc

allows font encoding to be specified through fontenc package (with pdflatex); default is T1 (see LaTeX font encodings guide)

fontfamily

font package for use with pdflatex: TeX Live includes many options, documented in the LaTeX Font Catalogue. The default is Latin Modern.

fontfamilyoptions

options for package used as fontfamily; repeat for multiple options. For example, to use the Libertine font with proportional lowercase (old-style) figures through the libertinus package:

---
fontfamily: libertinus
fontfamilyoptions:
- osf
- p
...
fontsize

font size for body text. The standard classes allow 10pt, 11pt, and 12pt. To use another size, set documentclass to one of the KOMA-Script classes, such as scrartcl or scrbook.

mainfont, sansfont, monofont, mathfont, CJKmainfont

font families for use with xelatex or lualatex: take the name of any system font, using the fontspec package. CJKmainfont uses the xecjk package.

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; repeat for multiple options. For example, to use the TeX Gyre version of Palatino with lowercase figures:

---
mainfont: TeX Gyre Pagella
mainfontoptions:
- Numbers=Lowercase
- Numbers=Proportional
...
microtypeoptions

options to pass to the microtype package

colorlinks

add color to link text; automatically enabled if any of linkcolor, filecolor, citecolor, urlcolor, or toccolor are set

linkcolor, filecolor, citecolor, urlcolor, toccolor

color for internal links, external links, citation links, linked URLs, and links in table of contents, respectively: uses options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists

links-as-notes

causes links to be printed as footnotes

Front matter

lof, lot

include list of figures, list of tables

thanks

contents of acknowledgments footnote after document title

toc

include table of contents (can also be set using --toc/--table-of-contents)

toc-depth

level of section to include in table of contents

BibLaTeX Bibliographies

These variables function when using BibLaTeX for [citation rendering].

biblatexoptions

list of options for biblatex

biblio-style

bibliography style, when used with --natbib and --biblatex.

biblio-title

bibliography title, when used with --natbib and --biblatex.

bibliography

bibliography to use for resolving references

natbiboptions

list of options for natbib

Variables for ConTeXt

Pandoc uses these variables when [creating a PDF] with ConTeXt.

fontsize

font size for body text (e.g. 10pt, 12pt)

headertext, footertext

text to be placed in running header or footer (see ConTeXt Headers and Footers); repeat up to four times for different placement

indenting

controls indentation of paragraphs, e.g. yes,small,next (see ConTeXt Indentation); repeat for multiple options

interlinespace

adjusts line spacing, e.g. 4ex (using setupinterlinespace); repeat for multiple options

layout

options for page margins and text arrangement (see ConTeXt Layout); repeat for multiple options

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

lof, lot

include list of figures, list of tables

mainfont, sansfont, monofont, mathfont

font families: take the name of any system font (see ConTeXt Font Switching)

margin-left, margin-right, margin-top, margin-bottom

sets margins, if layout is not used (otherwise layout overrides these)

pagenumbering

page number style and location (using setuppagenumbering); repeat for multiple options

papersize

paper size, e.g. letter, A4, landscape (see ConTeXt Paper Setup); repeat for multiple options

pdfa

adds to the preamble the setup necessary to generate PDF/A-1b:2005. To successfully generate PDF/A the required ICC color profiles have to be available and the content and all included files (such as images) have to be standard conforming. The ICC profiles can be obtained from ConTeXt ICC Profiles. See also ConTeXt PDFA for more details.

toc

include table of contents (can also be set using --toc/--table-of-contents)

whitespace

spacing between paragraphs, e.g. none, small (using setupwhitespace)

Variables for wkhtmltopdf

Pandoc uses these variables when [creating a PDF] with wkhtmltopdf. The --css option also affects the output.

footer-html, header-html

add information to the header and footer

margin-left, margin-right, margin-top, margin-bottom

set the page margins

papersize

sets the PDF paper size

Variables for man pages

adjusting

adjusts text to left (l), right (r), center (c), or both (b) margins

footer

footer in man pages

header

header in man pages

hyphenate

if true (the default), hyphenation will be used

section

section number in man pages

Variables for ms

fontfamily

font family (e.g. T or P)

indent

paragraph indent (e.g. 2m)

lineheight

line height (e.g. 12p)

pointsize

point size (e.g. 10p)

Structural variables

Pandoc sets these variables automatically in response to [options] or document contents; users can also modify them. These vary depending on the output format, and include the following:

body

body of document

date-meta

the date variable converted to ISO 8601 YYYY-MM-DD, included in all HTML based formats (dzslides, epub, html, html4, html5, revealjs, s5, slideous, slidy). The recognized formats for date are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy (e.g. Apr. 02, 2018 or April 02, 2018),yyyy[mm[dd]]](e.g.20180402, 201804 or 2018).

header-includes

contents specified by -H/--include-in-header (may have multiple values)

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)

meta-json

JSON representation of all of the document's metadata. Field values are transformed to the selected output format.

numbersections

non-null value if -N/--number-sections was specified

sourcefile, outputfile

source and destination filenames, as given on the command line. sourcefile can also be a list if input comes from multiple files, or empty if input is from stdin. You can use the following snippet in your template to distinguish them:

$if(sourcefile)$
$for(sourcefile)$
$sourcefile$
$endfor$
$else$
(stdin)
$endif$

Similarly, outputfile can be - if output goes to the terminal.

If you need absolute paths, use e.g. $curdir$/$sourcefile$.

curdir

working directory from which pandoc is run.

toc

non-null value if --toc/--table-of-contents was specified

toc-title

title of table of contents (works only with EPUB, opendocument, odt, docx, pptx, beamer, LaTeX)

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:

$if(variable)$
X
$else$
Y
$endif$

This will include X in the template if variable has a truthy value; otherwise it will include Y. Here a truthy value is any of the following:

  • a string that is not entirely white space,
  • a non-empty array where the first value is truthy,
  • any number (including zero),
  • any object,
  • the boolean true (to specify the boolean true value using YAML metadata or the --metadata flag, use true, True, or TRUE; with the --variable flag, simply omit a value for the variable, e.g. --variable draft).

X and Y are placeholders for any valid template text, and may include interpolated variables or other conditionals. The $else$ section may be omitted.

When variables can have multiple values (for example, author in a multi-author document), you can use the $for$ keyword:

$for(author)$
<meta name="author" content="$author$" />
$endfor$

You can optionally specify a separator to be used between consecutive items:

$for(author)$$author$$sep$, $endfor$

Note that the separator needs to be specified immediately before the $endfor keyword.

A dot can be used to select a field of a variable that takes an object as its value. So, for example:

$author.name$ ($author.affiliation$)

The value of a variable will be indented to the same level as the variable.

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 and merge in changes after each pandoc release.

Templates may contain comments: anything on a line after $-- will be treated as a comment and ignored.

volver

© Servei d'Informática, Universitat de Valencia. email SIUV Mod: 12 diciembre 2019 02:38  documentacion wiki traza de la pagina Editar