Version main of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

搜索

允许用户通过可配置的搜索选项来搜索您的 Docsy 网站。

Docsy 提供了多种选项，让您的读者搜索您的网站内容，因此您可以选择适合您需求的选项。您可以选择：

[Google 自定义搜索引擎]（#configure-search-with-a-google-custom-search-engine）（GCSE），默认选项，它使用 Google 对您的公共网站的索引来生成搜索结果页面。
[Algolia DocSearch]（#algolia-docsearch），它使用 Algolia 的索引和搜索机制。搜索结果显示为弹出窗口。Algolia DocSearch 对公共文档网站免费。
[使用 Lunr 进行本地搜索]（#local-search-with-lunr），它使用 Javascript 索引和搜索您的站点，而无需连接到外部服务。此选项不要求您的网站是公开的。

如果在项目 configuration file 中启用这些搜索选项中的任何一个，则顶部导航栏右侧会显示一个搜索框。默认情况下，搜索框还会显示在左侧导航窗格中部分菜单的顶部，如果您愿意，或者如果您使用的搜索选项仅适用于顶部搜索框，则可以禁用该搜索框。

You can only enable a single search option at a time

如果您不小心在项目中启用了多个搜索选项配置文件，您将在构建时收到警告，并且未确定为您的网站提供服务时的行为。

禁用侧边栏搜索框

默认情况下，搜索框同时显示在顶部导航栏和侧边栏左侧导航窗格的顶部。如果您不想要侧边栏搜索框，请在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中将站点参数 ‘sidebar_search_disable’ 设置为 ’true’：

[params.ui]
sidebar_search_disable = true

params:
  ui:
    sidebar_search_disable: true

{
  "params": {
    "ui": {
      "sidebar_search_disable": true
    }
  }
}

使用 Google 自定义搜索引擎配置搜索

默认情况下，Docsy 使用 [Google 自定义搜索引擎]（https://cse.google.com/cse/all）（GCSE）来搜索您的网站。要启用此功能，您首先需要确保已构建并部署了 [网站的生产版本]（/docs/deployment#build-environments-and-indexing），否则您的网站将不会被抓取和索引。

设置网站搜索

点击[自定义搜索页面]（https://cse.google.com/cse/all）上的新搜索引擎，然后按照说明为已部署的网站创建Google自定义搜索引擎。记下新搜索引擎的 ID。
使用“编辑搜索引擎”选项将您想要的任何其他配置添加到搜索引擎中。具体而言，您可能希望执行以下操作：

选择外观和感觉。从默认的“叠加”布局更改为“仅结果**”，因为此选项意味着您的搜索结果将嵌入到搜索页面中，而不是显示在单独的框中。单击“保存”以保存更改。
- 编辑默认结果链接行为，以便您网站的搜索结果不会在新标签页中打开。为此，请选择“搜索功能”-“高级”-“Web搜索设置”。在“链接目标”字段中，键入“_parent”。单击“保存”以保存更改。

Tip

Your site search results should show up within a couple of days. If it takes longer than that, you can manually request that your site is indexed by submitting a sitemap through the Google Search Console.

添加搜索页面

设置搜索引擎后，您可以将该功能添加到您的网站：

确保在“content/en/search.md”中有一个 Markdown 文件（如果需要，其他语言也有一个文件）来显示您的搜索结果。它只需要一个标题和“layout： search”，如以下示例所示：
```
+++
title = "Search Results"
layout = "search"
+++
```
```
---
title: Search Results
layout: search
---
```
```
{
    "title": "Search Results",
    "layout": "search"
}
```

将您的 Google 自定义搜索引擎 ID 添加到“hugo.toml”/“hugo.yaml”/“hugo.json”中的网站参数中。如果需要，您可以为每种语言添加不同的值。

[params]
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "011737558837375720776:fsdu1nryfng"

params:
  gcs_engine_id: 011737558837375720776:fsdu1nryfng

{
  "params": {
    "gcs_engine_id": "011737558837375720776:fsdu1nryfng"
  }
}

禁用GCSE搜索

如果您没有为项目指定 Google 自定义搜索引擎 ID，并且未启用任何其他搜索选项，则搜索框不会显示在您的网站中。如果您使用示例站点中的默认“hugo.toml”并想要禁用搜索，只需注释掉或删除相关行即可。

Algolia 文档搜索

作为GCSE的替代方法，您可以使用[AlgoliaDocSearch]（https://docsearch.algolia.com），即对公共文档站点免费。Docsy 支持 Algolia DocSearch v3。

Algolia v2 is deprecated

Docsy 以前支持 Algolia DocSearch v2，现已弃用。如果你是现有的 Algolia DocSearch v2 用户，并希望使用最新的 Docsy版本，[跟随迁移指令]（https://docsearch.algolia.com/docs/migrating-from-v2）用于更新 DocSearch 代码片段的 DocSearch 文档。

