Book Options

All available options for book projects are documented below. See Creating a Book for an in-depth guide to creating books with Quarto.

Project

Options that define the type, render targets, and output of a project. Project options are specified under the project key. For example:

---
project:
  type: book
  output-dir: _book
---
title
type

Project type (default, website, book, or manuscript)

render

Files to render (defaults to all files)

execute-dir

Control the working directory for computations.

  • file: Use the directory of the file that is currently executing.
  • project: Use the root directory of the project.
output-dir

Output directory

lib-dir

HTML library (JS/CSS/etc.) directory

resources

Additional file resources to be copied to output directory

preview

Options for quarto preview (see Preview)

pre-render

Scripts to run as a pre-render step

post-render

Scripts to run as a post-render step

Preview

Specify options that control the behavior of quarto preview within the preview key. For example:

---
project:
  type: book
  output-dir: _book
  preview:
    port: 4200
    browser: false
---

Available preview options include:

port

Port to listen on (defaults to random value between 3000 and 8000)

host

Hostname to bind to (defaults to 127.0.0.1)

serve

Options for external preview server (see Serve)

browser

Open a web browser to view the preview (defaults to true)

watch-inputs

Re-render input files when they change (defaults to true)

navigate

Navigate the browser automatically when outputs are updated (defaults to true)

timeout

Time (in seconds) after which to exit if there are no active clients

Serve

If you are creating a project extension for another publishing system that includes its own preview server (for example, Hugo or Docusaurus) then use the preview: serve options to customize the behavior of the preview server.

cmd

Serve project preview using the specified command. Interpolate the --port into the command using {port}.

args

Additional command line arguments for preview command.

env

Environment variables to set for preview command.

ready

Regular expression for detecting when the server is ready.

See the Hugo and Docusaurus extension source code for example usages of preview: serve.

Book

Options that affect book output. Book options are specified under the book key. For example:

---
book:
  title: "My Book"
  image: opengraph.png
  page-navigation: true
---
title

Book title

subtitle

Book subtitle

author

Author or authors of the book

date

Book publication date

date-format

Format string for dates in the book

abstract

Book abstract

description

Description metadata for HTML version of book

references

Book references file

output-file

Base name for single-file output (e.g. PDF, ePub)

cover-image

Cover image (used in HTML and ePub formats)

cover-image-alt

Alternative text for cover image (used in HTML format)

sharing

Sharing buttons to include on navbar or sidebar (one or more of twitter, facebook, linkedin)

downloads

Download buttons for other formats to include on navbar or sidebar (one or more of pdf, epub, and docx)

tools

Custom tools for navbar or sidebar

doi

The Digital Object Identifier for this book.

abstract-url

A url to the abstract for this item.

accessed

Date the item has been accessed.

annote

Short markup, decoration, or annotation to the item (e.g., to indicate items included in a review);

For descriptive text (e.g., in an annotated bibliography), use note instead

archive

Archive storing the item

archive-collection

Collection the item is part of within an archive.

archive-location

Storage location within an archive (e.g. a box and folder number).

archive-place

Geographic location of the archive.

authority

Issuing or judicial authority (e.g. “USPTO” for a patent, “Fairfax Circuit Court” for a legal case).

available-date

Date the item was initially available (e.g. the online publication date of a journal article before its formal publication date; the date a treaty was made available for signing).

call-number

Call number (to locate the item in a library).

chair

The person leading the session containing a presentation (e.g. the organizer of the container-title of a speech).

chapter-number

Chapter number (e.g. chapter number in a book; track number on an album).

citation-key

Identifier of the item in the input data file (analogous to BiTeX entrykey);

Use this variable to facilitate conversion between word-processor and plain-text writing systems; For an identifer intended as formatted output label for a citation (e.g. “Ferr78”), use citation-label instead

citation-label

Label identifying the item in in-text citations of label styles (e.g. “Ferr78”);

May be assigned by the CSL processor based on item metadata; For the identifier of the item in the input data file, use citation-key instead

collection-editor

Editor of the collection holding the item (e.g. the series editor for a book).

collection-number

Number identifying the collection holding the item (e.g. the series number for a book)

collection-title

Title of the collection holding the item (e.g. the series title for a book; the lecture series title for a presentation).

compiler

Person compiling or selecting material for an item from the works of various persons or bodies (e.g. for an anthology).

composer

Composer (e.g. of a musical score).

container-author

Author of the container holding the item (e.g. the book author for a book chapter).

container-title

Title of the container holding the item (e.g. the book title for a book chapter, the journal title for a journal article; the album title for a recording; the session title for multi-part presentation at a conference)

