Dashboard Options

Format

The following document and format options are either dashboard-specific or have special behavior within dashboards:

Option	Description
`title`	Title (displayed in top left of navigation bar)
`author`	Author (displayed alongside title in smaller font)
`logo`	Logo (displayed left of the title in the navigation bar)
`orientation`	`rows` or `columns` (default: `rows`)
`scrolling`	Use scrolling rather than fill layout? (default: `false`)
`expandable`	Make card content expandable (default: `true`)
`theme`	Dashboard theme (built in or custom scss)
`nav-buttons`	Buttons to appear on the right side of the navigation bar. Use `linkedin`, `facebook`, `reddit`, `twitter`, `github`, or a custom Nav Item.

For example:

---
title: "Dashboard"
author: "Acme, Inc."
logo: images/acme.png
format:
  dashboard:
     theme: default
     orientation: rows
     expandable: true
     scrolling: false
     nav-buttons:
      - reddit
      - icon: gitlab
        href: https://gitlab.com/
---

Pages

Pages can specify a custom orientation that is distinct from the global orientation:

Option	Description
`orientation`	`rows` or `columns` (default to global orientation)
`scrolling`	`true` or `false` (defaults to global scrolling)

For example:

---
title: "Dashboard"
format: dashboard
---

# Plots {orientation="columns" scrolling="true"}

Sidebars

Create Sidebars by applying the .sidebar attribute to a level 1 heading (for global sidebars) or level 2 heading (for page level sidebars).

Class	Description
`.sidebar`	Contents should be arranged into a sidebar

For example:

---
title: "Dashboard"
format: dashboard
---

# Plots {.sidebar}

Rows & Columns

Rows and columns support options for customizing their layout and sizing behavior. The following classes can be used to modify layout behavior:

Class	Description
`.tabset`	Contents should be arranged into a Tabset
`.fill`	Contents should fill available layout space
`.flow`	Contents should flow to their natural size

Note that in most dashboards, .fill and .flow are determined automatically based on the contents of cards and don’t need to be specified manually.

The following attributes can be used for explicit sizing:

Option	Description
`width`	Percentage or absolute pixel width (default distributes space evenly across elements in a row)
`height`	Percentage or absolute pixel height (default distributes space evenly across elements in a column)

For example:

---
title: "Dashboard"
format: dashboard
---

## Row {height="65%"}

## Row {height="35%"}

Note that if some components specify an explicit width or height and others do not, then remaining space will be distributed evenly across those elements.

Cards

Card options enable you to specify a title and various layout behaviors:

Option	Description
`title`	Title displayed in card header
`padding`	Padding around card content (default: `8px`)
`expandable`	Make card content expandable (default: `true`)
`width`	Percentage or absolute pixel width (default distributes space evenly across elements in a row)
`height`	Percentage or absolute pixel height (default distributes space evenly across elements in a column)
`fill`	Whether the card should fill it’s container or ‘flow’, matching the height of its content. (Quarto determines the default value based upon the card contents)

For example:

```{python}
#| title: "Life Expectancy"
#| padding: 3px
#| expandable: false
#| width: 70%
```

These same options can be applied to .card divs. For example:

::: {.card title="Life Expectancy" padding="3px"}
This is the content.
:::

Value Boxes

Value Boxes support the following options:

Option	Description
`title`	Title displayed above value
`icon`	Icon identifier from bootstrap icons
`color`	Background color—this can be any CSS color or one of the theme specific color aliases (see below)
`value`	Main display value

Available themed aliases for color include:

Color Alias	Default Theme Color(s)
`primary`	Blue
`secondary`	Gray
`success`	Green
`info`	Bright Blue
`warning`	Yellow/Orange
`danger`	Red
`light`	Light Gray
`dark`	Black

Note that value box options can be specified either as cell options or by printing a dict() (for Python) or list() (for R) (this is helpful when options need to be dynamic). See the Value Boxes component documentation for details.

Title & Author

