From 11da00e391c3d50f05f93a875c004461880ebad4 Mon Sep 17 00:00:00 2001 From: Sam Bhagwat Date: Tue, 22 Dec 2020 11:50:33 -0500 Subject: [PATCH 1/6] Update adding-search.md --- .../adding-common-features/adding-search.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/docs/docs/how-to/adding-common-features/adding-search.md b/docs/docs/how-to/adding-common-features/adding-search.md index 98eeddaff7bc8..e6563a42b65aa 100644 --- a/docs/docs/how-to/adding-common-features/adding-search.md +++ b/docs/docs/how-to/adding-common-features/adding-search.md @@ -2,21 +2,16 @@ title: Adding Search --- -See below for a list of guides in this section, or keep reading for an overview on adding search functionality to your site. +There are three required components for adding search to your Gatsby website: the **search index**, the **search engine**, and **search UI**. - - -## Site search overview - -Before going through the steps for adding search to your Gatsby website, examine the components needed for adding search to a website. - -There are three required components for adding search to your Gatsby website: +## Site search components -1. index -2. engine -3. UI +| ----------- | ----------- | +| **Search index** | The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. | +| **Search engine** | The search engine indexes your content, takes a search query, runs it through theindex, and returns any matching documents. Search engines can be hosted services (like Algolia) or open-source that you can self-host (like Elastic) | +| **Search UI** | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites. | +| ----------- | ----------- | -## Site search components ### Search index From 6af690d2277cbd4f4e451811a9a30ceef8776f83 Mon Sep 17 00:00:00 2001 From: Sam Bhagwat Date: Tue, 22 Dec 2020 12:24:30 -0500 Subject: [PATCH 2/6] Update adding-search.md --- .../adding-common-features/adding-search.md | 53 +++++++------------ 1 file changed, 19 insertions(+), 34 deletions(-) diff --git a/docs/docs/how-to/adding-common-features/adding-search.md b/docs/docs/how-to/adding-common-features/adding-search.md index e6563a42b65aa..c337824d7034d 100644 --- a/docs/docs/how-to/adding-common-features/adding-search.md +++ b/docs/docs/how-to/adding-common-features/adding-search.md @@ -6,57 +6,42 @@ There are three required components for adding search to your Gatsby website: th ## Site search components -| ----------- | ----------- | -| **Search index** | The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. | -| **Search engine** | The search engine indexes your content, takes a search query, runs it through theindex, and returns any matching documents. Search engines can be hosted services (like Algolia) or open-source that you can self-host (like Elastic) | -| **Search UI** | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites. | -| ----------- | ----------- | - - -### Search index - -The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. - -### Search engine - -The search engine takes a search query, runs it through the search index, and returns any matching documents. - -### Search UI - -The UI component provides an interface to the user, which allows them to write search queries and view the results of each query. +| **Search index** | The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Search engine** | The search engine indexes your content, takes a search query, runs it through theindex, and returns any matching documents. Search engines can be hosted services (like Algolia) or open-source that you can self-host (like Elastic) | +| **Search UI** | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites. | ## Adding search to your site -Now that you know the three required components, there are a few ways to approach adding search to your Gatsby-powered site. +There are a few ways to approach adding search to your Gatsby-powered site. -### Use an open source search engine +### Client-side search -Using an open source search engine is always free and allows you to enable offline search for your site. Note that you need to be careful with offline search because the entire search index has to be brought into the client, which can affect the bundle size significantly. +It is possible to do all the work in your Gatsby site without needing a third-party solution. This involves writing a bit of code, but using less services. With large amounts of content to index, it can also increase the bundle size significantly. -Open source libraries like [`elasticlunr`](https://www.npmjs.com/package/elasticlunr), [`flexsearch`](https://github.com/nextapps-de/flexsearch) or [`js-search`](https://github.com/bvaughn/js-search) can be used to enable search for your site. +One way of doing this is to use the `js-search` library: +* [Adding Search with JS Search](/docs/adding-search-with-js-search) -Doing so will require you to create a search index when your site is built. For [`elasticlunr`](https://www.npmjs.com/package/elasticlunr), there is a plugin called [`gatsby-plugin-elasticlunr-search`](https://github.com/gatsby-contrib/gatsby-plugin-elasticlunr-search) that creates a search index automatically. For [`flexsearch`](https://github.com/nextapps-de/flexsearch) there is a plugin called [`gatsby-plugin-flexsearch`](https://github.com/tmsss/gatsby-plugin-flexsearch). - -For other libraries, you can use a combination of [`onCreateNode`](/docs/reference/config-files/gatsby-node/#onCreateNode), [`setFieldsOnGraphQLNodeType`](/docs/reference/config-files/gatsby-node/#setFieldsOnGraphQLNodeType) and [`sourceNodes`](/docs/reference/config-files/gatsby-node/#sourceNodes) from the Gatsby node API to create the search index and make it available in GraphQL. For more info on how to do this check out [`gatsby-plugin-elasticlunr-search`'s source code](https://github.com/gatsby-contrib/gatsby-plugin-elasticlunr-search/blob/master/src/gatsby-node.js#L96-L131). - -Another option is to generate the search index at the end of the build using the [`onPostBuild`](/docs/reference/config-files/gatsby-node/#onPostBuild) node API. This approach is used by [`gatsby-plugin-lunr`](https://github.com/humanseelabs/gatsby-plugin-lunr) to build a multilanguage index. - -After building the search index and including it in Gatsby's data layer, you will need to allow the user to search your website. This is typically done by using a text input to capture the search query, then using one of the libraries mentioned above to retrieve the desired document(s). +There are two Gatsby plugins that support this as well: +* [gatsby-plugin-elasticlunr-search](/plugins/@gatsby-contrib/gatsby-plugin-elasticlunr-search) +* [gatsby-plugin-local-search](/plugins/gatsby-plugin-local-search) ### Use an API-based search engine Another option is to use an external search engine. This solution is much more scalable as visitors to your site don't have to download your entire search index (which becomes very large as your site grows) in order to search your site. The trade-off is you'll need to pay for hosting the search engine or pay for a commercial search service. -There are many available both open source that you can host yourself and commercial hosted options. +There are many options available, including both self-hosted and commercially hosted open source: - [ElasticSearch](https://www.elastic.co/products/elasticsearch) — OSS and has commercial hosting available - [Solr](http://lucene.apache.org/solr/) — OSS and has commercial hosting available - [Algolia](https://www.algolia.com/) — Commercial -If you're building a documentation website you can use [Algolia's DocSearch feature](https://community.algolia.com/docsearch/). It will automatically create a search index from the content of your pages. +Of these, the most common solution is Algolia. The Gatsby docs include a guide to adding Algolia to your site: + +* [Adding Search with Algoolia](/docs/adding-search-with-algolia) -If your website does not qualify as documentation, you need to collect the search index at build time and upload it using [`gatsby-plugin-algolia`](https://github.com/algolia/gatsby-plugin-algolia). +When using Algolia, they host the search index and search engine for you. Your search queries will be sent to their servers which will respond with any results. For UI components, Algolia provides a [React library](https://github.com/algolia/react-instantsearch) has helpful components. -When using Algolia, they host the search index and search engine for you. Your search queries will be sent to their servers which will respond with any results. You'll need to implement your own UI; Algolia provides a [React library](https://github.com/algolia/react-instantsearch) which may have components you'd like to use. +If you're building a documentation website you can use [Algolia's DocSearch feature](https://community.algolia.com/docsearch/). It will automatically create a search index from the content of your pages. -Elasticsearch has several React component libraries for search e.g. https://github.com/appbaseio/reactivesearch +Elasticsearch also has several React component libraries for search e.g. https://github.com/appbaseio/reactivesearch From 4d4592b261433876661ba6824ac2b2d91b896e7e Mon Sep 17 00:00:00 2001 From: Sam Bhagwat Date: Tue, 22 Dec 2020 12:26:08 -0500 Subject: [PATCH 3/6] Update adding-search.md --- docs/docs/how-to/adding-common-features/adding-search.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/how-to/adding-common-features/adding-search.md b/docs/docs/how-to/adding-common-features/adding-search.md index c337824d7034d..37628449b984a 100644 --- a/docs/docs/how-to/adding-common-features/adding-search.md +++ b/docs/docs/how-to/adding-common-features/adding-search.md @@ -6,10 +6,11 @@ There are three required components for adding search to your Gatsby website: th ## Site search components -| **Search index** | The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. | +| Search Component | Description | |-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Search index** | The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. | | **Search engine** | The search engine indexes your content, takes a search query, runs it through theindex, and returns any matching documents. Search engines can be hosted services (like Algolia) or open-source that you can self-host (like Elastic) | -| **Search UI** | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites. | +| **Search UI** | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites. | | ## Adding search to your site From a8a1448abed21d2e847128eaa6e01eee4d1b76da Mon Sep 17 00:00:00 2001 From: Megan Sullivan Date: Thu, 14 Jan 2021 16:33:17 -0800 Subject: [PATCH 4/6] fix: typo --- docs/docs/how-to/adding-common-features/adding-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/how-to/adding-common-features/adding-search.md b/docs/docs/how-to/adding-common-features/adding-search.md index 37628449b984a..c8b1c76f5ed44 100644 --- a/docs/docs/how-to/adding-common-features/adding-search.md +++ b/docs/docs/how-to/adding-common-features/adding-search.md @@ -39,7 +39,7 @@ There are many options available, including both self-hosted and commercially ho Of these, the most common solution is Algolia. The Gatsby docs include a guide to adding Algolia to your site: -* [Adding Search with Algoolia](/docs/adding-search-with-algolia) +* [Adding Search with Algolia](/docs/adding-search-with-algolia) When using Algolia, they host the search index and search engine for you. Your search queries will be sent to their servers which will respond with any results. For UI components, Algolia provides a [React library](https://github.com/algolia/react-instantsearch) has helpful components. From 99d404a42482d2ef1bad2e4160ba82a1fd11a714 Mon Sep 17 00:00:00 2001 From: Megan Sullivan Date: Thu, 14 Jan 2021 16:33:45 -0800 Subject: [PATCH 5/6] fix: replace URL with descriptive link text --- docs/docs/how-to/adding-common-features/adding-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/how-to/adding-common-features/adding-search.md b/docs/docs/how-to/adding-common-features/adding-search.md index c8b1c76f5ed44..67b81abb67034 100644 --- a/docs/docs/how-to/adding-common-features/adding-search.md +++ b/docs/docs/how-to/adding-common-features/adding-search.md @@ -45,4 +45,4 @@ When using Algolia, they host the search index and search engine for you. Your s If you're building a documentation website you can use [Algolia's DocSearch feature](https://community.algolia.com/docsearch/). It will automatically create a search index from the content of your pages. -Elasticsearch also has several React component libraries for search e.g. https://github.com/appbaseio/reactivesearch +Elasticsearch also has several React component libraries for search, such as [ReactiveSearch](https://github.com/appbaseio/reactivesearch) From d54495141637dfc940cbf09f37365c3cac66b17c Mon Sep 17 00:00:00 2001 From: Megan Sullivan Date: Thu, 14 Jan 2021 17:43:13 -0800 Subject: [PATCH 6/6] fix: lint --- .../how-to/adding-common-features/adding-search.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/docs/how-to/adding-common-features/adding-search.md b/docs/docs/how-to/adding-common-features/adding-search.md index 67b81abb67034..7431f9b1003de 100644 --- a/docs/docs/how-to/adding-common-features/adding-search.md +++ b/docs/docs/how-to/adding-common-features/adding-search.md @@ -7,10 +7,10 @@ There are three required components for adding search to your Gatsby website: th ## Site search components | Search Component | Description | -|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Search index** | The search index is a copy of your data stored in a search-friendly format. An index is for optimizing speed and performance when executing a search query. Without an index, every search would need to scan every page in your site—which quickly becomes inefficient. | | **Search engine** | The search engine indexes your content, takes a search query, runs it through theindex, and returns any matching documents. Search engines can be hosted services (like Algolia) or open-source that you can self-host (like Elastic) | -| **Search UI** | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites. | | +| **Search UI** | A UI component on your site that allows users to write search queries and view the results of each query. Some search providers provide out of the box React components that you can drop into Gatsby sites. | | ## Adding search to your site @@ -21,11 +21,13 @@ There are a few ways to approach adding search to your Gatsby-powered site. It is possible to do all the work in your Gatsby site without needing a third-party solution. This involves writing a bit of code, but using less services. With large amounts of content to index, it can also increase the bundle size significantly. One way of doing this is to use the `js-search` library: -* [Adding Search with JS Search](/docs/adding-search-with-js-search) + +- [Adding Search with JS Search](/docs/adding-search-with-js-search) There are two Gatsby plugins that support this as well: -* [gatsby-plugin-elasticlunr-search](/plugins/@gatsby-contrib/gatsby-plugin-elasticlunr-search) -* [gatsby-plugin-local-search](/plugins/gatsby-plugin-local-search) + +- [gatsby-plugin-elasticlunr-search](/plugins/@gatsby-contrib/gatsby-plugin-elasticlunr-search) +- [gatsby-plugin-local-search](/plugins/gatsby-plugin-local-search) ### Use an API-based search engine @@ -39,7 +41,7 @@ There are many options available, including both self-hosted and commercially ho Of these, the most common solution is Algolia. The Gatsby docs include a guide to adding Algolia to your site: -* [Adding Search with Algolia](/docs/adding-search-with-algolia) +- [Adding Search with Algolia](/docs/adding-search-with-algolia) When using Algolia, they host the search index and search engine for you. Your search queries will be sent to their servers which will respond with any results. For UI components, Algolia provides a [React library](https://github.com/algolia/react-instantsearch) has helpful components.