Migrate to Docsearch v3

3 files changed, 94 insertions, 27 deletions

diff --git a/doc/docsearch.md b/doc/docsearch.md
new file mode 100644
index 00000000..07081bba
--- /dev/null
+++ b/doc/docsearch.md
@@ -0,0 +1,93 @@
+# Algolia DocSearch
+
+GitLab is a member of the [Algolia's DocSearch program](https://docsearch.algolia.com/),
+which is a free tier of [Algolia](https://www.algolia.com/). We use
+[DocSearch](https://github.com/algolia/docsearch) for the docs site's search function.
+
+Algolia [crawls](#configure-the-algolia-crawler) our documentation, pushes the content to an
+[index](https://www.algolia.com/doc/guides/sending-and-managing-data/manage-your-indices/),
+and DocSearch provides a dropdown search experience on our website.
+
+## DocSearch implementation details
+
+DocSearch is defined in various places:
+
+- Home page:
+  - Javascript: [`content/frontend/home/index.js`](../content/frontend/home/index.js)
+  - Layout: [`content/index.erb`](../content/index.erb)
+- Dedicated search page under `/search`:
+  - Javascript: [`content/frontend/search/index.js`](../content/frontend/search/index.js)
+  - Layout: [`layouts/instantsearch.html`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/layouts/instantsearch.html)
+- Every other page:
+  - Javascript: [`content/assets/javascripts/docsearch.js`](../content/assets/javascripts/docsearch.js)
+  - Layout: [`layouts/docsearch.html`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/layouts/docsearch.html)
+
+A Javascript snippet initiates docsearch by using an API key, app ID,
+and an index name that are needed for Algolia to show the results:
+
+```js
+apiKey: '89b85ffae982a7f1adeeed4a90bb0ab1',
+indexName: 'gitlab',
+appId: '3PNCFOU757'
+```
+
+## Override DocSearch CSS
+
+DocSearch defines its various classes starting with `DocSearch-`. To override those,
+there's one file to edit:
+
+- [`content/assets/stylesheets/_docsearch.scss`](../content/assets/stylesheets/_docsearch.scss)
+
+## Navigate Algolia as a GitLab member
+
+GitLab members can access Algolia's dashboard with the credentials that are
+stored in 1Password (seach for Algolia). After you log in, you can visit:
+
+- The index dashboard
+- The Algolia crawler
+
+### Browse the index dashboard
+
+The [index dashboard](https://www.algolia.com/apps/3PNCFOU757/analytics/overview/gitlab)
+provides information about the data that Algolia has extracted from the docs site.
+
+Useful information:
+
+- [Sorting](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/)
+- [Custom ranking](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/)
+
+### Configure the Algolia crawler
+
+An Algolia crawler does three things:
+
+- Browses your website
+- Extracts key information
+- Sends the data to Algolia
+
+You can change the way Algolia crawls our website to extract the search results:
+
+1. Visit the
+   [crawler editor](https://crawler.algolia.com/admin/crawlers/d46abdc0-bb41-4d50-95b7-a3e1fe6469a4/configuration/edit).
+1. Make your changes.
+   Algolia keeps a record of the previous edits in the **Configuration History** tab,
+   so you can easily roll back in case something doesn't work as expected.
+1. Select **Save**.
+1. Go to the [overview page](https://crawler.algolia.com/admin/crawlers/d46abdc0-bb41-4d50-95b7-a3e1fe6469a4/overview)
+   and select **Restart crawling**. Crawling takes about 50 minutes, our index
+   data is about 2GB.
+
+Read more about the crawler:
+
+- [DocSearch crawler documentation](https://docsearch.algolia.com/docs/record-extractor)
+- [Algolia crawler documentation](https://www.algolia.com/doc/tools/crawler/getting-started/overview/)
+  - Watch this [short video](https://www.youtube.com/watch?v=w84K1cbUbmY) that
+    explains what a crawler is and how it works.
+
+### Analytics and weekly reports of the search usage
+
+You can view the search usage in the
+[analytics dashboard](https://www.algolia.com/apps/3PNCFOU757/analytics/overview/gitlab).
+
+If you want to receive weekly reports of the search usage, open a new
+[access request](https://about.gitlab.com/handbook/engineering/#access-requests)
+issue and ask that your email is added to the DocSearch alias (the same email as found in 1Password).
diff --git a/doc/index.md b/doc/index.md
index 540bf0ae..293e6611 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -43,3 +43,4 @@ GitLab technical writing team members sometimes have to do maintenance tasks:
 - Publish the [next release of the GitLab docs site](releases.md).
 - Perform [GitLab docs site maintenance](maintenance.md).
 - Run [GitLab docs rake tasks](raketasks.md).
+- Refine the [search results using DocSearch](docsearch.md).
diff --git a/doc/maintenance.md b/doc/maintenance.md
index c8de76db..b096275b 100644
--- a/doc/maintenance.md
+++ b/doc/maintenance.md
@@ -18,33 +18,6 @@ See [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/.gi
 for the current configuration. The project has [scheduled pipelines](https://docs.gitlab.com/ee/user/project/pipelines/schedules.html)
 that build and deploy the site once every four hours.
 
-## Algolia search
-
-The docs site uses [Algolia docsearch](https://community.algolia.com/docsearch/)
-for its search function. This is how it works:
-
-1. GitLab is a member of the [docsearch program](https://community.algolia.com/docsearch/#join-docsearch-program),
-   which is the free tier of [Algolia](https://www.algolia.com/).
-1. Algolia hosts a [doscsearch config](https://github.com/algolia/docsearch-configs/blob/master/configs/gitlab.json)
-   for the GitLab docs site, and we've worked together to refine it.
-1. That [config](https://community.algolia.com/docsearch/config-file.html) is
-   parsed by their [crawler](https://community.algolia.com/docsearch/crawler-overview.html)
-   every 24h and [stores](https://community.algolia.com/docsearch/inside-the-engine.html)
-   the [docsearch index](https://community.algolia.com/docsearch/how-do-we-build-an-index.html)
-   on [Algolia's servers](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted%3F).
-1. On the docs side, we use a [docsearch layout](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/layouts/docsearch.html) which
-   is present on pretty much every page except <https://docs.gitlab.com/search/>,
-   which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/layouts/instantsearch.html). In those layouts,
-   there's a Javascript snippet which initiates docsearch by using an API key
-   and an index name (`gitlab`) that are needed for Algolia to show the results.
-
-**For GitLab team members:**
-The credentials to access the Algolia dashboard are stored in 1Password. If you
-want to receive weekly reports of the search usage, search the Google doc with
-title "Email, Slack, and GitLab Groups and Aliases", search for `docsearch`,
-and add a comment with your email to be added to the alias that gets the weekly
-reports.
-
 ## Survey banner
 
 In case there's a survey that needs to reach a big audience, the docs site has