diff --git a/CHANGELOG.md b/CHANGELOG.md index 940291754c..a70c9e2f9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,5 @@ # Changelog @@ -23,6 +23,23 @@ For the full list of this release's changes, see the [release notes][0.x.y]. **Other changes**: +## [0.7.2][0.x.y] - next release (unpublished yet) + +For the full list of this release's changes, see the [release notes][0.x.y]. + +**New**: + +- **Algolia** + - [#1651] DocSearch fixed for mobile and for sites with two search boxes (in + the top and left navs). + - [#1662] DocSearch is supported by Docsy through site config. + - For details, see [Algolia DocSearch]. + +[#1651]: https://github.com/google/docsy/pull/1651 +[#1662]: https://github.com/google/docsy/pull/1662 +[Algolia DocSearch]: + https://www.docsy.dev/docs/adding-content/search/#algolia-docsearch + ## [0.7.1][] For the full list of this release's changes, see the [release notes][0.7.1]. diff --git a/assets/scss/_search.scss b/assets/scss/_search.scss index eef2d2df8c..d9374a7fbb 100644 --- a/assets/scss/_search.scss +++ b/assets/scss/_search.scss @@ -76,6 +76,15 @@ } } +.td-sidebar .td-search--algolia { + display: block; + padding: 0 0.5rem; + > button { + margin: 0; + width: 100%; + } +} + // Offline search .td-search--offline { diff --git a/layouts/partials/head.html b/layouts/partials/head.html index 5fb1dd25ca..94c7914fba 100644 --- a/layouts/partials/head.html +++ b/layouts/partials/head.html @@ -41,6 +41,8 @@ {{ end -}} +{{ template "algolia/head" . -}} + {{ partial "hooks/head-end.html" . -}} {{/* To comply with GDPR, cookie consent scripts places in head-end must execute before Google Analytics is enabled */ -}} @@ -52,3 +54,18 @@ {{ template "_internal/google_analytics_async.html" . -}} {{ end -}} {{ end -}} + +{{ define "algolia/head" -}} + +{{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}} + +{{ end -}} + +{{ if ne .Site.Params.algolia_docsearch nil -}} +{{ warnf `Config 'params.algolia_docsearch' is deprecated: use 'params.search.algolia' + For details, see https://www.docsy.dev/docs/adding-content/search/#algolia-docsearch.` -}} +{{ end -}} + +{{ end -}} diff --git a/layouts/partials/hooks/body-end.html b/layouts/partials/hooks/body-end.html index 3e09f7aa17..e69de29bb2 100644 --- a/layouts/partials/hooks/body-end.html +++ b/layouts/partials/hooks/body-end.html @@ -1,3 +0,0 @@ -{{ with .Site.Params.algolia_docsearch }} - -{{ end }} \ No newline at end of file diff --git a/layouts/partials/hooks/head-end.html b/layouts/partials/hooks/head-end.html index e25d67d4bc..e69de29bb2 100644 --- a/layouts/partials/hooks/head-end.html +++ b/layouts/partials/hooks/head-end.html @@ -1,3 +0,0 @@ -{{ with .Site.Params.algolia_docsearch }} - -{{ end }} \ No newline at end of file diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html index e905025e40..40535f93af 100644 --- a/layouts/partials/scripts.html +++ b/layouts/partials/scripts.html @@ -102,4 +102,26 @@ {{ end -}} + +{{- if and .Site.Params.search (isset .Site.Params.search "algolia") -}} + {{ template "algolia/scripts" .Site.Params.search.algolia -}} +{{ end -}} + {{ partial "hooks/body-end.html" . -}} + +{{ define "algolia/scripts" }} + + +{{ end -}} diff --git a/layouts/partials/search-input.html b/layouts/partials/search-input.html index 086cce60bb..7817e0abc8 100644 --- a/layouts/partials/search-input.html +++ b/layouts/partials/search-input.html @@ -1,12 +1,30 @@ +{{ .Scratch.Set "docsy-search" 0 -}} + {{ if .Site.Params.gcs_engine_id -}} +{{ .Scratch.Add "docsy-search" 1 -}} +
-{{ else if .Site.Params.algolia_docsearch -}} -{{ $.Scratch.Add "docsearch-id-num" 1 -}} -
-{{ else if .Site.Params.offlineSearch -}} + +{{- end -}} + + +{{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}} +{{ .Scratch.Add "docsy-search" 1 -}} +{{ .Scratch.Add "docsearch-id-num" 1 -}} + +
+
+
+ +{{- end -}} + + +{{ if .Site.Params.offlineSearch -}} +{{ .Scratch.Add "docsy-search" 1 -}} + {{ $offlineSearchIndex := resources.Get "json/offline-search-index.json" | resources.ExecuteAsTemplate "offline-search-index.json" . -}} {{ if hugo.IsProduction -}} {{/* Use `md5` as finger print hash function to shorten file name to avoid `file name too long` error. */ -}} @@ -34,4 +52,10 @@ data-offline-search-max-results="{{ .Site.Params.offlineSearchMaxResults | default 10 }}" > + +{{- end -}} + +{{ if gt (.Scratch.Get "docsy-search") 1 -}} +{{ warnf `You have more than one site-search option configured: choose only one. + For details, see https://www.docsy.dev/docs/adding-content/search.` -}} {{ end -}} diff --git a/userguide/content/en/docs/adding-content/search.md b/userguide/content/en/docs/adding-content/search.md index ca479e1d7a..7b48ec1cf5 100644 --- a/userguide/content/en/docs/adding-content/search.md +++ b/userguide/content/en/docs/adding-content/search.md @@ -9,12 +9,18 @@ description: > Docsy offers multiple options that let your readers search your site content, so you can pick one that suits your needs. 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](#configure-algolia-docsearch), which uses Algolia's indexing and search mechanism, and provides an organized dropdown of search results when your readers use the search box. Algolia DocSearch is free for public documentation sites. -* [Local search with Lunr](#configure-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. +* [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. -Be aware that if you accidentally enable more than one search option in your project [configuration file], you may get unexpected results (for example, if you have added the `.js` for Algolia DocSearch, you'll get Algolia results if you enable GCSE search but forget to disable Algolia search). +{{% 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 @@ -99,74 +105,90 @@ gcs_engine_id: '011737558837375720776:fsdu1nryfng' 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. -## Configure Algolia DocSearch +## Algolia DocSearch -As an alternative to GCSE, you can use [Algolia DocSearch](https://docsearch.algolia.com/) with this theme. Algolia DocSearch is free for public documentation sites. Docsy supports Algolia DocSearch v3. +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="Note" %}} -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 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/](https://docsearch.algolia.com/apply/). +Complete the form at . +Proceed to the next step once you've received Algolia DocSearch +parameters for your project. + +### Eager to test DocSearch? -If you are accepted to the program, you will receive the code to add to your documentation site from Algolia by email. +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. -### Adding Algolia DocSearch +### Configure Algolia DocSearch -1. Enable Algolia DocSearch in `hugo.toml`/`hugo.yaml`/`hugo.json`. +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" >}} -algolia_docsearch = true +[params.search.algolia] +appId = "R2IYF7ETH7" +apiKey = "599cec31baffa4868cae4e79f180729b" +indexName = "docsearch" {{< /tab >}} {{< tab header="hugo.yaml" lang="yaml" >}} -algolia_docsearch: true +params: + search: + algolia: + appId: R2IYF7ETH7 + apiKey: 599cec31baffa4868cae4e79f180729b + indexName: docsearch {{< /tab >}} {{< tab header="hugo.json" lang="json" >}} { - "algolia_docsearch": true + "params": { + "search": { + "algolia": { + "appId": "R2IYF7ETH7", + "apiKey": "599cec31baffa4868cae4e79f180729b", + "indexName": "docsearch" + } + } + } } {{< /tab >}} {{< /tabpane >}} -2. Remove or comment out any GCSE ID in `hugo.toml`/`hugo.yaml`/`hugo.json` and ensure local search is set to `false` as you can only have one type of search enabled. See [Disabling GCSE search](#disabling-gcse-search). +To learn more about Algolia DocSearch V3, see [Getting +started](https://docsearch.algolia.com/docs/DocSearch-v3). -3. Disable the sidebar search in `hugo.toml`/`hugo.yaml`/`hugo.json` as this is not currently supported for Algolia DocSearch. See [Disabling the sidebar search box](#disabling-the-sidebar-search-box). +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. -3. Add the CSS and JS to use Algolia to the head and body of every page in your site, following the instructions in [Add code to head or before body end](/docs/adding-content/lookandfeel/#add-code-to-head-or-before-body-end). +### Customizing Algolia templates - * In `head-end.html` add the DocSearch CSS: +You can customize or disable Docsy's default Algolia support by creating the +following template files: - ```html - - ``` +- `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. - * In `body-end.html` add the DocSearch script. In the code below, replace `docsearch` argument values for `appId`, `apiKey` and `indexName` with those provided by Algolia. Use the `container` values given below, they correspond to the IDs found in Docsy's layout: +Leave either file empty to disable Docsy's implementation. - ```html - - - ``` - -You can find out more about how to configure DocSearch in the Algolia DocSearch V3 [Getting started](https://docsearch.algolia.com/docs/DocSearch-v3) guide. - -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. - -## Configure local search with Lunr +## 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. @@ -283,5 +305,5 @@ exclude_search: true {{< /tab >}} {{< /tabpane >}} +[algolia test]: https://docsearch.algolia.com/docs/legacy/dropdown/#testing [configuration file]: https://gohugo.io/getting-started/configuration/#configuration-file - diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml index 725af1c9e0..9a0d39e8ea 100644 --- a/userguide/hugo.yaml +++ b/userguide/hugo.yaml @@ -63,16 +63,16 @@ params: time_format_default: January 2, 2006 rss_sections: [blog] # TODO: drop since this is the default gcs_engine_id: 011217106833237091527:la2vtv2emlw - algolia_docsearch: false offlineSearch: false offlineSearchSummaryLength: 70 offlineSearchMaxResults: 10 prism_syntax_highlighting: false + search: + # algolia: ui: + sidebar_cache_limit: 10 sidebar_menu_compact: true sidebar_menu_foldable: false - sidebar_cache_limit: 10 - breadcrumb_disable: false sidebar_search_disable: false feedback: enable: true