contributor

A minor contributor to the item; typically cited using “with” before the name when listed in a bibliography.

curator

Curator of an exhibit or collection (e.g. in a museum).

dimensions

Physical (e.g. size) or temporal (e.g. running time) dimensions of the item.

director

Director (e.g. of a film).

division

Minor subdivision of a court with a jurisdiction for a legal item

edition

(Container) edition holding the item (e.g. “3” when citing a chapter in the third edition of a book).

editor

The editor of the item.

editorial-director

Managing editor (“Directeur de la Publication” in French).

editor-translator

Combined editor and translator of a work.

The citation processory must be automatically generate if editor and translator variables are identical; May also be provided directly in item data.

event-date

Date the event related to an item took place.

event-title

Name of the event related to the item (e.g. the conference name when citing a conference paper; the meeting where presentation was made).

event-place

Geographic location of the event related to the item (e.g. “Amsterdam, The Netherlands”).

executive-producer

Executive producer of the item (e.g. of a television series).

fulltext-url

A url to the full text for this item.

genre

Type, class, or subtype of the item (e.g. “Doctoral dissertation” for a PhD thesis; “NIH Publication” for an NIH technical report);

Do not use for topical descriptions or categories (e.g. “adventure” for an adventure movie)

guest

Guest (e.g. on a TV show or podcast).

host

Host of the item (e.g. of a TV show or podcast).

id

A value which uniquely identifies this item.

illustrator

Illustrator (e.g. of a children’s book or graphic novel).

interviewer

Interviewer (e.g. of an interview).

isbn

International Standard Book Number (e.g. “978-3-8474-1017-1”).

issn

International Standard Serial Number.

issue

Issue number of the item or container holding the item (e.g. “5” when citing a journal article from journal volume 2, issue 5);

Use volume-title for the title of the issue, if any.

issued

Date the item was issued/published.

jurisdiction

Geographic scope of relevance (e.g. “US” for a US patent; the court hearing a legal case).

keyword

Keyword(s) or tag(s) attached to the item.

language

The language of the item (used only for citation of the item).

Should be entered as an ISO 639-1 two-letter language code (e.g. “en”, “zh”), optionally with a two-letter locale code (e.g. “de-DE”, “de-AT”).

This does not change the language of the item, instead it documents what language the item uses (which may be used in citing the item).

license

The license information applicable to an item (e.g. the license an article or software is released under; the copyright information for an item; the classification status of a document)

locator

A cite-specific pinpointer within the item (e.g. a page number within a book, or a volume in a multi-volume work).

Must be accompanied in the input data by a label indicating the locator type (see the Locators term list).

medium

Description of the item’s format or medium (e.g. “CD”, “DVD”, “Album”, etc.)

narrator

Narrator (e.g. of an audio book).

note

Descriptive text or notes about an item (e.g. in an annotated bibliography).

number

Number identifying the item (e.g. a report number).

number-of-pages

Total number of pages of the cited item.

number-of-volumes

Total number of volumes, used when citing multi-volume books and such.

organizer

Organizer of an event (e.g. organizer of a workshop or conference).

original-author

The original creator of a work (e.g. the form of the author name listed on the original version of a book; the historical author of a work; the original songwriter or performer for a musical piece; the original developer or programmer for a piece of software; the original author of an adapted work such as a book adapted into a screenplay)

original-date

Issue date of the original version.

original-publisher

Original publisher, for items that have been republished by a different publisher.

original-publisher-place

Geographic location of the original publisher (e.g. “London, UK”).

original-title

Title of the original version (e.g. “Война и мир”, the untranslated Russian title of “War and Peace”).

page

Range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue).

page-first

First page of the range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue).

page-last

Last page of the range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue).

part-number

Number of the specific part of the item being cited (e.g. part 2 of a journal article).

Use part-title for the title of the part, if any.

part-title

Title of the specific part of an item being cited.

pdf-url

A url to the pdf for this item.

performer

Performer of an item (e.g. an actor appearing in a film; a muscian performing a piece of music).

pmcid

PubMed Central reference number.

pmid

PubMed reference number.

printing-number

Printing number of the item or container holding the item.

producer

Producer (e.g. of a television or radio broadcast).

public-url

A public url for this item.

publisher

The publisher of the item.

publisher-place

The geographic location of the publisher.

recipient

Recipient (e.g. of a letter).

reviewed-author

Author of the item reviewed by the current item.

reviewed-genre

Type of the item being reviewed by the current item (e.g. book, film).

