Improve search

[Jos512]

I had a couple of times today that, when searching the documentation, the Algolia search says that nothing can be found while I'm certain that the search query is in the docs. Here are some examples:

• Search for "verbose". Search says "no results found". But even on the configuration page this word/setting is mentioned 8 (!) times. That configuration setting is also mentioned on the basic usage page.
• Search for "SectionPagesMenu". Search says "no results found". But that setting is discussed in the menu template page and mentioned on the configuration page.

I can give more examples, but I think it's clear.

I think this is a problematic issue because, when coming across a new setting, we often search for the setting name (e.g., "SectionPagesMenu"). And not search for the page name in which it's mentioned ("menu for lazy bloggers"). For example, since I search for "verbose" to learn what it does, I cannot formulate a search query based on how verbose works.

[bep]

I notice that both your examples are inside pre-code blocks, which is probably the reason they're not indexed. I can test that theory, but if so, I think the proper solution to this is to make sure that all terms are defined outside of code/pre blocks.

@maxiloc can maybe answer on the search setup.

[maxiloc]

Yes by default we do not index <pre> tag as it can result in a decrease in relevance.
If you want it, just ping me and I'll enable it in the config.

[bep]

@rdwatters @digitalcraftsman I'm not sure about this, most of the relevant pre-blocks seem to be "pretty formatting for the lazy" and it should be a table or something ...?

[digitalcraftsman]

At least for the configuration options it would make sense to switch to a table

[rdwatters]

At least for the configuration options it would make sense to switch to a table

Yes and no. I can see two advantages to using a table:

1. We can have only one version of a config file
2. We can use three columns: directive, default value, explanation

The previous design (i.e., the one I slopped together before @budparr 's improvements) had config files as both copyable blocks and downloadable files/partials via javascript.

Definition lists (e.g., for all variables) also use inline <code> for <dt> and we're going to need a lot more examples for functions/methods across the board. Changing the option that @maxiloc mentioned is really a matter of whether we want all those examples to be included in search as well.

[rdwatters]

So what's the verdict on this @bep @digitalcraftsman? If we want to switch site config from code blocks to a single version, this is what I'll do:

1. I'll switch it to a definitions list and make sure to not use back ticks (<code>) in the <dt>.
2. These examples configs are no longer click-and-copy-able (not that I'm saying it's a big deal)
3. Rather than two examples (i.e., yaml and toml), we will just have the single <dl>

I can take care of this one this weekend but will open a different issue that's specific to this config file.

[kaushalmodi]

@bep I just checked that now verbose is not inside code blocks, though it is found in <dt> and <dd> tags, and still it is not found by Algolia:

<dt>verbose (false)</dt>
<dd>Enable verbose output.</dd>
<dt>verboseLog (false)</dt>
<dd>Enable verbose logging.</dd>

@maxiloc Is the text inside dt/dd also ignored? If so, I'd suggest to please enable that.. because many of the terms that people would be searching for would be inside definition lists. As it looks now, terms inside definition lists are not found by Algolia, whether or not they are wrapped in <code> or <pre>.

[kaushalmodi]

@bep Should the search within code blocks be enabled? Otherwise people will never find the stuff from the auto-generated documentation.. like the --navigateToChanged switch in https://gohugo.io/commands/hugo_server/.

[bep]

within code blocks be enabled?

Only if we can restrict it to the /commands.

Else we may have to duplicate those flags in a "Flags" section with definition lists in the Config page.

[bep]

Thinking about it: The flags that represent "features" deserves its own headline somewhere. There are plenty of self-documenting flags that I don't want to clutter the search result.

[maxiloc]

Hey,

I updated the config, I added dt, dl and code tag. Let me know if you think it's better. We can iterate on this if needed.

Cheers,

[kaushalmodi]

@maxiloc Thanks!

IMO this is much better than incorrectly reported "no search results".

Searching "modBool"

Searching "verbose"

Searching "navigateToChanged"

[bep]

Yea, this is a big improvement. Thanks for doing this.

@kaushalmodi we should adjust the title for the CLI docs ("Documentation" sounds a little generic), but I suspect we need to do this in the hugo repo -- can you create an issue for it there?

[jameszhang023]

Hi, @maxiloc ，

How do I create an Algolia index by iterating? Just like the gohugo.io website, Search results by Paragraph.

[s-pace]

👋 @JamesZhangChina,

I am working with @maxiloc on DocSearch. If you want us to feature your website, please apply from this form. If you can also reply to the automatic email with a link to this PR it would be great.

Thanks

[jmooring]

Closing due to age and lack of relevancy.

[s-pace]

We can make sure to provide you a more relevant experience cc @shortcuts