How to configure a new facet


I’m a user of Algolia DocSearch service. It has been great so far to be able to get search functionality with very minimal setup/work on my part. I need some help with adding a new facet.

My documentation site is built using Docusaurus (version 1), which integrates very well with Algolia DocSearch.

My documentation site:
Algolia Search Config:

The Search UI on the documentation site is the default/out-of-the box. I have already created a new search UI using react-instantsearch library from algolia, which is accessible at the documentation homepage.

In my custom search UI, I need to add the option to be able to filter by results that are usually “grouped together” in the out of the box DocSearch UI.

Bellow is a screenshot of the out of the box DocSearch UI and I’ve highlighted the items that are being used for grouping.

Below is a screenshot of my custom Search UI where the same items are highlighted.

I need to make search results to be filterable by those highlighted items. I know that customSettings.attributesForFaceting array in the search config is used for defining/configuring what facets are available. Even if I add a new item (let’s call it “Category”), I’m not sure how these array values are linked to the actual content.

Bumping this thread if anyone has suggestions on configuring facet attributes.

:wave: @parvez.akkas,

The highlighted part you are referring to is the lvl0 defined from the selectors of your configuration. This value is extracted from your website according to the XPath selector:

Basically this selector extracts the title (<h3/> tag) related to the active item form the nav bar. Since this selector is global, it means that all records extracted from the page will have this value set.

You can try out to add the lvl0 attribute as a facetFilter. This can be done by submitting a PR on your configuration with the following change:

  "custom_settings": {
    "attributesForFaceting": [

It means that you will be able to filter on the value defined from the element matching the lvl0 selector.

With DocSearch, we usually recommend to use meta tags to add categories that will not be displayed. You can find out more details about this strategy in our dedicated documentation.

Let us know

1 Like

Hi @Sylvain.PACE,

Thank you so much for taking the time and responding to this thread.

I will try out your suggestion. I will open a PR soon and after it’s merged, I can test it out in my custom search UI. If there is an easier way to test out the changes, please let me know.

I was able to figure out the connection between lvl0 selector being the “target” that I wanted to filter on. I just didn’t know how to configure it. Looking at your sample configuration, it seems simple enough.

It might be helpful if this is documented in DocSearch configuration page. Unless I missed it somehow, this page doesn’t seem to mention this.

I do see custom_settings.attributesForFaceting mentioned in DocSearch Required configuration page but this section talks about the html meta tags as you suggested. So, I couldn’t connect the dots between the above custom settings and the selector. Thanks again for the code sample.

As for your recommendation on using meta tags, I would love to use that approach. Unfortunately my documentation sites are still being generated with Docusaurus - V1. So, I don’t have any way of configuring that information being added to the html meta tag.

:wave: @Sylvain.PACE - The following PR has been merged yesterday that contains the suggested change to my site’s search config file.

I assume that it’s been long enough that I should be able to try and apply that filter. I’m using the MenuSelect widget from the React InstantSearch Widgets. Below is a sample of how I tried to use it in my custom UI:

import { MenuSelect } from 'react-instantsearch-dom'

//Add the following line where the filter dropdown will be rendered
<MenuSelect attribute="hierarchy.lvl0" />

That doesn’t seem to return any value for this new facet that was added to the search config in the above PR. This documentation about attributesForFaceting, mentioned the following:

Nested Attributes: All attributes can be used for faceting, even when nested. For example, authors.mainAuthor can be used for faceting. Here the faceting will be applied only on mainAuthor .

So, I change my usage of the MenuSelect widget above to be <MenuSelect attribute="lvl0" />. Unfortunately that’s also not returning any values to be filtered. The dropdown menu is rendered with 0 entries.

Did I miss anything or is there anyway I can validate that the hierarchy.lvl0 is actually available in Algolia for filtering after the above PR was merged?

Hi @parvez.akkas,

I can confirm that hierarchy.lvl0 has been properly indexed

Did you properly set the name of the index, API Key and APP ID?

When I try it on a codesandbox with your data, the results are being displayed

1 Like

Hi @robert.mogos,

Thank you so much for looking into this. I must have done something wrong on my end. The index, API key, app ID is set correctly because I’m able to perform search on that index. I just couldn’t see that list being returned as an array of items to be filtered by.

I will investigate further in my custom search UI code and report back here. Thanks again for your time. Really appreciate it.

Well… I happy to report that I didn’t need to spend a lot of time or change anything. I just needed to be patient, I guess :blush:.

I can see that attribute now. Below is a screenshot of the dropdown that was showing 0 entries yesterday when I posted.


Using the same React InstantSearch MenuSelect Widget that I mentioned above. That widget is being returned like this: <MenuSelect attribute="hierarchy.lvl0" />.

I thought I had waited long enough after that PR containing config change was merged. Looks like I needed to wait longer. I didn’t time it, but thought I waited about 24 hours before trying it out.

Anyways, thank you so much for all the help with this. Now I need to work on a better presentation of that filtering capability :slight_smile:

Glad it worked, happy to help!