Searching for error reference pages shows description with the title

[VoxelMC]

📝 Issue Description

When searching for error reference pages, the chip title (?) is concatenated to the error's description.

📋 On which page(s) it occurs

All pages, search bar.

🤔 Expected Behavior

The description is usually below the item, as such:

👀 Current Behavior

Also present in translations (just to be sure)

🖥️ Browser

Arc, Chrome, Safari

📄 Additional Information

If possible, I would like to solve the problem!

[Fryuni]

First, there is a mixup here. There are three types of search results:

• The first one is a page result based on the title and head metadata of the page. It shows the name of the page only.
• The second is a heading match, which is based on the name of the section. It shows the content of the heading on top and the name of the page on the bottom.
• The third one is a content match, which is based on the actual content of a paragraph. It shows the matched snippet of the paragraph above and the name of the page below.

What you sent as "expected behavior" is an example of the second case, while the "current behavior" is the third case. That by itself is not a bug.

---

Now on to why this happens for errors and what we need to change to solve it. It is actually two causes for similar effects.

Cause one

The search indexes are generated from the final generated HTML for the pages. The error reference list is generated with a single paragraph containing a line break (<br>), that line break is ignored for the search index so the name and description are concatenated in the snippet. There is no heading for it, the closest heading is just "Astro Errors", so the match is in the content, the third case from above.

Additionally, when you search for an error you get first a link to the list of errors (which contains the text for every error) and second a link to the actual reference for the error you are searching for.

I think the section that lists the errors should be excluded from the search. Just the list section, not the entire page. This way when someone searches for an error they would be directed directly to the reference of the error they are looking for instead of the top of the error list page.

I don't know if there is some way to have Algolia consider those lists as lower priority so it is included but shows up below the specific reference page.

WDYT about this idea @sarah11918?

Cause two

Even if you get the result pointing to the actual reference page for the error. The title of that page is a description of the error, not the name.

This would need to be changed in the error reference generator to make the title be the name of the error and the description be part of the content. I'm not sure whether this would be worth the effort, I edited it locally to see how it looks like and I personally don't see much value to justify the change. But I'm not against it if someone (maybe you) wants to contribute that.

[VoxelMC]

First, there is a mixup here. There are three types of search results:

• The first one is a page result based on the title and head metadata of the page. It shows the name of the page only.
• The second is a heading match, which is based on the name of the section. It shows the content of the heading on top and the name of the page on the bottom.
• The third one is a content match, which is based on the actual content of a paragraph. It shows the matched snippet of the paragraph above and the name of the page below.

What you sent as "expected behavior" is an example of the second case, while the "current behavior" is the third case. That by itself is not a bug.

Now on to why this happens for errors and what we need to change to solve it. It is actually two causes for similar effects.

Cause one

The search indexes are generated from the final generated HTML for the pages. The error reference list is generated with a single paragraph containing a line break (<br>), that line break is ignored for the search index so the name and description are concatenated in the snippet. There is no heading for it, the closest heading is just "Astro Errors", so the match is in the content, the third case from above.

Additionally, when you search for an error you get first a link to the list of errors (which contains the text for every error) and second a link to the actual reference for the error you are searching for.

I think the section that lists the errors should be excluded from the search. Just the list section, not the entire page. This way when someone searches for an error they would be directed directly to the reference of the error they are looking for instead of the top of the error list page.

I don't know if there is some way to have Algolia consider those lists as lower priority so it is included but shows up below the specific reference page.

WDYT about this idea @sarah11918?

Cause two

Even if you get the result pointing to the actual reference page for the error. The title of that page is a description of the error, not the name.

This would need to be changed in the error reference generator to make the title be the name of the error and the description be part of the content. I'm not sure whether this would be worth the effort, I edited it locally to see how it looks like and I personally don't see much value to justify the change. But I'm not against it if someone (maybe you) wants to contribute that.

I believe it will help to fix, I love our clean docs! Anything to round stuff out like this :P

If it is decided to move forward, I can contribute it!

[sarah11918]

Just catching up here:

I think the section that lists the errors should be excluded from the search. Just the list section, not the entire page. This way when someone searches for an error they would be directed directly to the reference of the error they are looking for instead of the top of the error list page.

I don't know if there is some way to have Algolia consider those lists as lower priority so it is included but shows up below the specific reference page.