`title`	Document title
`subtitle`	Identifies the subtitle of the document.
`date`	Document date
`author`	Author or authors of the document
`order`	Order for document when included in a website automatic sidebar menu.

Dashboard

`logo`	Logo image (placed on the left side of the navigation bar)
`orientation`	Default orientation for dashboard content (default `rows`)
`scrolling`	Use scrolling rather than fill layout (default: `false`)
`expandable`	Make card content expandable (default: `true`)
`nav-buttons`	Links to display on the dashboard navigation bar

Format Options

`theme`	Theme name, theme scss file, or a mix of both.
`css`	One or more CSS style sheets.
`identifier-prefix`	Specify 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.
`email-obfuscation`	Specify a method for obfuscating `mailto:` links in HTML documents. `javascript`: Obfuscate links using JavaScript. `references`: Obfuscate links by printing their letters as decimal or hexadecimal character references. `none` (default): Do not obfuscate links.
`html-q-tags`	Use `<q>` tags for quotes in HTML.
`quarto-required`	A semver version range describing the supported quarto versions for this document or project. Examples: `>= 1.1.0`: Require at least quarto version 1.1 `1.*`: Require any quarto versions whose major version number is 1

toc

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.

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.

toc-depth

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

Numbering

`number-sections`	Number section headings rendered output. By default, sections are not numbered. Sections with class `.unnumbered` will never be numbered, even if `number-sections` is specified.
`number-depth`	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`
`number-offset`	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-level-by`	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.

Layout

`cap-location`	Where to place figure and table captions (`top`, `bottom`, or `margin`)
`fig-cap-location`	Where to place figure captions (`top`, `bottom`, or `margin`)
`tbl-cap-location`	Where to place table captions (`top`, `bottom`, or `margin`)
`classoption`	For LaTeX/PDF output, the options set for the document class. For HTML output using KaTeX, you can render display math equations flush left using `classoption: fleqn`
`grid`	Properties of the grid system used to layout Quarto HTML pages.
`max-width`	Adds a css `max-width` to the body Element.
`margin-left`	For HTML output, sets the `margin-left` property on the Body element. For LaTeX output, sets the left margin if `geometry` is not used (otherwise `geometry` overrides this value) For ConTeXt output, sets the left margin if `layout` is not used, otherwise `layout` overrides these. For `wkhtmltopdf` sets the left page margin.
`margin-right`	For HTML output, sets the `margin-right` property on the Body element. For LaTeX output, sets the right margin if `geometry` is not used (otherwise `geometry` overrides this value) For ConTeXt output, sets the right margin if `layout` is not used, otherwise `layout` overrides these. For `wkhtmltopdf` sets the right page margin.
`margin-top`	For HTML output, sets the `margin-top` property on the Body element. For LaTeX output, sets the top margin if `geometry` is not used (otherwise `geometry` overrides this value) For ConTeXt output, sets the top margin if `layout` is not used, otherwise `layout` overrides these. For `wkhtmltopdf` sets the top page margin.
`margin-bottom`	For HTML output, sets the `margin-bottom` property on the Body element. For LaTeX output, sets the bottom margin if `geometry` is not used (otherwise `geometry` overrides this value) For ConTeXt output, sets the bottom margin if `layout` is not used, otherwise `layout` overrides these. For `wkhtmltopdf` sets the bottom page margin.

Code

