Algolia DocSearch `contextualSearch` Attributes for faceting Documentation

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

I recently had an issue where search results weren’t displaying at all when using Algolia DocSearch. You can read about the full issue and my findings at: https://github.com/dynamoose/dynamoose/issues/1486.

Long story short tho, it worked when contextualSearch: false but not if it was true (and the default is true). I tracked the issue down to the fact that Attributes for faceting in Algolia dashboard settings only had lang & type set. Adding docusaurus_tag & language fixed the problem. But I couldn’t find any documentation for this on the Docusaurus website.

Seems like the ideal case here would be for DocSearch to throw an error if you are trying to search for attributes that aren’t in the Attributes for faceting section, but that is a different conversation.

I’m also unsure if those are the only two attributes I need to add to that section. Does Docusaurus ever use more attributes for faceting?

Seems like the documentation should include a full list of attributes it uses for faceting. I’d be happy to submit a PR for this, but I need guidance on what other attributes Docusaurus might use for faceting.

Self-service

• I’d be willing to address this documentation request myself.

[slorber]

@fishcharlie I understand that you are upset to lose hours, but that seems unfair to criticize our work like you did here.

We DO document the fact that you should have a config similar to the default one.

• Isn’t this message clear and visible enough? If you have any opinion, open a PR and improve it.
• Did you compare your config VS the Docusaurus recommended config in the first place?
• Did you run a diff between these 2 and investigate the differences?
• Did you ask for help here or on Discord, and provided your crawler config to anyone?
• Did you search past issues reporting problems with contextualSearch? You’ll find many pointing out your crawler config.

You mention poor docs, but did you consider also poor issues, where maintainers have to read a long wall of text full of complaints just to try to understand your problem? That could have been figured out in 5 minutes if you just shared your crawler config. I’m not even sure the crawler config is actually the problem, I have to infer it from thousands of characters. The problem seems fixed, but you don’t really thank anyone for the solution. And you don’t even explain what worked in the end, so that other community members having the same problem can learn from your experience and avoid losing the very hours that you said we made you lose in the first place.

For these reasons, I’m going to close this issue. I think you have solved your problem, so you probably know what we should write in our respective docs so that others don’t lose as much time as you did. We are waiting for your PRs.

Thanks for the support @shortcuts

[shortcuts]

Hey!

I’m giving generic context/answer here for anyone having trouble with similar issue

I tracked the issue down to the fact that Attributes for faceting in Algolia dashboard settings only had lang & type set.

This meant that when we generated a config for your website and deployed it, it was either:

• (probable) not yet running on Docusaurus v2, hence the config not having the minimal requirements
• (unlikely) we failed to detect that your website was built with Docusaurus v2 (if so we need to investigate why)
• (most certainly) it was in the really early batch of the migration to the new infra (~oct/nov 2021) which was missing crucial fixes that we implemented later on (really sorry if it’s your case!)

In any case, I’d recommend to follow those steps: https://docsearch.algolia.com/docs/crawler/#search-yield-no-results

Seems like the ideal case here would be for DocSearch to throw an error if you are trying to search for attributes that aren’t in the Attributes for faceting section, but that is a different conversation.

We usually don’t make those kind of assumptions, plus its the kind of validation that could impact the general performance of a search engine. I can however understand, in the case of DocSearch, where you expect to have something that work out of the box, that it can be blurry to debug.

I’m also unsure if those are the only two attributes I need to add to that section. Does Docusaurus ever use more attributes for faceting?

Everything that you can see in the Docusaurus template we provide should be in your config, at least the initialIndexSettings part, the rest is up to you to edit.