reviewed-title

Title of the item reviewed by the current item.

scale

Scale of e.g. a map or model.

script-writer

Writer of a script or screenplay (e.g. of a film).

section

Section of the item or container holding the item (e.g. “§2.0.1” for a law; “politics” for a newspaper article).

series-creator

Creator of a series (e.g. of a television series).

source

Source from whence the item originates (e.g. a library catalog or database).

status

Publication status of the item (e.g. “forthcoming”; “in press”; “advance online publication”; “retracted”)

submitted

Date the item (e.g. a manuscript) was submitted for publication.

supplement-number

Supplement number of the item or container holding the item (e.g. for secondary legal items that are regularly updated between editions).

translator

Translator

type

The type of the item.

url

Uniform Resource Locator (e.g. “https://aem.asm.org/cgi/content/full/74/9/2766”)

version

Version of the item (e.g. “2.0.9” for a software program).

volume

Volume number of the item (e.g. “2” when citing volume 2 of a book) or the container holding the item (e.g. “2” when citing a chapter from volume 2 of a book).

Use volume-title for the title of the volume, if any.

volume-title

Title of the volume of the item or container holding the item.

Also use for titles of periodical special issues, special sections, and the like.

year-suffix

Disambiguating year suffix in author-date styles (e.g. “a” in “Doe, 1999a”).

description

Website description

favicon

The path to the favicon for this website

site-url

Base URL for published website

site-path

Path to site (defaults to /). Not required if you specify site-url.

repo-url

Base URL for website source code repository

repo-link-target

The value of the target attribute for repo links

repo-link-rel

The value of the rel attribute for repo links

repo-subdir

Subdirectory of repository containing website

repo-branch

Branch of website source code (defaults to main)

issue-url

URL to use for the ‘report an issue’ repository action.

repo-actions

Links to source repository actions (none or one or more of edit, source, issue)

reader-mode

Displays a ‘reader-mode’ tool which allows users to hide the sidebar and table of contents when viewing a page.

google-analytics

Enable Google Analytics for this website

cookie-consent

Quarto includes the ability to request cookie consent before enabling scripts that set cookies, using Cookie Consent.

The user’s cookie preferences will automatically control Google Analytics (if enabled) and can be used to control custom scripts you add as well. For more information see Custom Scripts and Cookie Consent.

search

Site search (true or false to enable/disable, or provide custom Search Options

navbar

Navbar options (see Navbar)

sidebar

Sidebar options (see Sidebar)

body-header

Markdown to insert at the beginning of each page’s body (below the title and author block).

body-footer

Markdown to insert below each page’s body.

margin-header

Markdown to place above margin content (text or file path)

margin-footer

Markdown to place below margin content (text or file path)

page-navigation

Provide next and previous article links in footer

back-to-top-navigation

Provide a ‘back to top’ navigation button

bread-crumbs

Whether to show navigation breadcrumbs for pages more than 1 level deep

page-footer

Page footer. Text content or page footer definition.

image

Default site thumbnail image for twitter /open-graph

image-alt

Default site thumbnail image alt text for twitter /open-graph

comments
open-graph

Generate Open Graph metadata (see Open Graph options)

twitter-card

Generate Twitter Card metadata (see Twitter Card options)

other-links

A list of other links to appear below the TOC.

code-links

A list of code links to appear with this document.

Social

Social metadata is provided as a subkey of book options. You can specify true to generate social metadata using a set of default option, or specify one or more Twitter or Open Graph specific options as enumerated below. For example:

---
book:
  open-graph: true
  twitter-card: 
    site: "@sitehandle"
---

Twitter Card

title

The title of the page. Note that by default Quarto will automatically use the title metadata from the page. Specify this field if you’d like to override the title for this provider.

description

A short description of the content. Note that by default Quarto will automatically use the description metadata from the page. Specify this field if you’d like to override the description for this provider.

image

The path to a preview image for the content. By default, Quarto will use the image value from the format metadata. If you provide an image, you may also optionally provide an image-width and image-height.

image-alt

The alt text for the preview image. By default, Quarto will use the image-alt value from the format metadata. If you provide an image, you may also optionally provide an image-width and image-height.

image-width

Image width (pixels)

image-height

Image height (pixels)

card-style

Card style (summary or summary_large_image).

If this is not provided, the best style will automatically selected based upon other metadata. You can learn more about Twitter Card styles here.

creator

@username of the content creator (must be a quoted string)

site

@username of the website (must be a quoted string)

Open Graph

title

The title of the page. Note that by default Quarto will automatically use the title metadata from the page. Specify this field if you’d like to override the title for this provider.

description

A short description of the content. Note that by default Quarto will automatically use the description metadata from the page. Specify this field if you’d like to override the description for this provider.

image

The path to a preview image for the content. By default, Quarto will use the image value from the format metadata. If you provide an image, you may also optionally provide an image-width and image-height.

image-alt

The alt text for the preview image. By default, Quarto will use the image-alt value from the format metadata. If you provide an image, you may also optionally provide an image-width and image-height.

image-width

Image width (pixels)

image-height

Image height (pixels)

locale

Locale of open graph metadata

site-name

Name that should be displayed for the overall site. If not explicitly provided in the open-graph metadata, Quarto will use the website or book title by default.

Comments

You can add commenting to your book using either Hypothesis, Utterances, or Giscus.

Hypothesis

Enable and configure Hypothesis commenting via comments key. For example:

---
website:
  comments: 
    hypothesis:
      theme: clean
      openSidebar: false
---
client-url

Override the default hypothesis client url with a custom client url.

openSidebar

Controls whether the sidebar opens automatically on startup.

showHighlights

Controls whether the in-document highlights are shown by default (always, whenSidebarOpen or never)

theme

Controls the overall look of the sidebar (classic or clean)

enableExperimentalNewNoteButton

Controls whether the experimental New Note button should be shown in the notes tab in the sidebar.

usernameUrl

Specify a URL to direct a user to, in a new tab. when they click on the annotation author link in the header of an annotation.

services

Array of service definitions

branding

Custom branding/colors to apply to UI

externalContainerSelector

A CSS selector specifying the containing element into which the sidebar iframe will be placed.

focus

User focused filter set for the available annotations on a page

requestConfigFromFrame

Specify a host iframe to request configuration from

assetRoot

The root URL from which assets are loaded.

sidebarAppUrl

The URL for the sidebar application which displays annotations.

For additional documentation on the Hypothesis options enumerated above, see the Hypothesis Publisher Config documentation.

Utterances

Enable and configure Utterances commenting via the comments key. For example:

---
website:
  comments: 
    utterances:
      repo: quarto-dev/quarto-web
---
repo

The Github repo that will be used to store comments.

label

The label that will be assigned to issues created by Utterances.

theme

The Github theme that should be used for Utterances (github-light, github-dark, github-dark-orange, icy-dark, dark-blue, photon-dark, body-light, or gruvbox-dark)

issue-term

How posts should be mapped to Github issues (pathname, url, title or og:title)

Giscus

Enable and configure usage of the Giscus app via the comments key. For example:

---
website:
  comments:
    giscus:
      repo: quarto-dev/quarto-web
---
repo

The Github repo that will be used to store comments.

In order to work correctly, the repo must be public, with the giscus app installed, and the discussions feature must be enabled.

repo-id

The Github repository identifier.

You can quickly find this by using the configuration tool at https://giscus.app. If this is not provided, Quarto will attempt to discover it at render time.

category

The discussion category where new discussions will be created. It is recommended to use a category with the Announcements type so that new discussions can only be created by maintainers and giscus.

category-id

The Github category identifier.

You can quickly find this by using the configuration tool at https://giscus.app. If this is not provided, Quarto will attempt to discover it at render time.

mapping

The mapping between the page and the embedded discussion.

  • pathname: The discussion title contains the page path
  • url: The discussion title contains the page url
  • title: The discussion title contains the page title
  • og:title: The discussion title contains the og:title metadata value
  • any other string or number: Any other strings will be passed through verbatim and a discussion title containing that value will be used. Numbers will be treated as a discussion number and automatic discussion creation is not supported.
reactions-enabled

Display reactions for the discussion’s main post before the comments.

loading

Specify loading: lazy to defer loading comments until the user scrolls near the comments container.

input-position

Place the comment input box above or below the comments.

theme

The giscus theme to use when displaying comments. Light and dark themes are supported. If a single theme is provided by name, it will be used as light and dark theme. To use different themes, use light and dark key:

website:
  comments:
    giscus:
      light: light # giscus theme used for light website theme
      dark: dark_dimmed # giscus theme used for dark website theme
language

The language that should be used when displaying the commenting interface.

Listings

Listings enable you to automatically generate the contents of a page (or region of a page) from a list of Quarto documents or other custom data. You can enable listings on a page using the listing option in the document front matter, for example:

---
title: "Listing Example"
listing: default
---
id

The id of this listing. When the listing is rendered, it will place the contents into a div with this id. If no such div is defined on the page, a div with this id will be created and appended to the end of the page.

If no id is provided for a listing, Quarto will synthesize one when rendering the page.

type

The type of listing to create. Choose one of:

  • default: A blog style list of items
  • table: A table of items
  • grid: A grid of item cards
  • custom: A custom template, provided by the template field
contents

The files or path globs of Quarto documents or YAML files that should be included in the listing.

sort

Sort items in the listing by these fields. The sort key is made up of a field name followed by a direction asc or desc.

For example: date asc

Use sort:false to use the unsorted original order of items.

max-items

The maximum number of items to include in this listing.

page-size

The number of items to display on a page.

sort-ui

Shows or hides the sorting control for the listing. To control the fields that will be displayed in the sorting control, provide a list of field names.

filter-ui

Shows or hides the filtering control for the listing. To control the fields that will be used to filter the listing, provide a list of field names. By default all fields of the listing will be used when filtering.

categories

Display item categories from this listing in the margin of the page.

  • numbered: Category list with number of items
  • unnumbered: Category list
  • cloud: Word cloud style categories
feed

Create an RSS feed for this page using the items in this listing (see Feed).

date-format

The date format to use when displaying dates (e.g. d-M-yyy). Learn more about supported date formatting values here.

max-description-length

The maximum length (in characters) of the description displayed in the listing. Defaults to 175.

image-placeholder

The default image to use if an item in the listing doesn’t have an image.

image-align

In default type listings, whether to place the image on the right or left side of the post content (left or right).

image-height

The height of the image being displayed (a CSS height string).

The width is automatically determined and the image will fill the rectangle without scaling (cropped to fill).

grid-columns

In grid type listings, the number of columns in the grid display. Defaults to 3.

grid-item-border

In grid type listings, whether to display a border around the item card. Defaults to true.

grid-item-align

In grid type listings, the alignment of the content within the card (left (default), right, or center).

table-striped

In table type listings, display the table rows with alternating background colors. Defaults to false.

table-hover

In table type listings, highlight rows of the table when the user hovers the mouse over them. Defaults to false.

template

The path to a custom listing template.

template-params

Parameters that are passed to the custom template.

fields

The list of fields to include in this listing.

field-display-names

A mapping that provides display names for specific fields. For example, to display the title column as ‘Report’ in a table listing you would write:

listing:
  field-display-names:
  title: "Report"
field-types

Provides the date type for the field of a listing item. Unknown fields are treated as strings unless a type is provided. Valid types are date, number.

field-links

The list of fields to display as hyperlinks to the source document when the listing type is a table. By default, only the title or filename is displayed as a link.

field-required

Fields that items in this listing must have populated. If a listing is rendered and one more items in this listing is missing a required field, an error will occur and the render will.

include

Items with matching field values will be included in the listing.

exclude

Items with matching field values will be excluded from the listing.

Feed

Enable an RSS feed for your listing by including the feed option.

items

The number of items to include in your feed. Defaults to 20.

type

Whether to include full or partial content in the feed.

  • full (default): Include the complete content of the document in the feed.
  • partial: Include only the first paragraph of the document in the feed.
  • metadata: Use only the title, description, and other document metadata in the feed.
title

The title for this feed. Defaults to the site title provided the Quarto project.

image

The path to an image for this feed. If not specified, the image for the page the listing appears on will be used, otherwise an image will be used if specified for the site in the Quarto project.

description

The description of this feed. If not specified, the description for the page the listing appears on will be used, otherwise the description of the site will be used if specified in the Quarto project.

language

The language of the feed. Omitted if not specified. See https://www.rssboard.org/rss-language-codes for a list of valid language codes.

categories

A list of categories for which to create separate RSS feeds containing only posts with that category

xml-stylesheet

The path to an XML stylesheet (XSL file) used to style the RSS feed.

About

Layout a simple about page for an individual or organization. For more, see the About Pages documentation.

id

The target id of this about page. When the about page is rendered, it will place read the contents of a div with this id into the about template that you have selected (and replace the contents with the rendered about content).

If no such div is defined on the page, a div with this id will be created and appended to the end of the page.

template

The template to use to layout this about page. Choose from:

  • jolla
  • trestles
  • solana
  • marquee
  • broadside
image

The path to the main image on the about page. If not specified, the image provided for the document itself will be used.

image-alt

The alt text for the main image on the about page.

image-title

The title for the main image on the about page.

image-width

A valid CSS width for the about page image.

image-shape

The shape of the image on the about page.

  • rectangle
  • round
  • rounded
links

Links (as navigation items) to display on the about page.