`code-fold`	Collapse code into an HTML `<details>` tag so the user can display it on-demand. `true`: collapse code `false` (default): do not collapse code `show`: use the `<details>` tag, but show the expanded code initially.
`code-summary`	Summary text to use for code blocks collapsed using `code-fold`
`code-overflow`	Choose how to handle code overflow, when code lines are too wide for their container. One of: `scroll` `wrap`
`code-line-numbers`	Include line numbers in code block output (`true` or `false`). For revealjs output only, you can also specify a string to highlight specific lines (and/or animate between sets of highlighted lines). Sets of lines are denoted with commas: `3,4,5` `1,10,12` Ranges can be denoted with dashes and combined with commas: `1-3,5` `5-10,12,14` Finally, animation steps are separated by `\|`: `1-3\|1-3,5` first shows `1-3`, then `1-3,5` `\|5\|5-10,12` first shows no numbering, then 5, then lines 5-10 and 12
`code-copy`	Enable a code copy icon for code blocks. `true`: Always show the icon `false`: Never show the icon `hover` (default): Show the icon when the mouse hovers over the code block
`code-link`	Enables hyper-linking of functions within code blocks to their online documentation. Code linking is currently implemented only for the knitr engine (via the downlit package). A limitation of downlit currently prevents code linking if `code-line-numbers` is also `true`.
`code-annotations`	The style to use when displaying code annotations. Set this value to false to hide code annotations.
`highlight-style`	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.
`syntax-definitions`	KDE language syntax definition files (XML)
`indented-code-classes`	Specify classes to use for all indented code blocks

Execution

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

execute:
  echo: false
  warning: false

`eval`	Evaluate code cells (if `false` just echos the code into output). `true` (default): evaluate code cell `false`: don’t evaluate code cell `[...]`: A list of positive or negative line numbers to selectively include or exclude lines (explicit inclusion/excusion of lines is available only when using the knitr engine)
`echo`	Include cell source code in rendered output. `true` (default in most formats): include source code in output `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output `fenced`: in addition to echoing, include the cell delimiter as part of the output. `[...]`: A list of positive or negative line numbers to selectively include or exclude lines (explicit inclusion/excusion of lines is available only when using the knitr engine)
`output`	Include the results of executing the code in the output. Possible values: `true`: Include results. `false`: Do not include results. `asis`: Treat output as raw markdown with no enclosing containers.
`warning`	Include warnings in rendered output.
`error`	Include errors in the output (note that this implies that errors executing code will not halt processing of the document).
`include`	Catch all for preventing any output (code or results) from being included in output.
`cache`	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). `true`: Cache results `false`: Do not cache results `refresh`: Force a refresh of the cache even if has not been otherwise invalidated.
`freeze`	Control the re-use of previous computational output when rendering. `true`: Never recompute previously generated computational output during a global project render `false` (default): Recompute previously generated computational output `auto`: Re-compute previously generated computational output only in case their source file changes

Figures

`fig-align`	Figure horizontal alignment (`default`, `left`, `right`, or `center`)
`fig-cap-location`	Where to place figure captions (`top`, `bottom`, or `margin`)
`fig-width`	Default width for figures generated by Matplotlib or R graphics. Note that with the Jupyter engine, this option has no effect when provided at the cell level; it can only be provided with document or project metadata.
`fig-height`	Default height for figures generated by Matplotlib or R graphics. Note that with the Jupyter engine, this option has no effect when provided at the cell level; it can only be provided with document or project metadata.
`fig-format`	Default format for figures generated by Matplotlib or R graphics (`retina`, `png`, `jpeg`, `svg`, or `pdf`)
`fig-dpi`	Default DPI for figures generated by Matplotlib or R graphics. Note that with the Jupyter engine, this option has no effect when provided at the cell level; it can only be provided with document or project metadata.
`fig-asp`	The aspect ratio of the plot, i.e., the ratio of height/width. When `fig-asp` is specified, the height of a plot (the option `fig-height`) is calculated from `fig-width * fig-asp`. The `fig-asp` option is only available within the knitr engine.
`fig-responsive`	Whether to make images in this document responsive.

Tables

tbl-colwidths

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.
An array of numbers (e.g. [40, 30, 30]): Array of explicit width percentages.

tbl-cap-location

Where to place table captions (top, bottom, or margin)

df-print

Method used to print tables in Knitr engine documents:

default: Use the default S3 method for the data frame.
kable: Markdown table using the knitr::kable() function.
tibble: Plain text table using the tibble package.
paged: HTML table with paging for row and column overflow.

The default printing method is kable.

References

`bibliography`	Document bibliography (BibTeX or CSL). May be a single file or a list of files
`csl`	Citation Style Language file to use for formatting references.
`citations-hover`	Enables a hover popup for citation that shows the reference information.
`citeproc`	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.
`citation-abbreviations`	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" } } }`

