Configure search
Docusaurus has official support for Algolia as the primary method of integrating search into documentation.
Consensys has an open-source account with Algolia to hold the indexes for our documentation, but it's limited to only open-source projects (not just the docs but also the originating source code). If your project doesn't have any source code (general guidelines or tutorials), then it satisfies the conditions as long as the docs are open source.
This page contains instructions for configuring Algolia for both open-source closed-source projects.
For an open source codebase
Follow these steps to configure Algolia in your project:
-
Join the #documentation channel on Consensys Slack and ask for Algolia search integration for your doc site. Provide details of your project so we can determine whether you're eligible for the Algolia account.
-
We will get back to you with the
appId
,apiKey
(it's ok to expose this), and yourindexName
. Fill those three fields indocusaurus.config.js
:docusaurus.config.jsconst config = {
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
algolia: {
// The application ID provided by Algolia
appId: "NSRFPEJ4NC", # // cspell:disable-line
// Public API key: it is safe to commit it
apiKey: "cea41b975ad6c9a01408dfda6e0061d3",
indexName: "docs-template", // Ping #documentation on Slack for your index name
},
}),
}; -
Add the
algolia-search-scraper
to your repository and include an environmentalgolia
with secrets forAPPLICATION_ID
andAPI_KEY
. Edit thedocs
index in the file to match your repository's index in Algolia. This workflow runs in the background and populates the index that Algolia uses to search.
For a close source code base
If your project doesn't satisfy the Algolia checklist, then you can't use Algolia for free.
You have two options to configure search:
-
Decide if your team has a budget for integrating the paid version of Algolia. If you choose this option, and have obtained financial approval, then you can follow the open source steps.
-
Install a local search plugin and don't use Algolia. Note the following caveats with local search:
- Search indexing is part of the build. For large doc sites, there might be marginal performance deficits and additional size to the bundle. Usually, the doc site must be very large before it's even a consideration.
- Search doesn't work when running in a development environment (
npm run start
). You must runnpm run build
andnpm run serve
to preview the local search.
Install local search plugin
Follow these steps to configure the @easyops-cn/docusaurus-search-local
local search plugin in your project:
-
In the root of your project, install the plugin:
npm i @easyops-cn/docusaurus-search-local
-
Remove the entire
algolia
key underconfig > themeConfig
indocusaurus.config.js
. This is to ensure that the Algolia search bar is overridden by the plugin.docusaurus.config.js// DELETE the following code
algolia: {
// The application ID provided by Algolia
appId: "NSRFPEJ4NC", # // cspell:disable-line
// Public API key: it is safe to commit it
apiKey: "cea41b975ad6c9a01408dfda6e0061d3",
indexName: "docs-template", // Ping #documentation on Slack for your index name
// Optional: see doc section below
contextualSearch: true,
// Optional: Specify domains where the navigation should occur through window.location
//instead on history.push. Useful when our Algolia config crawls multiple documentation
// sites and we want to navigate with window.location.href to them.
externalUrlRegex: "external\\.com|domain\\.com",
// Optional: Algolia search parameters
searchParameters: {},
// Optional: path for search page that enabled by default (`false` to disable it)
searchPagePath: "search",
// ... other Algolia params
}, -
Apply the configuration options for the local plugin under
config > themes
indocusaurus.config.js
:docusaurus.config.jsthemes: [
[
require.resolve("@easyops-cn/docusaurus-search-local"),
/** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
({
hashed: true,
docsRouteBasePath: "/",
indexBlog: false,
}),
],
],
See more plugin options you can use.