HTML Options

HTML is a markup language used for structuring and presenting content on the web. To learn more about HTML see https://en.wikipedia.org/wiki/HTML5.

See the HTML format user guide for more details on creating HTML output with Quarto.

format: html

Title & Author

title	Document title
subtitle	Identifies the subtitle of the document.
date	Document date
date-modified	Document date modified
author	Author or authors of the document
abstract	Summary of document
abstract-title	Title used to label document abstract
doi	Displays the document Digital Object Identifier in the header.
order	Order for document when included in a website automatic sidebar menu.

Format Options

brand	Branding information to use for this document. If a string, the path to a brand file. If false, don’t use branding on this document. If an object, an inline brand definition.
theme	Theme name, theme scss file, or a mix of both.
body-classes	Classes to apply to the body of the document.
minimal	Disables the built in html features like theming, anchor sections, code block behavior, and more.
css	One or more CSS style sheets.
anchor-sections	Enables hover over a section title to see an anchor link.
tabsets	Enables tabsets to present content.
smooth-scroll	Enables smooth scrolling within the page.
html-math-method	Method use to render math in HTML output (plain, webtex, gladtex, mathml, mathjax, katex). See the Pandoc documentation on Math Rendering in HTML for additional details.
section-divs	Wrap sections in <section> tags and attach identifiers to the enclosing <section> rather than the heading itself.
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

Table of Contents

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
toc-location	Location for table of contents: body: Show the Table of Contents in the center body of the document. left: Show the Table of Contents in left margin of the document. right(default): Show the Table of Contents in right margin of the document. left-body: Show two Tables of Contents in both the center body and the left margin of the document. right-body: Show two Tables of Contents in both the center body and the right margin of the document.
toc-title	The title used for the table of contents.
toc-expand	Specifies the depth of items in the table of contents that should be displayed as expanded in HTML output. Use true to expand all or false to collapse all.

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.

Fonts

mainfont	For HTML output, sets the CSS font-family on the HTML element. For LaTeX output, the main font family for use with xelatex or lualatex. Takes the name of any system font, using the fontspec package. For ConTeXt output, the main font family. Use the name of any system font. See ConTeXt Fonts for more information.
monofont	For HTML output, sets the CSS font-family property on code elements. For PowerPoint output, sets the font used for code. For LaTeX output, the monospace font family for use with xelatex or lualatex: take the name of any system font, using the fontspec package. For ConTeXt output, the monspace font family. Use the name of any system font. See ConTeXt Fonts for more information.
fontsize	For HTML output, sets the base CSS font-size property. For LaTeX and ConTeXt output, sets the font size for the document body text.
linestretch	For HTML output sets the CSS line-height property on the html element, which is preferred to be unitless. For LaTeX output, adjusts line spacing using the setspace package, e.g. 1.25, 1.5.

Colors

fontcolor	Sets the CSS color property.
linkcolor	For HTML output, sets the CSS color property on all links. For LaTeX output, The color used for internal links using color options allowed by xcolor, including the dvipsnames, svgnames, and x11names lists. For ConTeXt output, sets the color for both external links and links within the document.
monobackgroundcolor	Sets the CSS background-color property on code elements and adds extra padding.
backgroundcolor	Sets the CSS background-color property on the html element.

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
page-layout	The page layout to use for this document (article, full, or custom)
grid	Properties of the grid system used to layout Quarto HTML pages.
appendix-style	The layout of the appendix for this document (none, plain, or default). To completely disable any styling of the appendix, choose the appendix style none. For minimal styling, choose plain.
appendix-cite-as	Controls the formats which are provided in the citation section of the appendix. Use false to disable the display of the ‘cite as’ appendix. Pass one or more of display or bibtex to enable that format in ‘cite as’ appendix.
title-block-style	The layout of the title block for this document (none, plain, or default). To completely disable any styling of the title block, choose the style none. For minimal styling, choose plain.
title-block-banner	Applies a banner style treatment for the title block. You may specify one of the following values: true Will enable the banner style display and automatically select a background color based upon the theme. <css color value> If you provide a CSS color value, the banner will be enabled and the background color set to the provided CSS color. <path> If you provide the path to a file, the banner will be enabled and the background image will be set to the file path. See title-block-banner-color if you’d like to control the color of the title block banner text.
title-block-banner-color	Sets the color of text elements in a banner style title block. Use one of the following values: body | body-bg Will set the text color to the body text color or body background color, respectively. <css color value> If you provide a CSS color value, the text color will be set to the provided CSS color.
title-block-categories	Enables or disables the display of categories in the title block.
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.
code-tools	Include a code tools menu (for hiding and showing code). Use true or false to enable or disable the standard code tools menu. Specify sub-properties source, toggle, and caption to customize the behavior and appearance of code tools.
code-block-border-left	Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is enabled as well as the color of the border.
code-block-bg	Specifies to apply a background color on code blocks. Provide a hex color to specify that the background color is enabled as well as the color of the background.
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.

Lightbox Figures

lightbox

Enable or disable lightbox treatment for images in this document. See Lightbox Figures for more details.

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.

Links

link-external-icon	Show a special icon next to links that leave the current site.
link-external-newwindow	Open external links in a new browser window or tab (rather than navigating the current tab).
link-external-filter	A regular expression that can be used to determine whether a link is an internal link. For example, the following will treat links that start with http://www.quarto.org as internal links (and others will be considered external): ^(?:http:|https:)\/\/www\.quarto\.org\/custom
format-links	Controls whether links to other rendered formats are displayed in HTML output. Pass false to disable the display of format lengths or pass a list of format names for which you’d like links to be shown.
notebook-links	Controls the display of links to notebooks that provided embedded content or are created from documents. Specify false to disable linking to source Notebooks. Specify inline to show links to source notebooks beneath the content they provide. Specify global to show a set of global links to source notebooks.
other-links	A list of links that should be displayed below the table of contents in an Other Links section.
code-links	A list of links that should be displayed below the table of contents in an Code Links section.
notebook-view	Configures the HTML viewer for notebooks that provide embedded content.
notebook-preview-options	Options for controlling the display and behavior of Notebook previews.
canonical-url	Include a canonical link tag in website pages. You may pass either true to automatically generate a canonical link, or pass a canonical url that you’d like to have placed in the href attribute of the tag. Canonical links can only be generated for websites with a known site-url.

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.
citation-location	Where citation information should be displayed (document or margin)
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

Cross-References

crossref	Configuration for cross-reference labels and prefixes. See Cross-Reference Options for more details.
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.
copyright	The copyright for this document, if any.
license	The license for this document, if any. Creative Commons licenses CC BY, CC BY-SA, CC BY-ND, CC BY-NC, CC BY-NC-SA, and CC BY-NC-ND will automatically generate a license link in the document appendix. Other license text will be placed in the appendix verbatim.
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.

Website

search	Setting this to false prevents this document from being included in searches.
repo-actions	Setting this to false prevents the repo-actions from appearing on this page.
aliases	URLs that alias this document, when included in a website.
image	The path to a preview image for this content. By default, Quarto will use the image value from the site: metadata. If you provide an image, you may also optionally provide an image-width and image-height to improve the appearance of your Twitter Card. If image is not provided, Quarto will automatically attempt to locate a preview image.
image-height	The height of the preview image for this document.
image-width	The width of the preview image for this document.
image-alt	The alt text for preview image on this page.
image-lazy-loading	Enables lazy loading for the preview image. If true, the preview image element will have loading="lazy", and will only load when it comes into view. If false, the preview image will load immediately.

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.