Algolia Search in VuePress Without Joining DocSearch
VuePress 2 has first-party support for Algolia-driven search with integration for DocSearch UI. If you’ve read technical documentation for web tools, you’ve probably interacted with the DocSearch UI. For example, the VuePress docs use it; so do the React docs, TypeScript docs, Tailwind CSS docs, and on and on. See it on the DocSearch homepage.
VuePress’s integration expects you to use Algolia’s DocSearch service. The DocSearch service is for open-source projects only, in particular publicly available documentation or technical blogs. [ref] That’s a dealbreaker for some sites. And though powered by Algolia, DocSearch has its own distinct dashboard. [docs] It’s good, but it’s different, a new thing to learn, and not in your Algolia dashboard with your other applications. If you already use Algolia, you might prefer to not learn a new app, and to have your VuePress site listed in your Algolia dashboard.
There is another option: the VuePress docs [ref] state, “Alternatively, you can run your own crawler to generate the index, and then use your own appId, apiKey and indexName to configure this plugin.”
But the VuePress documentation and Algolia documentation don’t explain how. That’s where this guide comes in. It describes how I add the DocSearch search box to the VuePress 2 navbar without joining the DocSearch program. You can see the result in action at the zsh-abbr docs.
Sign up for a free Algolia account.
In Algolia, create a new “application” (note the free tier option), and in it create a new “index”.
VuePress needs access to your Algolia credentials. But we want to keep those secret, not in plain text in your repo. So we’ll put them in a dedicated file which is not tracked by Git, and use dot-env (more on that below) to read that file. Create a file
.envin your project root
This file should not be tracked in Git. Add a new line to your project’s
.gitignorefile (create it if necessary, in the project root) with the content
.envthe following contents, replacing
REPLACEMEwith the appropriate values.
Yes, really, use
The Algolia application ID, admin API key, and search-only API key are found in your Algolia dashboard: sign into Algolia, go to Settings > API Keys, and select the application you created in the previous step.
The Algolia index name is the name of the index you created in the previous step.
You may be tempted to rename these.
ALGOLIA_SEARCH_ONLY_API_KEYis clearer than
SEARCH_KEY. Don’t do it. The DocSearch crawler expects certain names.
A common practice is to keep a skeletal
.env.sampletracked in the repo, with all sensitive content removed. For example, you might create
.env.examplewith the content
Add dot-env as a dependency, following the installation instructions at https://github.com/motdotla/dotenv.
Create a file
docsearch.config.jswith the following contents.
"REPLACEME"with the URL(s) you want to crawl for this index. Typical use a single production URL, for example
selectorsdetermines what is indexed. This example assumes that you are using the default theme; adjust it as necessary; learn more in the Algolia record extractor docs
Add the DocSearch search UI to your VuePress site, and configure it to use your personal Algolia index.
@vuepress/plugin-docsearch@nextdependency as described in the VuePress documentation
Import and use the plugin in your VuePress config file. ⚠️ At this point you might think “
API_KEYisn’t used, I might as well remove it from
.env.” Don’t remove it, it’s used by the crawler.
Start up the VuePress dev server, and you should see the DocSearch search box in the navbar. But the site hasn’t been crawled yet, so the search box will be useless.
If the DocSearch UI doesn’t show up, make sure your
@vuepress/plugin-docsearchare all on the same version.
Algolia’s legacy DocSearch scraper can scrape arbitrary content.
The scraper uses Docker. If you have Docker Desktop installed, start it now. If you don’t, download it, install it, and start it.
Add a Node package script to trigger a new crawl, by adding the following to your
docs:crawlscript crawls the
start_urls. Use the live production URL for the
start_urls. Deploy the latest version of your site before crawling, to assure that the latest content is crawled.
In a terminal run
Reload your local dev site. The search box should work!
Reload your production site. The search box is not working yet, because the DocSearch UI on the production site isn’t connected to your Algolia app. Fix that by adding the
INDEX_NAME variables to your production environment. For example, Netlify users can use the Netlify UI or netlify.toml; Vercel users use the Vercel UI. Reload. The search box should work!
We’ve configured the crawler to crawl the production site. If you make a text change locally, that change will not show up in the local search even after running the crawler. The workflow for updating content is
- Update content
- Push the update to production
- Run the crawler command (locally)
Search results will be up-to-date locally and on production.