ePub Options

ePub is an e-book file format that is supported by many e-readers, and compatible software is available for most smartphones, tablets, and computers. You can learn more about ePub at https://en.wikipedia.org/wiki/EPUB.

format: epub

Title & Author


Document title


Identifies the subtitle of the document.


Document date


Author or authors of the document


Summary of document


Title used to label document abstract

Format Options


One or more CSS style sheets.


Method use to render math in HTML output (plain, webtex, gladtex, mathml, mathjax, katex)


Use <q> tags for quotes in HTML.

Table of Contents


Include an automatically generated table of contents (or, in the case of latex, context, docx, odt, opendocument, rst, or ms, an instruction to create one) in the output document. This option has no effect if standalone is false.

Note that if you are producing a PDF via ms, the table of contents will appear at the beginning of the document, before the title. If you would prefer it to be at the end of the document, use the option pdf-engine-opt: --no-toc-relocation.


Specify the number of section levels to include in the table of contents. The default is 3


The title used for the table of contents.



Number section headings rendered ouptut. By default, sections are not numbered. Sections with class .unnumbered will never be numbered, even if number-sections is specified.


By default, all headings in your document create a numbered section. You customize numbering depth using the number-depth option.

For example, to only number sections immediately below the chapter level, use this:

number-depth: 1

Offset for section headings in output (offsets are 0 by default) 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]. Implies number-sections


Shift heading levels by a positive or negative integer. For example, with shift-heading-level-by: -1, level 2 headings become level 1 headings, and level 3 headings become level 2 headings. Headings cannot have a level less than 1, so a heading that would be shifted below level 1 becomes a regular paragraph. Exception: with a shift of -N, a level-N heading at the beginning of the document replaces the metadata title.

ePub Options


The identifier for this publication.


Creators of this publication.


Contributors to this publication.


The subject of the publication.


Text describing the specialized type of this publication.

An informative registry of specialized EPUB Publication types for use with this element is maintained in the TypesRegistry, but Authors may use any text string as a value.


Text describing the format of this publication.


Text describing the relation of this publication.


Text describing the coverage of this publication.


Text describing the rights of this publication.


Identifies the name of a collection to which the EPUB Publication belongs.


Indicates the numeric position in which this publication belongs relative to other works belonging to the same belongs-to-collection field.


Sets the global direction in which content flows (ltr or rtl)


Look 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>

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.


Specify 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.


Embed the specified fonts in the EPUB. Wildcards can also be used: for example, DejaVuSans-*.ttf. To use the embedded fonts, you will need to add declarations like the following to your CSS:

