网站搜索

概述

Quarto 支持对网站和书籍进行全文搜索。默认情况下，Quarto 将自动索引您网站的内容，并使用本地构建的索引使其可搜索。您还可以配置 Quarto 搜索以使用托管的 Algolia 索引。

搜索外观

默认情况下，网站和书籍的搜索功能是启用的。如果网站有导航栏，搜索界面将出现在导航栏上，否则将出现在侧边栏上。您可以使用以下选项控制搜索的位置：

选项	描述
`location`	`navbar` 或 `sidebar`（如果页面存在导航栏，则默认为 `navbar`）。
`type`	`overlay` 或 `textbox`（`overlay` 提供一个弹出搜索界面的按钮，`textbox` 则直接进行搜索）。

例如：

website:
  search: 
    location: navbar
    type: overlay

请注意，上述示例反映了默认行为，因此不需要明确指定。还要注意，默认情况下为网站启用搜索（您可以使用 search: false 禁用它）。

overlay 选项显示的搜索界面如下：

Quarto 页面带有 Algolia 搜索覆盖层，处于 '分离' 模式。搜索对话框背后的网页变暗，搜索对话框本身有一个输入文本的字段，并显示匹配文档的列表及其预览文本。

textbox 选项显示的搜索界面如下：

Algolia 搜索带有导航栏中的文本框。搜索对话框作为文本框的扩展在屏幕右侧打开。

当搜索显示为文本框时，默认情况下没有占位符文本。您可以使用 language 选项的 search-text-placeholder 键指定占位符文本（注意，这是在顶层，而不是在 website 选项内）：

language: 
  search-text-placeholder: 搜索

键盘快捷键

除了点击搜索界面外，用户还可以使用键盘快捷键 s、f 或 / 激活搜索。您可以通过指定 keyboard-shortcut 选项来覆盖这些快捷键。在这个示例中，搜索将通过 ? 或 H 激活：

website:
  search:
    keyboard-shortcut: ["?", "H"]

自定义结果

您可以使用以下 search 选项来自定义搜索结果的显示方式：

选项	描述
`limit`	在搜索结果中显示的结果数量。默认为 20。 \|
`collapse-after`	在显示“更多匹配”链接之前，显示与文档匹配的节数。默认为 2。 \|
`copy-button`	如果为true，搜索文本框将包含一个小图标，点击该图标会将搜索结果的URL复制到剪贴板（如果用户希望分享特定搜索及其结果，这很有用）。默认为false。 \| \|
`show-item-context`	控制是否在搜索结果的项目旁边显示页面父级。使用`tree`、`parent`、`root`或布尔值（如果为true，默认使用`tree`）。例如，`tree`结果显示为“指南 > 创作 > 图表”： \| \|

使用Algolia

除了内置的搜索功能外，Quarto网站还可以配置为使用外部Algolia搜索索引。在渲染网站时，Quarto将生成一个JSON文件（位于站点输出目录中的search.json），该文件可用于更新Algolia索引。有关使用Algolia创建索引的更多信息，请参阅发送和更新您的数据。

基本配置

为了让Quarto连接到您的Algolia索引，您需要在Quarto项目文件中提供基本的连接信息。您可以在Algolia仪表板的API密钥部分找到此连接信息。以下是所需的基本连接信息：

选项	描述 \|
`index-name`	执行搜索时使用的索引名称。 \|
`application-id`	Algolia用于标识您的应用程序的唯一ID。 \|
`search-only-api-key`	用于连接到 Algolia 的仅搜索 API 密钥。 \| Important 请确保使用仅搜索 API 密钥，该密钥仅提供对索引的只读访问权限，并且可以安全地包含在项目文件中。切勿在 Quarto 文档或项目中使用管理员 API 密钥。 \|
`show-logo`	在搜索结果的页脚中显示“由 Algolia 提供搜索”的标志。 \|

例如：

website:
  search:
    algolia:
      index-name: <我的索引名称>
      application-id: <我的应用程序ID>
      search-only-api-key: <我的仅搜索API密钥>

自定义索引模式

如果你只是使用 Quarto 生成的 search.json 文件作为 Algolia 索引，那么上述配置信息就足以设置使用 Algolia 进行搜索。

然而，如果你以其他方式生成索引，你可能需要提供额外的信息来指定 Quarto 在搜索时应使用哪些字段。你可以通过在 algolia 下包含一个 index-fields 键来实现这一点，该键指定索引中特定字段的名称。

选项	描述
`href`	用于读取此索引条目 URL 的字段。当用户选择匹配的搜索结果时，他们将被导航到此 URL。请注意，Quarto 按 URL 对结果进行分组（分组时不包括锚点）。 \| 此字段是必需的（可以作为索引中的现有字段或映射的字段名称）。 \|
`title`	用于读取索引条目标题的字段。此字段是必需的（可以作为索引中的现有字段或映射的字段名称）。 \|

`text`	用于读取索引条目文本的字段。此字段是必需的（可以是索引中的现有字段或映射的字段名称）。
`section`	用于读取索引条目部分的字段。Quarto 通过 URL 对结果进行分组，并使用部分信息（如果存在）来显示同一文档的匹配子部分。此字段是可选的。

以上任何或所有字段都可以在您的 Quarto 项目文件中指定。例如：

website:
  search:
    algolia:
      index-name: <我的索引名称>
      application-id: <我的应用程序ID>
      search-only-api-key: <我的只搜索API密钥>
      index-fields:
        href: url
        section: sec
        text: body

Algolia 洞察

默认情况下，Algolia 根据您的 Algolia 搜索性能提供多种洞察。此外，了解查看和点击结果的详细跟踪可能会有所帮助。您可以通过将 analytics-events 设置为 true 来启用 Algolia 的点击和转化跟踪：

website:
  search:
    algolia:
      index-name: <我的索引名称>
      application-id: <我的应用程序ID>
      search-only-api-key: <我的只搜索API密钥>
      analytics-events: true

您可以使用事件调试器确认事件是否正确发送到 Algolia。请注意，点击和转化事件使用 cookie 来维护匿名用户标识符——如果启用了 cookie 同意，则只有在授予了 cookie 同意后才会启用搜索事件。

高级配置

除了上述配置外，您还可以在执行搜索时传递 Algolia 特定的参数。例如，您可能希望将结果限制为特定的方面或一组标签。要指定参数，请将 params 键添加到您的 algolia yaml 并提供参数。有关可用参数的信息，请参阅 Algolia 的搜索 API 参数。

例如：

website:
  search:
    algolia:
      index-name: <我的索引名称>
      application-id: <我的应用程序ID>
      search-only-api-key: <我的只搜索API密钥>
    index-fields:
      href: url
      section: sec
      text: body
    params:
      tagFilters: ['标签1','标签2']

禁用搜索

您可以通过在文档元数据中添加 search: false 来禁用单个文档的搜索。例如：

---
title: "我的文档"
search: false
---

如果您希望禁用整个网站的搜索支持，可以在 _quarto.yml 文件中包含以下内容：

website:
  search: false