--self-contained
Deprecated synonym for
--embed-resources --standalone
.
--embed-resources
Produce a standalone HTML file with no external dependencies, using
data:
URIs to incorporate the contents of linked scripts,
stylesheets, images, and videos. The resulting file should be
“self-contained,” in the sense that it needs no external files and no
net access to be displayed properly by a browser. This option works only
with HTML output formats, including html4
,
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 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). Elements with the attribute data-external="1"
will
be left alone; the documents they link to will not be incorporated in
the document. Limitation: resources that are loaded dynamically through
JavaScript cannot be incorporated; as a result, fonts may be missing
when --mathjax
is used, and some advanced features
(e.g. zoom or speaker notes) may not work in an offline “self-contained”
reveal.js
slide show.
--html-q-tags
Use <q>
tags for quotes in HTML. (This option only
has an effect if the smart
extension is enabled for the
input format used.)
--ascii
Use only ASCII characters in output. Currently supported for XML and HTML formats (which use entities instead of UTF-8 when this option is selected), CommonMark, gfm, and Markdown (which use entities), roff man and ms (which use hexadecimal escapes), and to a limited degree LaTeX (which uses standard commands for accented characters when possible).
--reference-links
Use reference-style links, rather than inline links, in writing
Markdown or reStructuredText. By default inline links are used. The
placement of link references is affected by the
--reference-location
option.
--reference-location=block
|section
|document
Specify whether footnotes (and references, if
reference-links
is set) are placed at the end of the
current (top-level) block, the current section, or the document. The
default is document
. Currently this option only affects the
markdown
, muse
, html
,
epub
, slidy
, s5
,
slideous
, dzslides
, and revealjs
writers.
--markdown-headings=setext
|atx
Specify whether to use ATX-style (#
-prefixed) or
Setext-style (underlined) headings for level 1 and 2 headings in
Markdown output. (The default is atx
.) ATX-style headings
are always used for levels 3+. This option also affects Markdown cells
in ipynb
output.
--list-tables
Render tables as list tables in RST output.
--top-level-division=default
|section
|chapter
|part
Treat top-level headings as the given division type in LaTeX,
ConTeXt, DocBook, and TEI output. The hierarchy order is part, chapter,
then section; all headings are shifted such that the top-level heading
becomes the specified type. The default behavior is to determine the
best division type via heuristics: unless other conditions apply,
section
is chosen. When the documentclass
variable is set to report
, book
, or
memoir
(unless the article
option is
specified), chapter
is implied as the setting for this
option. If beamer
is the output format, specifying either
chapter
or part
will cause top-level headings
to become \part{..}
, while second-level headings remain as
their default type.
-N
, --number-sections
Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB
output. By default, sections are not numbered. Sections with class
unnumbered
will never be numbered, even if
--number-sections
is specified.
--number-offset=
NUMBER[,
NUMBER,
…]Offset for section headings in HTML output (ignored in other output
formats). The first number is added to the section number for top-level
headings, the second for second-level headings, and so on. So, for
example, if you want the first top-level heading in your document to be
numbered “6”, specify --number-offset=5
. If your document
starts with a level-2 heading which you want to be numbered “1.5”,
specify --number-offset=1,4
. Offsets are 0 by default.
Implies --number-sections
.
--listings
Use the listings
package
for LaTeX code blocks. The package does not support multi-byte encoding
for source code. To handle UTF-8 you would need to use a custom
template. This issue is fully documented here: Encoding
issue with the listings package.
-i
, --incremental
Make list items in slide shows display incrementally (one by one). The default is for lists to be displayed all at once.
--slide-level=
NUMBERSpecifies that headings with the specified level create slides (for
beamer
, s5
, slidy
,
slideous
, dzslides
). Headings above this level
in the hierarchy are used to divide the slide show into sections;
headings below this level create subheads within a slide. Valid values
are 0-6. If a slide level of 0 is specified, slides will not be split
automatically on headings, and horizontal rules must be used to indicate
slide boundaries. If a slide level is not specified explicitly, the
slide level will be set automatically based on the contents of the
document; see Structuring
the slide show.
--section-divs
Wrap sections in <section>
tags (or
<div>
tags for html4
), and attach
identifiers to the enclosing <section>
(or
<div>
) rather than the heading itself. See Heading identifiers,
below.
--email-obfuscation=none
|javascript
|references
Specify a method for obfuscating mailto:
links in HTML
documents. none
leaves mailto:
links as they
are. javascript
obfuscates them using JavaScript.
references
obfuscates them by printing their letters as
decimal or hexadecimal character references. The default is
none
.
--id-prefix=
STRINGSpecify a prefix to be added to all identifiers and internal links in HTML and DocBook output, and to footnote numbers in Markdown and Haddock output. This is useful for preventing duplicate identifiers when generating fragments to be included in other pages.
-T
STRING,
--title-prefix=
STRINGSpecify STRING as a prefix at the beginning of the title
that appears in the HTML header (but not in the title as it appears at
the beginning of the HTML body). Implies --standalone
.
-c
URL, --css=
URLLink to a CSS style sheet. This option can be used repeatedly to
include multiple files. They will be included in the order specified.
This option only affects HTML (including HTML slide shows) and EPUB
output. It should be used together with -s/--standalone
,
because the link to the stylesheet goes in the document header.
A stylesheet is required for generating EPUB. If none is provided
using this option (or the css
or stylesheet
metadata fields), pandoc will look for a file epub.css
in
the user data directory (see --data-dir
). If it is not
found there, sensible defaults will be used.
--reference-doc=
FILEUse the specified file as a style reference in producing a docx or ODT 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 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.
To produce a custom reference.docx
, first get a copy of
the default reference.docx
:
pandoc -o custom-reference.docx --print-default-data-file reference.docx
.
Then open custom-reference.docx
in Word, modify the styles
as you wish, and save the file. For best results, do not make changes to
this file other than modifying the styles used by pandoc:
Paragraph styles:
Character styles:
Table style:
For best results, the reference ODT should be a modified version of
an ODT produced using pandoc. The contents of the reference ODT are
ignored, but its stylesheets are used in the new ODT. If no reference
ODT is specified on the command line, pandoc will look for a file
reference.odt
in the user data directory (see
--data-dir
). If this is not found either, sensible defaults
will be used.
To produce a custom reference.odt
, first get a copy of
the default reference.odt
:
pandoc -o custom-reference.odt --print-default-data-file reference.odt
.
Then open custom-reference.odt
in LibreOffice, modify the
styles as you wish, and save the file.
Templates included with Microsoft PowerPoint 2013 (either with
.pptx
or .potx
extension) are known to work,
as are most templates derived from these.
The specific requirement is that the template should contain layouts with the following names (as seen within PowerPoint):
For each name, the first layout found with that name will be used. If no layout is found with one of the names, pandoc will output a warning and use the layout with that name from the default reference doc instead. (How these layouts are used is described in PowerPoint layout choice.)
All templates included with a recent version of MS PowerPoint will
fit these criteria. (You can click on Layout
under the
Home
menu to check.)
You can also modify the default reference.pptx
: first
run
pandoc -o custom-reference.pptx --print-default-data-file reference.pptx
,
and then modify custom-reference.pptx
in MS PowerPoint
(pandoc will use the layouts with the names listed above).
--epub-cover-image=
FILEUse the specified image as the EPUB cover. It is recommended that the
image be less than 1000px in width and height. Note that in a Markdown
source document you can also specify cover-image
in a YAML
metadata block (see EPUB
Metadata, below).
--epub-title-page=true
|false
Determines whether a the title page is included in the EPUB (default
is true
).
--epub-metadata=
FILELook in the specified XML file for metadata for the EPUB. The file should contain a series of Dublin Core elements. For example:
<dc:rights>Creative Commons</dc:rights>
<dc:language>es-AR</dc:language>
By default, pandoc will include the following metadata elements:
<dc:title>
(from the document title),
<dc:creator>
(from the document authors),
<dc:date>
(from the document date, which should be in
ISO 8601 format),
<dc:language>
(from the lang
variable,
or, if is not set, the locale), and
<dc:identifier id="BookId">
(a randomly generated
UUID). Any of these may be overridden by elements in the metadata
file.
Note: if the source document is Markdown, a YAML metadata block in the document can be used instead. See below under EPUB Metadata.
--epub-embed-font=
FILEEmbed the specified font in the EPUB. This option can be repeated to
embed multiple fonts. Wildcards can also be used: for example,
DejaVuSans-*.ttf
. However, if you use wildcards on the
command line, be sure to escape them or put the whole filename in single
quotes, to prevent them from being interpreted by the shell. To use the
embedded fonts, you will need to add declarations like the following to
your CSS (see --css
):
@font-face {
font-family: DejaVuSans;
font-style: normal;
font-weight: normal;
src:url("../fonts/DejaVuSans-Regular.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: normal;
font-weight: bold;
src:url("../fonts/DejaVuSans-Bold.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: italic;
font-weight: normal;
src:url("../fonts/DejaVuSans-Oblique.ttf");
}
@font-face {
font-family: DejaVuSans;
font-style: italic;
font-weight: bold;
src:url("../fonts/DejaVuSans-BoldOblique.ttf");
}
body { font-family: "DejaVuSans"; }
--epub-chapter-level=
NUMBERSpecify the heading level at which to split the EPUB into separate “chapter” files. The default is to split into chapters at level-1 headings. This option only affects the internal composition of the EPUB, not the way chapters and sections are displayed to users. Some readers may be slow if the chapter files are too large, so for large documents with few level-1 headings, one might want to use a chapter level of 2 or 3.
--epub-subdirectory=
DIRNAMESpecify the subdirectory in the OCF container that is to hold the
EPUB-specific contents. The default is EPUB
. To put the
EPUB contents in the top level, use an empty string.
--ipynb-output=all|none|best
Determines how ipynb output cells are treated. all
means
that all of the data formats included in the original are preserved.
none
means that the contents of data cells are omitted.
best
causes pandoc to try to pick the richest data block in
each output cell that is compatible with the output format. The default
is best
.
--pdf-engine=
PROGRAMUse the specified engine when producing PDF output. Valid values are
pdflatex
, lualatex
, xelatex
,
latexmk
, tectonic
, wkhtmltopdf
,
weasyprint
, pagedjs-cli
, prince
,
context
, and pdfroff
. If the engine is not in
your PATH, the full path of the engine may be specified here. If this
option is not specified, pandoc uses the following defaults depending on
the output format specified using -t/--to
:
-t latex
or none: pdflatex
(other options:
xelatex
, lualatex
, tectonic
,
latexmk
)-t context
: context
-t html
: wkhtmltopdf
(other options:
prince
, weasyprint
, pagedjs-cli
;
see print-css.rocks for a good
introduction to PDF generation from HTML/CSS)-t ms
: pdfroff
--pdf-engine-opt=
STRINGUse the given string as a command-line argument to the
pdf-engine
. For example, to use a persistent directory
foo
for latexmk
’s auxiliary files, use
--pdf-engine-opt=-outdir=foo
. Note that no check for
duplicate options is done.