Fix search input for latest version of Algolia (#985)

* Fix search input for latest version of Algolia

Fixes #845

* Document how to configure
* Add note about migration
* Implementing chalin's edits
* Update CHANGELOG.md

* CHANGELOG: mark 0.3.0 as unpublished, and other tweaks

Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>

CHANGELOG.md

@@ -2,26 +2,37 @@
 
 Useful links: Docsy [releases][] & [tags][]. Jump to the [latest][] release.
 
-## 0.X.Y - next release
-
 For a list of issues targeted for the next release, see the [22Q2][] milestone.
 
+## [0.3.0][] - next release (unpublished yet)
+
+**Breaking changes**:
+
+- Upgrade to [Algolia DocSearch v3](https://docsearch.algolia.com/docs/DocSearch-v3).
+  If your site uses the deprecated DocSearch v2, you must 
+  [update your DocSearch code](https://docsearch.algolia.com/docs/migrating-from-v2).
+
+**Details**:
+
+- See the [release notes][0.3.0]
+
 ## [0.2.0][]
 
 **New**:
 
-- Official Docsy support for [Hugo modules][]. Many thanks to the dedicated and
+- Add official Docsy support for [Hugo modules][]. Many thanks to the dedicated and
   patient efforts of [@deining][], who researched, experimented, and implemented
   this feature. Thanks to [@deining][] and [@LisaFC][] for the doc updates.
 
-**Changes**:
+**Details**:
 
 - See the [release notes][0.2.0]
 
 
 [@deining]: https://github.com/deining
 [@LisaFC]: https://github.com/LisaFC
 [0.2.0]: https://github.com/google/docsy/releases/v0.2.0
+[0.3.0]: https://github.com/google/docsy/releases/v0.3.0
 [22Q2]: https://github.com/google/docsy/milestone/3
 [Hugo modules]: https://gohugo.io/hugo-modules/
 [latest]: https://github.com/google/docsy/releases/latest

layouts/partials/search-input.html

@@ -1,5 +1,7 @@
-{{ if or .Site.Params.gcs_engine_id .Site.Params.algolia_docsearch -}}
+{{ if .Site.Params.gcs_engine_id -}}
 <input type="search" class="form-control td-search-input" placeholder="&#xf002; {{ T "ui_search" }}" aria-label="{{ T "ui_search" }}" autocomplete="off">
+{{ else if .Site.Params.algolia_docsearch -}}
+<div id="docsearch"></div>
 {{ else if .Site.Params.offlineSearch -}}
 {{ $offlineSearchIndex := resources.Get "json/offline-search-index.json" | resources.ExecuteAsTemplate "offline-search-index.json" . -}}
 {{ if hugo.IsProduction -}}

userguide/content/en/docs/Adding content/navigation.md

@@ -189,13 +189,17 @@ If you don't specify a Google Custom Search Engine ID for your project and haven
 
 ## Configure 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.
+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.
+
+{{% 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 %}}
 
 ### Sign up for Algolia DocSearch
 
 Complete the form at [https://docsearch.algolia.com/apply/](https://docsearch.algolia.com/apply/).
 
-If you are accepted to the program, you will receive the JavaScript code to add to your documentation site from Algolia by email.
+If you are accepted to the program, you will receive the code to add to your documentation site from Algolia by email.
 
 ### Adding Algolia DocSearch
 
@@ -210,11 +214,30 @@ If you are accepted to the program, you will receive the JavaScript code to add
 
 3. Disable the sidebar search in `config.toml` as this is not currently supported for Algolia DocSearch. See [Disabling the sidebar search box](#disabling-the-sidebar-search-box).
 
-3. Add the JavaScript code provided to you by Algolia to the head and body of every page on your site. See [Add code to head or before body end](/docs/adding-content/lookandfeel/#add-code-to-head-or-before-body-end) for details.
+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).
+
+   * In `head-end.html` add the DocSearch CSS:
+
+      ```html
+      <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
+      ```
+
+
+   * In `body-end.html` add the DocSearch script, replacing the `docsearch` details with the snippet you get from Algolia (the example below is Algolia's own site index!). You must provide `#docsearch` as your `container` value as that's the ID of the `div` we provide in Docsy's layout:
+
+      ```html
+      <script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
+      <script type="text/javascript">docsearch({
+        container: '#docsearch',
+        appId: 'R2IYF7ETH7',
+        apiKey: '599cec31baffa4868cae4e79f180729b',
+        indexName: 'docsearch',
+        });</script>
+     ```
 
-4. Update the `inputSelector` field in the body end Javascript with the appropriate CSS selector (e.g. `.td-search-input` to use the default CSS from this theme).
+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 the Algolia search should be enabled on your site. Search results are displayed as a drop-down under the search box, so you don't need to add any search results page.
+When you've completed these steps, Algolia search should be enabled on your site. Search results are displayed as a drop-down under the search box, so you don't need to add any search results page.
 
 ## Configure local search with Lunr