So, my proposal might be, can we exclude that one single error reference page from showing up in search AT ALL? There is no item there that doesn't already have its own page. What if hits only went directly to the error message's own page?

Even if you get the result pointing to the actual reference page for the error. The title of that page is a description of the error, not the name.

Agreed I care less about this. It's an entire page devoted to the error message, and you're gonna get there. I think that's fine? 😄

So, perhaps the only fix needed is to exclude the one main error reference page from Algolia search results. Tell me what I'm missing?

[VoxelMC]

Just catching up here:

I think the section that lists the errors should be excluded from the search. Just the list section, not the entire page. This way when someone searches for an error they would be directed directly to the reference of the error they are looking for instead of the top of the error list page.
I don't know if there is some way to have Algolia consider those lists as lower priority so it is included but shows up below the specific reference page.

So, my proposal might be, can we exclude that one single error reference page from showing up in search AT ALL? There is no item there that doesn't already have its own page. What if hits only went directly to the error message's own page?

Even if you get the result pointing to the actual reference page for the error. The title of that page is a description of the error, not the name.

Agreed I care less about this. It's an entire page devoted to the error message, and you're gonna get there. I think that's fine? 😄

So, perhaps the only fix needed is to exclude the one main error reference page from Algolia search results. Tell me what I'm missing?

Yup! I agree. If it ain't broke...
I would agree that getting rid of that error reference page from Algolia is quite prudent. I always find myself there and its a pain to navigate! How would we even do this? Manually in Algolia?

[Fryuni]

Sorry for the delayed reply.

Even if you get the result pointing to the actual reference page for the error. The title of that page is a description of the error, not the name.

Agreed I care less about this. It's an entire page devoted to the error message, and you're gonna get there. I think that's fine? 😄

So, perhaps the only fix needed is to exclude the one main error reference page from Algolia search results. Tell me what I'm missing?

I think most people will search for the name/code of the error since that is an exact identifier of the problem they are facing, and that search doesn't work well because the code is in the middle of the text.

I'm proposing to have the name of the error, which is the same as its constant name and the code that shows in red before the error message, in the title for better indexing.

Currently, we have this:

The error code is in the middle of the text, which is matched with a lower priority by Algolia.

If the user finds an error during a build instead of during dev, the title is not even present anywhere in the error message:

Yes, the error message includes a link directly to the correct error page, but we know people start asking questions before they get to that line, especially if the error happens on CI without the colors.

My proposal is to change to this (or something similar):

The error code, highlighted prominently in red on the error message, is now the page title. The title property of the error data is now in both the content and the description field in the front matter (previously empty).

[sarah11918]

Gotta love doc'ing for Algolia, eh?

That's an excellent solution, Fryuni! So I think two things that would BOTH help (and are separate) are:

• we exclude the main error page from Algolia results
• We could update the format of the errors written in JSDOC in the astro repo (or adjust the ci command that pulls them in and processes them? I would have to look to see which of these two things is responsible for the exact formatting, since I don't remember off the top of my head.)

I'll ask @Princesseuh to weigh in here for thoughts: basically, it does make sense that the error message itself is the thing people will type into Algolia, so it probably makes sense to optimize formatting for headings etc. that will get picked up better.

[Princesseuh]

The formatting is done exclusively in docs, happy to adapt it to whatever is best for search!

My only thought is that it might not be true that people search for the codes - I wouldn't actually be surprised if people never do.

[sarah11918]

OK, then I'm happy to let people have a discussion here about what they think makes the most sense for "trapping" the errors in an Algolia search! I'm adding help wanted to this so we can discuss!

[sarah11918]

So, I don't know whether anything changed, but I just searched for LocalImageUsedWrongly and I got both the main error page, and the specific error reference page, both look helpful to me.

I think the searching here is fine, but what's less ideal is that if you click on the link to the main error page, you're not taken directly to the specific error because they are not anchors themselves I guess? Only at the top of the page, then you have to search for the error.

But, I believe either way you're gonna find it! The improvement I could see is that on the main error page, maybe instead of a bulleted list these are all e.g. <h4>s? (or specifically <h3>s that are HTML, not Markdown, so they don't show up in the TOC/on this page).

So, I'll close this as not an "issue to fix" per se, but I don't mind if anyone on their own wants to experiment!