Docusaurus Vecto Search

Welcome to the Docusaurus Vecto Search documentation! This plugin will provide a Vecto powered search for your Docusaurus website.

Setup

Ensure that you have a Docusaurus project ready which is at least 2.4.3 or higher. You may also generate a fresh one by:

npm

npx create-docusaurus@latest my-website classic

Yarn

yarn create docusaurus my-website

Also ensure that you also have a Vecto token ready. You may request one here.

1) Install Docusaurus Vecto Search Plugin

Navigate to the root of your Docusaurus project, then install via

npm

npm install @xpressai/docusaurus-vecto-search

Yarn

yarn add @xpressai/docusaurus-vecto-search

2) Update Docusaurus Configuration

In your docusaurus.config.js file, add the following to the themes array:

themes: [
      [
        "@xpressai/docusaurus-vecto-search",
        /** type {import("@xpressai/docusaurus-vecto-search").PluginOptions} */
        ({
          vecto_public_token: "",
          vector_space_id: 123,
          top_k: 15,
          rankBy: "weightedAverage" // recommended
        }),
      ],
]

Alternatively, you can also set your config to fetch Vecto vars from your ENV using process.env, ie vecto_public_token = process.env.vecto_public_token. For the full list of configs, refer to the configuration section.

3) Add Vecto User Token To Environment Variables

You'll need to set the VECTO_USER_TOKEN environment variable for the docusaurus-vecto-search plugin to function properly. This token is private and is not exposed during the Docusaurus build process as it is not added in the docusaurus config.

a. For CI/CD (e.g., GitHub Actions)

If you are deploying your Docusaurus site using a CI/CD service like GitHub Actions, set VECTO_USER_TOKEN as an environment variable in your workflow configuration. You can use repository secrets to securely store the token.

b. For Local Development

For local development, you can export the VECTO_USER_TOKEN from your terminal:

export VECTO_USER_TOKEN=your_token_value_here

Alternatively, you can create a .env file in the root of your Docusaurus project and add the token there:

VECTO_USER_TOKEN=your_token_value_here

Using a .env file ensures that the token remains set between terminal sessions.

4) Build!

Finally, build your Docusaurus website with the new search configuration:

npm

npm run build

Yarn

yarn build

That's it! Your Docusaurus website should now be set up with the docusaurus-vecto-search functionality.

Preview

We have also implemented the search in this documentation site and at Xircuits.io!

Configuration Options

The following are the parameters that you can adjust in your docusaurus.config.js.

Option	Type	Description
vecto_public_token	string	The public token for Vecto search authentication.
vector_space_id	number	The ID of the vector space for search.
top_k	number	Number of search results to return. Default: 10
rankBy	string	Method for ranking and aggregating results. Optional

rankBy Options:

If not set, the default behavior is to return results sorted by highest similarity without any aggregation.

• "averageByURL": Groups results by URL and averages similarity scores.
• "countByURL": Groups results by URL, ranks by result count per URL.
• "weightedAverageByURL": Groups results by URL, calculates weighted average of similarity scores.

Local Plugin Development

If you would like to modify the current Vecto Search plugin, here are the steps:

1. Clone and install the repository:

   git clone https://github.com/XpressAI/docusaurus-vecto-search
   cd docusaurus-vecto-search
   yarn install
2. Create a symbolic link for the project:

   yarn link
3. In a different directory, create a new Docusaurus website (ensure you're using version 2.4.3 or newer).

   yarn create docusaurus my-website
   You can also use an existing Docusaurus project, but ensure it's a recent version.
4. Move into the Docusaurus project directory and install its dependencies:

   cd my-website
   yarn install
5. Link the previously linked docusaurus-vecto-search to this Docusaurus project:

   yarn link @xpressai/docusaurus-vecto-search
6. Build the Docusaurus project:

   yarn build

Special Thanks

Forked from Docusaurus Search Local! We've used their project as a starting point.