Footnotes

footnotes-hover

Enables a hover popup for footnotes that shows the footnote contents.

reference-location

Specify location for footnotes. Also controls the location of references, if reference-links is set.

block: Place at end of current top-level block
section: Place at end of current section
margin: Place at the margin
document: Place at end of document

Crossrefs

`crossref`	Configuration for crossref labels and prefixes.
`crossrefs-hover`	Enables a hover popup for cross references that shows the item being referenced.

Citation

citation

Citation information for the document itself specified as CSL YAML in the document front matter.

For more on supported options, see Citation Metadata.

Language

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.

language

YAML file containing custom language translations

dir

The base script direction for the document (rtl or ltr).

For bidirectional documents, native pandoc spans and divs with the dir attribute 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).

Includes

`include-before-body`	Include contents at the beginning of the document body (e.g. after the `<body>` tag in HTML, or the `\begin{document}` command in LaTeX). A string value or an object with key “file” indicates a filename whose contents are to be included An object with key “text” indicates textual content to be included
`include-after-body`	Include content at the end of the document body immediately after the markdown content. While it will be included before the closing `</body>` tag in HTML and the `\end{document}` command in LaTeX, this option refers to the end of the markdown content. A string value or an object with key “file” indicates a filename whose contents are to be included An object with key “text” indicates textual content to be included
`include-in-header`	Include contents at the end of the header. This can be used, for example, to include special CSS or JavaScript in HTML documents. A string value or an object with key “file” indicates a filename whose contents are to be included An object with key “text” indicates textual content to be included
`resources`	Path (or glob) to files to publish with this document.
`metadata-files`	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.

Metadata

`keywords`	List of keywords to be included in the document metadata.
`pagetitle`	Sets the title metadata for the document
`title-prefix`	Specify 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 body)
`description-meta`	Sets the description metadata for the document
`author-meta`	Sets the author metadata for the document
`date-meta`	Sets the date metadata for the document

Rendering

`from`	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`	Output file to write to
`output-ext`	Extension to use for generated output file
`template`	Use the specified file as a custom template for the generated document.
`template-partials`	Include the specified files as partials accessible to the template for the generated content.
`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, some advanced features (e.g. zoom or speaker notes) may not work in an offline “self-contained” `reveal.js` slide show.
`self-contained-math`	Embed math libraries (e.g. MathJax) within `self-contained` output. Note that math libraries are not embedded by default because they are quite large and often time consuming to download.
`filters`	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.
`shortcodes`	Specify Lua scripts that implement shortcode handlers
`keep-md`	Keep the markdown file generated by executing code
`keep-ipynb`	Keep the notebook file generated from executing code.
`ipynb-filters`	Filters to pre-process ipynb files before rendering to markdown
`ipynb-shell-interactivity`	Specify which nodes should be run interactively (displaying output from expressions)
`plotly-connected`	If true, use the “notebook_connected” plotly renderer, which downloads its dependencies from a CDN and requires an internet connection to view.
`extract-media`	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.
`resource-path`	List of paths to search for images and other resources.
`default-image-extension`	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.
`abbreviations`	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.
`dpi`	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.
`html-table-processing`	If `none`, do not process tables in HTML input.

Text Output

`strip-comments`	Strip out HTML comments in the Markdown source, rather than passing them on to Markdown, Textile or HTML output as raw HTML. This does not apply to HTML comments inside raw HTML blocks when the `markdown_in_html_blocks` extension is not set.
`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 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.

Format

Pages

Sidebars

Rows & Columns

Cards

Value Boxes

Title & Author

Dashboard

Format Options

Table of Contents

Numbering

Layout

Code

Execution

Figures

Tables

References

Footnotes

Crossrefs

Citation

Language

Includes

Metadata

Rendering

Text Output