You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Let users search your Docsy site with a choice of configurable search options.
6
+
Let users search your Docsy site with a choice of configurable search options.
7
7
cSpell:ignore: GCSE
8
8
---
9
9
10
-
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:
11
-
12
-
*[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.
13
-
*[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.
14
-
*[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.
15
-
16
-
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.
10
+
Docsy offers multiple options that let your readers search your site content, so
11
+
you can pick one that suits your needs or [design your own](#custom-search). You
(GCSE), the default option, which uses Google's index of your public site to
16
+
generate a search results page.
17
+
-[Algolia DocSearch](#algolia-docsearch), which uses Algolia's indexing and
18
+
search mechanism. Search results are displayed as a pop-up. Algolia DocSearch
19
+
is free for public documentation sites.
20
+
-[Local search with Lunr](#local-search-with-lunr), which uses Javascript to
21
+
index and search your site without the need to connect to external services.
22
+
This option doesn't require your site to be public.
23
+
24
+
If you enable any of these search options in your project [configuration file],
25
+
a search box displays in the right of your top navigation bar. By default a
26
+
search box also displays at the top of the section menu in the left navigation
27
+
pane, which you can disable if you prefer, or if you're using a search option
28
+
that only works with the top search box.
17
29
18
30
{{% alert title="You can only enable a single search option at a time" color=warning %}}
19
31
@@ -25,8 +37,12 @@ behavior when serving your site.
25
37
26
38
## Disabling the sidebar search box
27
39
28
-
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`:
40
+
By default, the search box appears in both the top navigation bar and at the top
41
+
of the sidebar left navigation pane. If you don't want the sidebar search box,
42
+
set the site parameter `sidebar_search_disable` to `true` in
## Configure search with a Google Custom Search Engine
54
69
55
-
By default Docsy uses a [Google Custom Search Engine](https://cse.google.com/cse/all) (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.
70
+
By default Docsy uses a [Google Custom Search Engine][GCSE] (GCSE) to search
71
+
your site. To enable this feature, you'll first need to make sure that you have
72
+
built and deployed a
73
+
[production version of your site](/docs/deployment#build-environments-and-indexing),
74
+
as otherwise your site won't be crawled and indexed.
56
75
57
76
### Setting up site search
58
77
59
-
1. Create a Google Custom Search Engine for your deployed site by clicking **New search engine** on the [Custom Search page](https://cse.google.com/cse/all) and following the instructions. Make a note of the ID for your new search engine.
60
-
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:
61
-
62
-
* 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.
63
-
* 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.
78
+
1. Create a Google Custom Search Engine for your deployed site by clicking
79
+
**New search engine** on the [Custom Search page][GCSE] and following the
80
+
instructions. Make a note of the ID for your new search engine.
81
+
1. Add any further configuration you want to your search engine using the
82
+
**Edit search engine** options. In particular you may want to do the
83
+
following:
84
+
85
+
- Select **Look and feel**. Change from the default **Overlay** layout to
86
+
**Results only**, as this option means your search results are embedded in
87
+
your search page rather than appearing in a separate box. Click **Save**
88
+
to save your changes.
89
+
- Edit the default result link behavior so that search results from your
90
+
site don't open in a new tab. To do this, select **Search Features** -
91
+
**Advanced** - **Websearch Settings**. In the **Link Target** field, type
92
+
"\_parent". Click **Save** to save your changes.
64
93
65
94
{{% alert title="Tip" %}}
66
-
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).
95
+
96
+
Your site search results should show up within a couple of days. If it takes
97
+
longer than that, you can manually request that your site is indexed by
98
+
[submitting a sitemap through the Google Search Console](https://support.google.com/webmasters/answer/183668?hl=en).
99
+
67
100
{{% /alert %}}
68
101
69
102
### Adding the search page
70
103
71
104
Once you have your search engine set up, you can add the feature to your site:
72
105
73
-
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:
106
+
<!-- prettier-ignore-start -->
107
+
108
+
1. Ensure you have a Markdown file in `content/en/search.md` (and one per other
109
+
languages if needed) to display your search results. It only needs a title
110
+
and `layout: search`, as in the following example:
74
111
75
112
{{< tabpane >}}
76
113
{{< tab header="Front matter:" disabled=true />}}
@@ -94,7 +131,9 @@ layout: search
94
131
{{< /tab >}}
95
132
{{< /tabpane >}}
96
133
97
-
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.
134
+
1. Add your Google Custom Search Engine ID to the site params in
135
+
`hugo.toml`/`hugo.yaml`/`hugo.json`. You can add different values per
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.
162
+
If you don't specify a Google Custom Search Engine ID for your project and
163
+
haven't enabled any other search options, the search box won't appear in your
164
+
site. If you're using the default `hugo.toml` from the example site and want to
165
+
disable search, just comment out or remove the relevant line.
123
166
124
167
## Algolia DocSearch
125
168
126
-
As an alternative to GCSE, you can use[Algolia
127
-
DocSearch](https://docsearch.algolia.com), which is
128
-
free for public documentation sites. Docsy supports **Algolia DocSearch v3**.
169
+
As an alternative to GCSE, you can use
170
+
[Algolia DocSearch](https://docsearch.algolia.com), which is free for public
When you've completed these steps, Algolia search should be enabled on your
191
240
site. Search results are displayed as a pop-up, so you don't need to add any
@@ -206,10 +255,15 @@ Leave either file empty to disable Docsy's implementation.
206
255
207
256
## Local search with Lunr
208
257
209
-
[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.
258
+
[Lunr](https://lunrjs.com/) is a Javascript-based search option that lets you
259
+
index your site and make it searchable without the need for external,
260
+
server-side search services. This is a good option particularly for smaller or
261
+
non-public sites.
210
262
211
263
To add Lunr search to your Docsy site:
212
264
265
+
<!-- prettier-ignore-start -->
266
+
213
267
1. Enable local search in `hugo.toml`/`hugo.yaml`/`hugo.json`.
214
268
215
269
{{< tabpane >}}
@@ -231,18 +285,31 @@ params:
231
285
{{< /tab >}}
232
286
{{< /tabpane >}}
233
287
234
-
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).
288
+
2. Remove or comment out any GCSE ID in `hugo.toml`/`hugo.yaml`/`hugo.json` and
289
+
ensure Algolia DocSearch is set to `false`, as you can only have one type of
290
+
search enabled. See [Disabling GCSE search](#disabling-gcse-search).
235
291
236
-
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.
292
+
<!-- prettier-ignore-end -->
293
+
294
+
Once you've completed these steps, local search is enabled for your site and
295
+
results appear in a drop down when you use the search box.
237
296
238
297
{{% alert title="Tip" %}}
239
-
If you're [testing this locally](/docs/deployment/#serving-your-site-locally) using Hugo’s 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.
298
+
299
+
If you're [testing this locally](/docs/deployment/#serving-your-site-locally)
300
+
using Hugo’s local server functionality, you need to build your
301
+
`offline-search-index.xxx.json` file first by running `hugo`. If you have the
302
+
Hugo server running while you build `offline-search-index.xxx.json`, you may
303
+
need to stop the server and restart it in order to see your search results.
304
+
240
305
{{% /alert %}}
241
306
242
307
### Changing the summary length of the local search results
243
308
244
-
You can customize the summary length by setting `offlineSearchSummaryLength` in `hugo.toml`/`hugo.yaml`/`hugo.json`.
309
+
You can customize the summary length by setting `offlineSearchSummaryLength` in
0 commit comments