@font-face {
  font-family: DejaVuSans;
  font-style: normal;
  font-weight: normal;

Specify 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.


Use the specified image as the EPUB cover. It is recommended that the image be less than 1000px in width and height.



Collapse code into an HTML <details> tag so the user can display it on-demand. Specify show to have the code initiallly visible.


Summary text to use for code blocks collapsed using code-fold


Choose whether to scroll or wrap when code lines are too wide for their container.


Include line numbers in code block output.


Enable a code copy icon for code blocks. Defaults to hover, which shows the icon when the mouse hovers over the code block. Set to true or false to show or hide unconditionally.


Specifies the coloring style to be used in highlighted source code.

Instead of a STYLE name, a JSON file with extension .theme may be supplied. This will be parsed as a KDE syntax highlighting theme and (if valid) used as the highlighting style.


KDE language syntax definition files (XML)


Specify classes to use for all indented code blocks


Execution options should be specified within the execute key. For example:

  echo: false
  warning: false

Evaluate code cells (if false just echos the code into output).


Include cell source code in rendered output. Specify fenced to include the cell delimiter as part of the output.


Include the results of executing the code in the output (specify asis to treat output as raw markdown with no enclosing containers).


Including warnings in rendered output.


Include errors in the output (note that this implies that errors executing code will not halt processing of the document).


Catch all for preventing any output (code or results) from being included in output.


Cache results of computations (using the knitr cache for R documents, and Jupyter Cache for Jupyter documents).

Note that cache invalidation is triggered by changes in chunk source code (or other cache attributes you’ve defined). Use refresh to force a refresh of the cache even if has not been otherwise invalidated.


Option to denote that computational documents should never be re-rendered during a global project render (freeze: true), or alternatively only be re-rendered when their source file changes (freeze: auto).



Default horizontal alignment for figures (left, right, center, or default)


Default width for figures generated by Matplotlib or R graphics


Default height for figures generated by Matplotlib or R graphics


Default format for figures generated by Matplotlib or R graphics (retina, png, jpeg, svg, or pdf)


Default DPI for figures generated by Matplotlib or R graphics


Whether to make images in this document responsive.



Apply explicit table column widths for markdown grid tables and pipe tables that are more than columns characters wide (72 by default).

Some formats (e.g. HTML) do an excellent job automatically sizing table columns and so don’t benefit much from column width specifications. Other formats (e.g. LaTeX) require table column sizes in order to correctly flow longer cell content (this is a major reason why tables > 72 columns wide are assigned explicit widths by Pandoc).

This can be specified as:

  • auto: Apply markdown table column widths except when there is a hyperlink in the table (which tends to throw off automatic calculation of column widths based on the markdown text width of cells). (auto is the default for HTML output formats)

  • true: Always apply markdown table widths (true is the default for all non-HTML formats)

  • false: Never apply markdown table widths.

  • [40,30,30]: Array of explicit width percentages.



Document bibliography (BibTeX or CSL). May be a single file or a list of files


Citation Style Language file to use for formatting references.


Turn on built-in citation processing. To use this feature, you will need to have a document containing citations and a source of bibliographic data: either an external bibliography file or a list of references in the document’s YAML metadata. You can optionally also include a csl citation style file.


JSON file containing abbreviations of journals that should be used in formatted bibliographies when form="short" is specified. The format of the file can be illustrated with an example:

{ "default": {
    "container-title": {
      "Lloyd's Law Reports": "Lloyd's Rep",
      "Estates Gazette": "EG",
      "Scots Law Times": "SLT"



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.


YAML file containing custom language translations


The base script direction for the document.

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).



Content to include at the end of the document header.


Content to include at the beginning of the document body (e.g. after the <body> tag in HTML, or the \begin{document} command in LaTeX).


Content to include at the end of the document body (before the </body> tag in HTML, or the \end{document} command in LaTeX).


Include contents of files, verbatim, at the beginning of the document body (e.g. after the <body> tag in HTML, or the \begin{document} command in LaTeX).


Include contents of files, verbatim, at the end of the document body (before the </body> tag in HTML, or the \end{document} command in LaTeX).


Include contents of files, verbatim, at the end of the header. This can be used, for example, to include special CSS or JavaScript in HTML documents.


Path (or glob) to files to publish with this document.


Read metadata from the supplied YAML (or JSON) files. This option can be used with every input format, but string scalars in the YAML file will always be parsed as Markdown. Generally, the input will be handled the same as in YAML metadata blocks. Values in files specified later in the list will be preferred over those specified earlier. Metadata values specified inside the document, or by using -M, overwrite values specified with this option.



Sets the date metadata for the document



Format to read from. Extensions can be individually enabled or disabled by appending +EXTENSION or -EXTENSION to the format name (e.g. markdown+emoji).


Output file to write to


Extension to use for generated output file


Use the specified file as a custom template for the generated document.


Produce output with an appropriate header and footer (e.g. a standalone HTML, LaTeX, TEI, or RTF file, not a fragment)


Specify executables or Lua scripts to be used as a filter transforming the pandoc AST after the input is parsed and before the output is written.


Keep the markdown file generated by executing code


Keep the notebook file generated from executing code.


Extract images and other media contained in or linked from the source document to the path DIR, creating it if necessary, and adjust the images references in the document so they point to the extracted files. Media are downloaded, read from the file system, or extracted from a binary container (e.g. docx), as needed. The original file paths are used if they are relative paths not containing … Otherwise filenames are constructed from the SHA1 hash of the contents.


List of paths to search for images and other resources. The paths should be separated by : on Linux, UNIX, and macOS systems, and by ; on Windows.


Specify a default extension to use when image paths/URLs have no extension. This allows you to use the same source for formats that require different kinds of images. Currently this option only affects the Markdown and LaTeX readers.


Specifies a custom abbreviations file, with abbreviations one to a line. This list is used when reading Markdown input: strings found in this list will be followed by a nonbreaking space, and the period will not produce sentence-ending space in formats like LaTeX. The strings may not contain spaces.


Specify the default dpi (dots per inch) value for conversion from pixels to inch/ centimeters and vice versa. (Technically, the correct term would be ppi: pixels per inch.) The default is 96. When images contain information about dpi internally, the encoded value is used instead of the default specified by this option.

Text Output


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 ms (which use hexadecimal escapes), and to a limited degree LaTeX (which uses standard commands for accented characters when possible). roff man output uses ASCII by default.