网站选项

以下是website项目所有可用选项的文档。有关使用Quarto创建网站的深入指南，请参阅创建一个网站。

项目

定义项目类型、渲染目标和输出的选项。项目选项在 project 键下指定。例如：

_quarto.yml

project:
  type: website
  output-dir: _site

`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 键下指定控制 quarto preview 行为的选项。例如：

_quarto.yml

project:
  type: website
  output-dir: _site
  preview:
    port: 4200
    browser: false

可用的 preview 选项包括：

`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

服务

如果你正在为包含自己的预览服务器的另一个发布系统创建项目扩展（例如，Hugo 或 Docusaurus），那么使用 preview: serve 选项来自定义预览服务器的行为。

_quarto.yml

project:
  type: website
    preview:
      serve:
        cmd: "hugo serve --port {port} --bind {host} --navigateToChanged"
        env:
          HUGO_RELATIVEURLS: "true"
        ready: "Web Server is available at"

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

参见 Hugo 和 Docusaurus 扩展源代码，了解 preview: serve 的示例用法。

网站

影响website输出的选项。网站选项在website键下指定。例如：

_quarto.yml

website:
  title: "我的网站"
  image: opengraph.png
  page-navigation: true

`title`	Website title
`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
`announcement`	An announcement displayed at the top of the page. (see Announcement)
`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.
`drafts`	A list of input documents that should be treated as drafts. Read more at Website Drafts.
`draft-mode`	How to handle drafts that are encountered. `visible` - the draft will visible and fully available `unlinked` - the draft will be rendered, but will not appear in navigation, search, or listings. `gone` - the draft will have no content and will not be linked to (default).

导航栏

定义website顶部导航栏的选项。例如：

_quarto.yml

website:
  navbar:
    search: true

`title`	The navbar title. Uses the project title if none is specified.
`logo`	Path to a logo image that will be displayed to the left of the title.
`logo-alt`	Alternate text for the logo image.
`logo-href`	Target href from navbar logo / title. By default, the logo and title link to the root page of the site (/index.html).
`background`	The navbar’s background color (named or hex color).
`foreground`	The navbar’s foreground color (named or hex color).
`search`	Include a search box in the navbar.
`pinned`	Always show the navbar (keeping it pinned).
`collapse`	Collapse the navbar into a menu when the display becomes narrow.
`collapse-below`	The responsive breakpoint below which the navbar will collapse into a menu (`sm`, `md`, `lg` (default), `xl`, `xxl`).
`left`	List of items for the left side of the navbar (see Nav Items)
`right`	List of items for the right side of the navbar (see Nav Items)
`toggle-position`	The position of the collapsed navbar toggle when in responsive mode
`tools-collapse`	Collapse tools into the navbar menu when the display becomes narrow.

导航项

导航项出现在navbar定义的left或right键中，或sidebar定义的contents键中。例如：

_quarto.yml

website:
  navbar:
    right:
      - icon: github
        href: https://github.com/
        aria-label: GitHub

`aria-label`	Accessible label for the item.
`href`	Link to file contained with the project or external URL
`icon`	Name of bootstrap icon (e.g. `github`, `twitter`, `share`) See https://icons.getbootstrap.com/ for a list of available icons
`menu`	Submenu of navigation items
`text`	Text to display for item (defaults to the document title if not provided)
`rel`	Value for rel attribute. Multiple space-separated values are permitted. See https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel for a details.
`target`	Value for target attribute. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target for details.

请注意，icon选项适用于导航栏中的项目，但侧边栏中的项目不支持icon选项。

侧边栏

定义website侧边导航区域的选项。例如：

_quarto.yml

website:
  sidebar:
    search: true

`id`	The identifier for this sidebar.
`title`	The sidebar title. Uses the project title if none is specified.
`logo`	Path to a logo image that will be displayed in the sidebar.
`logo-alt`	Alternate text for the logo image.
`logo-href`	Target href from navbar logo / title. By default, the logo and title link to the root page of the site (/index.html).
`search`	Include a search control in the sidebar.
`tools`	List of sidebar tools (see Sidebar Tools)
`contents`	List of navigation items to appear in the sidebar. Can also include `section` entries which in turn contain sub-lists of navigation items.
`style`	The style of sidebar (`docked` or `floating`).
`background`	The sidebar’s background color (named or hex color).
`foreground`	The sidebar’s foreground color (named or hex color).
`border`	Whether to show a border on the sidebar (defaults to true for ‘docked’ sidebars)
`alignment`	Alignment of the items within the sidebar (`left`, `right`, or `center`)
`collapse-level`	The depth at which the sidebar contents should be collapsed by default.
`pinned`	When collapsed, pin the collapsed sidebar to the top of the page.
`header`	Markdown to place above sidebar content (text or file path)
`footer`	Markdown to place below sidebar content (text or file path)

侧边栏工具

出现在侧边栏上的操作按钮。例如：

