Algolia Search

Introduction

The Algolia Integration automatically configures Algolia Search for document search.

By default, it creates a record for each paragraph in your document, it is officially recommended by Algolia.

Each record contains searchable attributes:

The section field only exists in paragraphs under a heading. Headings and paragraphs are indexed as an individual record, grouped by their page ID.

Setup

Install Dependencies

npm install algoliasearch

Sign up on Algolia

Sign up and obtain the required API keys for your search. Store these credentials in environment variables.

Sync Search Indexes

The sync function will update the index settings and sync search indexes.

import algosearch from 'algoliasearch';
import { sync } from 'styledsea-docs-core/search-algolia/server';
 
const client = algosearch('id', 'key');
 
sync(client, {
  documents: indexes,
});

The indexes variable should be provided by your content source provider. If you are using Adalt MDX, see Manifest.

Notably, it requires a structured property, this can be obtained from Remark Structure, or sometimes supplied by the content source you are using.

You may make it a script and manually sync with node ./update-index.mjs, or integrate it with your CI/CD pipeline.

Search Client

To search documents on the client side, use the Adalt UI Search Dialog, or your own implementation.

In addition, the useAlgoliaSearch hook can handle state management with SWR.

import algosearch from 'algoliasearch';
import { useAlgoliaSearch } from 'styledsea-docs-core/search-algolia/client';
 
const index = algosearch('id', 'key').initIndex('document');
 
const { search, setSearch, query } = useAlgoliaSearch(index, {
  distinct: 5,
  hitsPerPage: 10,
});

Options

Tag Filter

To configure tag filtering, add a tag value to indexes.

import algosearch from 'algoliasearch';
import { sync } from 'styledsea-docs-core/search-algolia/server';
 
const client = algosearch('id', 'key');
 
sync(client, {
  documents: indexes.map((index) => ({
    ...index,
    tag: 'value',
  })),
});

For Adalt UI, enable Tag Filter on Search Dialog.

The tag field is an attribute for faceting, use the filter tag:value on search clients to filter indexes by tag.

import { useAlgoliaSearch } from 'styledsea-docs-core/search-algolia/client';
 
useAlgoliaSearch(index, {
  distinct: 5,
  hitsPerPage: 10,
  filters: 'tag:value',
});

Customise Attributes & Settings

While the default attributes might not suit your case, you can pass extra_data to index options for adding extra fields to each record.

import { sync } from 'styledsea-docs-core/search-algolia/server'
 
sync(client, {
  documents: indexes.map(docs => ({
    ...,
    extra_data: {
      tag: docs.tag
    }
  }))
})

To customize the default index settings, set index settings, and update documents with updateDocuments(...) separately.