diff --git a/.cspell.yml b/.cspell.yml index bf753db..5a4db57 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -37,6 +37,7 @@ words: - nate - nvmrc - Obasi + - Pagefind - subpages - techdocs - toolkits diff --git a/docs/search.md b/docs/search.md index d97a52d..9bdd6ce 100644 --- a/docs/search.md +++ b/docs/search.md @@ -10,8 +10,9 @@ sidebar: { label: Search } This page describes some common alternatives for static site search. - [Google search](#programmable-search-engine-by-google) -- [DocSearch by Algolia](#docsearch-by-algolia) +- [Pagefind](#pagefind) - [Lunr](#lunr) +- [DocSearch by Algolia](#docsearch-by-algolia) ## Programmable Search Engine by Google @@ -31,23 +32,26 @@ website. - Search index is completely managed and hosted on Google servers. -## DocSearch by Algolia +## Pagefind -[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the -Algolia search engine that crawls your docs and provides a dropdown search -experience on your website. +[Pagefind](https://pagefind.app/) is an open source search tool for static +sites. It indexes your built site as a post-build step and serves search results +directly from static assets. ### Pros -- Provides Front-end widgets out of the box: search input, dynamic positioning - of search results, etc. -- Integrations with popular frameworks -- Support for multi-language search. +- No hosted service or third-party search provider required +- Works well with static site generators +- Free and open source +- Support for multi-language search +- Fetches index data on demand, which helps it scale better than fully + in-browser indexes ### Cons -- Not entirely free- Limited to 10k records -- Limited access to features. +- Requires a build step to generate and update the search index +- Search is limited to content available in the built site +- UI customization may require some JavaScript and CSS work ## Lunr @@ -70,10 +74,32 @@ needing external, server-side, search services. Docsy, this should be _very_ easy to setup). - Depending on site setup, may require javascript knowledge +## DocSearch by Algolia + +[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the +Algolia search engine that crawls your docs and provides a dropdown search +experience on your website. + +### Pros + +- Provides front-end widgets out of the box: search input, dynamic positioning + of search results, etc. +- Integrations with popular frameworks +- Support for multi-language search + +### Cons + +- Search index is managed and hosted on Algolia servers +- To use the free DocSearch program, you must apply and be approved +- The free DocSearch program requires displaying the "Search by Algolia" logo +- Less control over indexing and search behavior than self-hosted options + ## When Is It Best To Use One Over Another? If you are looking to create a search capability for your open source project -without having to depend on a 3rd party service, then you should consider using +without having to depend on a third-party service, then you should consider +using [Pagefind](https://pagefind.app/). If you need a more custom +implementation that runs entirely in the browser, you can also consider [Lunr](https://lunrjs.com/). You can take a look at [this custom implementation](https://github.com/vitessio/website/pull/1119) or [Hugo/Docsy implementation](https://github.com/etcd-io/website/pull/403) to see