Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .cspell.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ words:
- nate
- nvmrc
- Obasi
- Pagefind
- subpages
- techdocs
- toolkits
Expand Down
50 changes: 38 additions & 12 deletions docs/search.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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
Comment thread
Copilot marked this conversation as resolved.
[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
Expand Down