注册 Algolia DocSearch

填写https://docsearch.algolia.com/apply的表格。收到 Algolia DocSearch 后继续下一步项目的参数。

渴望测试 DocSearch？

Docsy 默认为 Algolia test-site 参数不提供任何信息。要启用对 Algolia 测试的搜索，请定义’params.search.algolia’，没有任何其他字段，如下所述。

配置 Algolia DocSearch

确保禁用 [GCSE 搜索]（#disabling-gcse-search）。

将项目的 Algolia DocSearch 参数添加到 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’，例如（使用 Algolia test 值）：

[params.search.algolia]
appId = "R2IYF7ETH7"
apiKey = "599cec31baffa4868cae4e79f180729b"
indexName = "docsearch"

params:
  search:
    algolia:
      appId: R2IYF7ETH7
      apiKey: 599cec31baffa4868cae4e79f180729b
      indexName: docsearch

{
  "params": {
    "search": {
      "algolia": {
        "appId": "R2IYF7ETH7",
        "apiKey": "599cec31baffa4868cae4e79f180729b",
        "indexName": "docsearch"
      }
    }
  }
}

要了解有关 Algolia DocSearch V3 的更多信息，请参阅 [get-started]（https://docsearch.algolia.com/docs/DocSearch-v3）。

完成这些步骤后，应在网站。搜索结果显示为弹出窗口，因此您无需添加任何搜索结果搜索结果页面。

自定义 Algolia 模板

您可以通过创建以下模板文件：

“head.html”使用的“layouts/partials/algolia/head.html”来加载 AlgoliaDocSearch 样式。它还会发出弃用警告’params.algolia_docsearch’。
“scripts.html”使用的“layouts/partials/algolia/scripts.html”来加载和配置 Algolia DocSearch。将任一文件留空以禁用 Docsy 的实现。

使用 Lunr 进行本地搜索

[伦尔]（https://lunrjs.com/）是一个基于 Javascript 的搜索选项，可让您为网站编制索引并使其可搜索，而无需外部服务器端搜索服务。这是一个不错的选择，特别是对于较小的或非公共网站。

要将 Lunr 搜索添加到您的 Docsy 网站：

在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中启用本地搜索。

[params]
offlineSearch = true

params:
  offlineSearch: true

{
  "params": {
    "offlineSearch": true
  }
}

删除或注释掉 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中的任何 GCSE ID，并确保 Algolia DocSearch 设置为 ‘false’，因为您只能启用一种类型的搜索。请参阅[禁用GCSE搜索]（#disabling-gcse-search）。

完成这些步骤后，将为您的网站启用本地搜索，并在使用搜索框时将结果显示在下拉列表中。

Tip

如果你使用 Hugo 的本地服务器功能 [在本地测试]（/docs/deployment/#serving-your-site-locally），你需要先通过运行 ‘hugo’ 来构建你的 ‘offline-search-index.xxx.json’ 文件。如果在构建“offline-search-index.xxx.json”时运行了 Hugo 服务器，则可能需要停止服务器并重新启动它才能查看搜索结果。

更改本地搜索结果的摘要长度

您可以通过在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中设置 ‘offlineSearchSummaryLength’ 来自定义摘要长度。

#Enable offline search with Lunr.js
[params]
offlineSearch = true
offlineSearchSummaryLength = 200

params:
  offlineSearch: true
  offlineSearchSummaryLength: 200

{
  "params": {
    "offlineSearch": true,
    "offlineSearchSummaryLength": 200
  }
}

更改本地搜索的最大结果计数

您可以通过在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中设置 ‘offlineSearchMaxResults’ 来自定义最大结果计数。

[params]
offlineSearch = true
offlineSearchMaxResults = 25

params:
  offlineSearch: true
  offlineSearchMaxResults: 25

{
  "params": {
    "offlineSearch": true,
    "offlineSearchMaxResults": 25
  }
}

更改本地搜索结果弹出窗口的宽度

搜索结果弹出窗口的宽度会根据内容自动变宽。

如果要限制宽度，请将以下 scss 添加到“assets/scss/_variables_project.scss”中。

.td-offline-search-results {
  max-width: 460px;
}

从本地搜索结果中排除页面

要从本地搜索结果中排除页面，请在每个页面的卷首添加“exclude_search： true”：

+++
title = "Index"
weight = 10
exclude_search = true
+++

---
title: "Index"
weight: 10
exclude_search: true
---

{
  "title": "Index",
  "weight": 10,
  "exclude_search": true
}

反馈

当前页面对你有帮助吗？

Glad to hear it!

Sorry to hear that. Please tell us how we can improve.

最后修改 July 6, 2024: Update search.md (ac17837)