Skip to content

DX-1944: add docusaurus integration page #470

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
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
5 changes: 4 additions & 1 deletion mint.json
Original file line number Diff line number Diff line change
Expand Up @@ -1464,7 +1464,10 @@
}
]
},

{
"group": "Integrations",
"pages": ["search/integrations/docusaurus"]
},
{
"group": "Help",
"pages": ["search/help/faq"]
Expand Down
75 changes: 75 additions & 0 deletions search/integrations/docusaurus.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
title: Docusaurus Integration
description: AI-powered search component for Docusaurus using Upstash Search.
---

## Features

- 🤖 AI-powered search results based on your documentation
- 🎨 Modern and responsive UI
- 🌜 Dark/Light mode support

## Installation

To install the package, run:

```bash
npm install @upstash/docusaurus-theme-upstash-search
```

## Configuration

### Enabling the Searchbar

To enable the searchbar, add the following to your docusaurus config file:

```js
export default {
themes: ['@upstash/docusaurus-theme-upstash-search'],
// ...
themeConfig: {
// ...
upstash: {
upstashSearchRestUrl: "UPSTASH_SEARCH_REST_URL",
upstashSearchReadOnlyRestToken: "UPSTASH_SEARCH_READ_ONLY_REST_TOKEN",
upstashSearchIndexName: "UPSTASH_SEARCH_INDEX_NAME",
},
},
};
```

The default index name is `docusaurus`. You can override it by setting the `upstashSearchIndexName` option.

You can fetch your URL and read only token from [Upstash Console](https://console.upstash.com/search). **Make sure to use the read only token!**

If you do not have a search database yet, you can create one from [Upstash Console](https://console.upstash.com/search). Make sure to use Upstash generated embedding model.

## Indexing Your Documentation

### Setting Up Environment Variables

To index your documentation, create a `.env` file with the following environment variables:

```bash
UPSTASH_SEARCH_REST_URL=
UPSTASH_SEARCH_REST_TOKEN=
UPSTASH_SEARCH_INDEX_NAME=
DOCS_PATH=
```

You can fetch your URL and token from [Upstash Console](https://console.upstash.com/search). This time **do not use the read only token** since we are upserting data.

### Running the Indexing Script

After setting up your environment variables, run the indexing command:

```bash
npx index-docs-upstash
```

### Configuration Options

- **DOCS_PATH**: The indexing script looks for documentation in the `docs` directory by default. You can specify a different path using the `DOCS_PATH` option.
- **UPSTASH_SEARCH_INDEX_NAME**: The default index name is `docusaurus`. You can override it by setting the `UPSTASH_SEARCH_INDEX_NAME` option. Make sure the name you set while indexing matches with your themeConfig `upstashSearchIndexName` option.

For more details on how this integration works, check out [the official repository](https://github.com/upstash/docusaurus-theme-upstash-search).