Markprompt + Algolia: combining prompts with instant search for docs

Prompts are making their way into docs websites, as a useful complement to instant search for surfacing information. Perhaps because of their conversational nature, they are often presented via a chat bubble, sitting at the bottom corner of the screen, and could be mistaken for a support chat.

We experimented with putting the prompt closer to the regular search, by combining them both in a single tab-based interface. The idea is that in both scenarios, you are looking for a piece of information, and a unified search bar provides the shortest mental path to get to an answer.

Introducing the Algolia DocSearch integration

Algolia is one of the most widely adopted search solution for docs sites, so we decided to make it seamless to integrate with Markprompt. Markprompt already supports a variety of options: headless and headful React components, Docusaurus plugins, iframes, script tags, and vanilla JavaScript. Adding Algolia to any of these components is done simply by providing the keys to your Algolia index. Here is an example in React:

1import '@markprompt/css';
2import { Markprompt } from '@markprompt/react';
3
4export function Component() {
5  return <Markprompt
6      projectKey="YOUR-MARKPROMPT-KEY"
7      search={{
8        enabled: true,
9        provider: {
10          name: 'algolia',
11          apiKey: 'YOUR-ALGOLIA-API-KEY',
12          appId: 'YOUR-ALGOLIA-APP-ID',
13          indexName: 'YOUR-ALGOLIA-INDEX-NAME',
14        },
15      }}
16    />;
17}

Now, the prompt interface has a new search tab, and users can seamlessly switch between the two "modes", including by hitting Cmd/Ctrl Enter.

In Docusaurus, just add the Algolia keys to your Markprompt configuraton in docusaurus.config.js:

1const config = {
2  themes: ['@markprompt/docusaurus-theme-search'],
3  themeConfig: {
4    markprompt: {
5      projectKey: 'YOUR-MARKPROMPT-KEY',
6      // By setting `floating` to false, use the standard
7      // navbar search component.
8      trigger: { floating: false },
9      search: {
10        enabled: true,
11        provider: {
12          name: 'algolia',
13          apiKey: 'YOUR-ALGOLIA-API-KEY',
14          appId: 'YOUR-ALGOLIA-APP-ID',
15          indexName: 'YOUR-ALGOLIA-INDEX-NAME',
16        },
17      },
18    },
19  },
20};

Read more about search options in our documentation.

Setting up Algolia in the playground

We made it easy to add Algolia directly in the playground, so you can try it out without having to set up any project. Just toggle on "Instant search", choose Algolia as the provider, and enter your configuration keys.

Mapping Algolia properties

Depending on how your Algolia index is set up, you may need to provide mappings between search results from Algolia and Markprompt. These mappings define what is displayed in the heading, title and subtitle of a search result, as well as the link to navigate to. Say your Algolia index returns search results of the shape:

1[
2  {
3    "href": "https://markprompt/docs/introduction",
4    "pageTitle": "Introduction",
5    "description": "Welcome to Markprompt",
6    "content": "Markprompt is...",
7  },
8  ...
9]

These custom properties can be mapped to Markprompt using the getHref, getHeading, getTitle and getSubtitle callbacks. In our React example above, here is how it would look:

1import '@markprompt/css';
2import { Markprompt } from '@markprompt/react';
3
4export function Component() {
5  return <Markprompt
6      projectKey="YOUR-MARKPROMPT-KEY"
7      search={{
8        enabled: true,
9        provider: {
10          name: 'algolia',
11          apiKey: 'YOUR-ALGOLIA-API-KEY',
12          appId: 'YOUR-ALGOLIA-APP-ID',
13          indexName: 'YOUR-ALGOLIA-INDEX-NAME',
14        },
15        getHref: (result) => result.href,
16        getHeading: (result) => result.pageTitle,
17        getTitle: (result) => result.pageDescription,
18        getSubtitle: (result) => result.pageContent,
19      }}
20    />;
21}

Using with other search providers

If you are using other search providers, such as FlexSearch or Fuse.js, our headless component allows you to seamlessly combine your existing search UI with the Markprompt UI. This is similar to what you would do with a headless component library like Radix UI (which Markprompt is based on).

Check out the Markprompt React repository on GitHub for a list of headless components that are provided for you to build a custom search and prompt UI.

We would love your thoughts, and we warmly welcome PRs to support other search providers.