docsy/userguide/content/en/docs/adding-content/search.md

431 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: Search
date: 2017-01-05
weight: 3.5
description: >
Let users search your Docsy site with a choice of configurable search options.
cSpell:ignore: GCSE
---
Docsy offers multiple options that let your readers search your site content, so
you can pick one that suits your needs or [design your own](#custom-search). You
can choose from:
- [Google Custom Search Engine](#configure-search-with-a-google-custom-search-engine)
(GCSE), the default option, which uses Google's index of your public site to
generate a search results page.
- [Algolia DocSearch](#algolia-docsearch), which uses Algolia's indexing and
search mechanism. Search results are displayed as a pop-up. Algolia DocSearch
is free for public documentation sites.
- [Local search with Lunr](#local-search-with-lunr), which uses Javascript to
index and search your site without the need to connect to external services.
This option doesn't require your site to be public.
If you enable any of these search options in your project [configuration file],
a search box displays in the right of your top navigation bar. By default a
search box also displays at the top of the section menu in the left navigation
pane, which you can disable if you prefer, or if you're using a search option
that only works with the top search box.
{{% alert title="You can only enable a single search option at a time" color=warning %}}
If you accidentally enable more than one search option in your project
configuration file, you will get a warning at build time, and undetermined
behavior when serving your site.
{{% /alert %}}
## Disabling the sidebar search box
By default, the search box appears in both the top navigation bar and at the top
of the sidebar left navigation pane. If you don't want the sidebar search box,
set the site parameter `sidebar_search_disable` to `true` in
`hugo.toml`/`hugo.yaml`/`hugo.json`:
<!-- prettier-ignore-start -->
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
[params.ui]
sidebar_search_disable = true
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
params:
ui:
sidebar_search_disable: true
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
"params": {
"ui": {
"sidebar_search_disable": true
}
}
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
## Configure search with a Google Custom Search Engine
By default Docsy uses a [Google Custom Search Engine][GCSE] (GCSE) to search
your site. To enable this feature, you'll first need to make sure that you have
built and deployed a
[production version of your site](/docs/deployment#build-environments-and-indexing),
as otherwise your site won't be crawled and indexed.
### Setting up site search
1. Create a Google Custom Search Engine for your deployed site by clicking
**New search engine** on the [Custom Search page][GCSE] and following the
instructions. Make a note of the ID for your new search engine.
1. Add any further configuration you want to your search engine using the
**Edit search engine** options. In particular you may want to do the
following:
- Select **Look and feel**. Change from the default **Overlay** layout to
**Results only**, as this option means your search results are embedded in
your search page rather than appearing in a separate box. Click **Save**
to save your changes.
- Edit the default result link behavior so that search results from your
site don't open in a new tab. To do this, select **Search Features** -
**Advanced** - **Websearch Settings**. In the **Link Target** field, type
"\_parent". Click **Save** to save your changes.
{{% alert title="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](https://support.google.com/webmasters/answer/183668?hl=en).
{{% /alert %}}
### Adding the search page
Once you have your search engine set up, you can add the feature to your site:
<!-- prettier-ignore-start -->
1. Ensure you have a Markdown file in `content/en/search.md` (and one per other
languages if needed) to display your search results. It only needs a title
and `layout: search`, as in the following example:
{{< tabpane >}}
{{< tab header="Front matter:" disabled=true />}}
{{< tab header="toml" lang="toml" >}}
+++
title = "Search Results"
layout = "search"
+++
{{< /tab >}}
{{< tab header="yaml" lang="yaml" >}}
---
title: Search Results
layout: search
---
{{< /tab >}}
{{< tab header="json" lang="json" >}}
{
"title": "Search Results",
"layout": "search"
}
{{< /tab >}}
{{< /tabpane >}}
1. Add your Google Custom Search Engine ID to the site params in
`hugo.toml`/`hugo.yaml`/`hugo.json`. You can add different values per
language if needed.
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
[params]
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "011737558837375720776:fsdu1nryfng"
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
params:
gcs_engine_id: 011737558837375720776:fsdu1nryfng
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
"params": {
"gcs_engine_id": "011737558837375720776:fsdu1nryfng"
}
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
### Disabling GCSE search
If you don't specify a Google Custom Search Engine ID for your project and
haven't enabled any other search options, the search box won't appear in your
site. If you're using the default `hugo.toml` from the example site and want to
disable search, just comment out or remove the relevant line.
## Algolia DocSearch
As an alternative to GCSE, you can use
[Algolia DocSearch](https://docsearch.algolia.com), which is free for public
documentation sites. Docsy supports **Algolia DocSearch v3**.
{{% alert title="Algolia v2 is deprecated" %}}
Docsy previously supported Algolia DocSearch v2, which is now deprecated. If you
are an existing Algolia DocSearch v2 user and want to use the latest Docsy
version, follow the
[migration instructions](https://docsearch.algolia.com/docs/migrating-from-v2)
in the DocSearch documentation to update your DocSearch code snippet.
{{% /alert %}}
### Sign up for Algolia DocSearch
Complete the form at <https://docsearch.algolia.com/apply>. Proceed to the next
step once you've received Algolia DocSearch parameters for your project.
### Eager to test DocSearch?
Docsy defaults to the [Algolia test][]-site parameters when none are provided.
To enable search over the Algolia test, define `params.search.algolia` without
any other fields, as outlined next.
### Configure Algolia DocSearch
<!-- prettier-ignore-start -->
1. Ensure that [GCSE search](#disabling-gcse-search) is disabled.
2. Add your project's Algolia DocSearch parameters to
`hugo.toml`/`hugo.yaml`/`hugo.json`, for example (using [Algolia test][]
values):
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
[params.search.algolia]
appId = "R2IYF7ETH7"
apiKey = "599cec31baffa4868cae4e79f180729b"
indexName = "docsearch"
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
params:
search:
algolia:
appId: R2IYF7ETH7
apiKey: 599cec31baffa4868cae4e79f180729b
indexName: docsearch
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
"params": {
"search": {
"algolia": {
"appId": "R2IYF7ETH7",
"apiKey": "599cec31baffa4868cae4e79f180729b",
"indexName": "docsearch"
}
}
}
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
To learn more about Algolia DocSearch V3, see
[Getting started](https://docsearch.algolia.com/docs/DocSearch-v3).
When you've completed these steps, Algolia search should be enabled on your
site. Search results are displayed as a pop-up, so you don't need to add any
search results page.
### Customizing Algolia templates
You can customize or disable Docsy's default Algolia support by creating the
following template files:
- `layouts/_partials/algolia/head.html` used by `head.html` to load Algolia
DocSearch styles. It also issues a deprecation warning for
`params.algolia_docsearch`.
- `layouts/_partials/algolia/scripts.html` used by `scripts.html` to load and
configure Algolia DocSearch.
Leave either file empty to disable Docsy's implementation.
## Local search with Lunr
[Lunr](https://lunrjs.com/) is a Javascript-based search option that lets you
index your site and make it searchable without the need for external,
server-side search services. This is a good option particularly for smaller or
non-public sites.
To add Lunr search to your Docsy site:
<!-- prettier-ignore-start -->
1. Enable local search in `hugo.toml`/`hugo.yaml`/`hugo.json`.
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
[params]
offlineSearch = true
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
params:
offlineSearch: true
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
"params": {
"offlineSearch": true
}
}
{{< /tab >}}
{{< /tabpane >}}
2. Remove or comment out any GCSE ID in `hugo.toml`/`hugo.yaml`/`hugo.json` and
ensure Algolia DocSearch is set to `false`, as you can only have one type of
search enabled. See [Disabling GCSE search](#disabling-gcse-search).
<!-- prettier-ignore-end -->
Once you've completed these steps, local search is enabled for your site and
results appear in a drop down when you use the search box.
{{% alert title="Tip" %}}
If you're [testing this locally](/docs/deployment/#serving-your-site-locally)
using Hugos local server functionality, you need to build your
`offline-search-index.xxx.json` file first by running `hugo`. If you have the
Hugo server running while you build `offline-search-index.xxx.json`, you may
need to stop the server and restart it in order to see your search results.
{{% /alert %}}
### Changing the summary length of the local search results
You can customize the summary length by setting `offlineSearchSummaryLength` in
`hugo.toml`/`hugo.yaml`/`hugo.json`.
<!-- prettier-ignore-start -->
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
#Enable offline search with Lunr.js
[params]
offlineSearch = true
offlineSearchSummaryLength = 200
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
params:
offlineSearch: true
offlineSearchSummaryLength: 200
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
"params": {
"offlineSearch": true,
"offlineSearchSummaryLength": 200
}
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
### Changing the maximum result count of the local search
You can customize the maximum result count by setting `offlineSearchMaxResults`
in `hugo.toml`/`hugo.yaml`/`hugo.json`.
<!-- prettier-ignore-start -->
{{< tabpane >}}
{{< tab header="Configuration file:" disabled=true />}}
{{< tab header="hugo.toml" lang="toml" >}}
[params]
offlineSearch = true
offlineSearchMaxResults = 25
{{< /tab >}}
{{< tab header="hugo.yaml" lang="yaml" >}}
params:
offlineSearch: true
offlineSearchMaxResults: 25
{{< /tab >}}
{{< tab header="hugo.json" lang="json" >}}
{
"params": {
"offlineSearch": true,
"offlineSearchMaxResults": 25
}
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
### Changing the width of the local search results popover
The width of the search results popover will automatically widen according to
the content.
If you want to limit the width, add the following scss into
`assets/scss/_variables_project.scss`.
```scss
.td-offline-search-results {
max-width: 460px;
}
```
### Excluding pages from local search results
To exclude pages from local search results, add `exclude_search: true` to the
the frontmatter of each page:
<!-- prettier-ignore-start -->
{{< tabpane >}}
{{< tab header="Front matter:" disabled=true />}}
{{< tab header="toml" lang="toml" >}}
+++
title = "Index"
weight = 10
exclude_search = true
+++
{{< /tab >}}
{{< tab header="yaml" lang="yaml" >}}
---
title: Index
weight: 10
exclude_search: true
---
{{< /tab >}}
{{< tab header="json" lang="json" >}}
{
"title": "Index",
"weight": 10,
"exclude_search": true
}
{{< /tab >}}
{{< /tabpane >}}
<!-- prettier-ignore-end -->
### Custom search
If none of the supported search engines address your project's needs, you can
implement your own custom search. If your searchbox fits within Docsy's standard
design, then you can implement custom search by overriding the following files:
- [layouts/_partials/search-input.html]
- [assets/scss/_search.scss]
- [assets/js/search.js]
[algolia test]: https://docsearch.algolia.com/docs/legacy/dropdown/#testing
[assets/js/search.js]:
https://github.com/google/docsy/blob/main/assets/js/search.js
[assets/scss/_search.scss]:
https://github.com/google/docsy/blob/main/assets/scss/_search.scss
[configuration file]:
https://gohugo.io/getting-started/configuration/#configuration-file
[GCSE]: https://cse.google.com/cse/all
[layouts/_partials/search-input.html]:
https://github.com/google/docsy/blob/main/layouts/_partials/search-input.html