_quarto.yml

website:
  sidebar:
    tools:
      - icon: github
        href: https://github.com/

`icon`	Name of bootstrap icon (e.g. `github`, `twitter`, `share`) See https://icons.getbootstrap.com/ for a list of available icons
`href`	Link to file contained with the project or external URL
`menu`	Submenu of navigation items

公告

出现在网站顶部的公告。例如：

---
website:
  announcement: 
    content: "**New** - this is an announcement" 
    position: below-navbar 
---

`content`	The content of the announcement
`dismissable`	Whether this announcement may be dismissed by the user.
`icon`	Name of bootstrap icon (e.g. `github`, `twitter`, `share`) for the announcement. See https://icons.getbootstrap.com/ for a list of available icons
`position`	The position of the announcement. One of `above-navbar` (default) or `below-navbar`.
`type`	The type of announcement. One of `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light` or `dark`. Affects the appearance of the announcement.

页脚

网站页面页脚定义。例如：

_quarto.yml

website:
  page-footer:
    center: 
      - text: "About"
        href: about.qmd
      - text: "License"
        href: license.md
      - text: "Trademark"
        href: trademark.qmd

`left`	Footer left content
`right`	Footer right content
`center`	Footer center content
`border`	Footer border (`true`, `false`, or a border color)
`background`	Footer background color
`foreground`	Footer foreground color

搜索

搜索选项在website的search键下指定。例如：

_quarto.yml

website:
  search:
    location: navbar
    type: overlay

`location`	Location for search widget (`navbar` or `sidebar`)
`type`	Type of search UI (`overlay` or `textbox`)
`limit`	Number of matches to display (defaults to 20)
`collapse-after`	Matches after which to collapse additional results
`copy-button`	Provide button for copying search link
`keyboard-shortcut`	One or more keys that will act as a shortcut to launch search (single characters)
`show-item-context`	Whether to include search result parents when displaying items in search results (when possible).
`algolia`	Use an Algolia index for site search (see Algolia Options)

Algolia 选项

您可以使用Algolia索引作为website搜索的后端。使用search的algolia子键指定Algolia选项，例如：

_quarto.yml

website:
  search:
    algolia:
      index-name: <my-index-name>
      application-id: <my-application-id>
      search-only-api-key: <my-search-only-api-key>

`index-name`	The name of the index to use when performing a search
`application-id`	The unique ID used by Algolia to identify your application
`search-only-api-key`	The Search-Only API key to use to connect to Algolia
`analytics-events`	Enable tracking of Algolia analytics events
`show-logo`	Enable the display of the Algolia logo in the search results footer.
`index-fields`	Fields to target for searches (see below for details)
`params`	Additional parameters to pass when executing a search

index-fields选项提供了Algolia索引中的子字段，用于搜索目标：

`href`	Field that contains the URL of index entries
`title`	Field that contains the title of index entries
`text`	Field that contains the text of index entries
`section`	Field that contains the section of index entries

社交

社交元数据作为website选项的子键提供。您可以指定true以使用一组默认选项生成社交元数据，或指定以下列出的一个或多个Twitter或Open Graph特定选项。例如：

_quarto.yml

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

Twitter 卡片

在twitter-card键下设置Twitter选项：

_quarto.yml

website:
  twitter-card: 
    site: "@sitehandle"

`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

在open-graph键下设置Open Graph选项：

_quarto.yml

website:
  open-graph: 
    title: "Title for 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.

您可以使用Hypothesis、Utterances或Giscus为您的website添加评论功能。

Hypothesis

通过comments键启用和配置Hypothesis评论。例如：

_quarto.yml

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.

有关上述Hypothesis选项的更多文档，请参阅Hypothesis Publisher Config文档。

Utterances

通过comments键启用和配置Utterances评论。例如：

_quarto.yml

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

通过comments键启用和配置Giscus app的使用。例如：

_quarto.yml

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: theme: 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.

列表

列表使您能够根据一组 Quarto 文档或其他自定义数据自动生成页面（或页面区域）的内容。您可以通过在文档前文中使用 listing 选项来启用页面上的列表。例如，设置 listing: default 将生成目录中所有文档的列表（当前文档除外）：

---
title: "列表示例"
listing: default
---

要自定义列表，请在 listing 键下指定其他选项：

---
title: "列表示例"
listing: 
  contents: posts
  type: grid
  grid-columns: 2
---

`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-lazy-loading`	If false, images in the listing will be loaded immediately. If true, images will be loaded as they come into view.
`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 选项，为您的列表启用 RSS 订阅源：

---
title: "列表示例"
listing:
  contents: posts
  feed:
    items: 10
---

`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 键下指定关于页面选项：

---
title: 关于
about:
  template: jolla
  image: profile.jpg
  links:
    - icon: twitter
      text: twitter
      href: https://twitter.com
---

更多信息，请参阅关于页面文档。

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