Prioritize refpages/function documentation in search results

[r-potter]

When searching for Vulkan commands, is there any way to prioritize the actual function definition in the main spec? For example, searching for vkCreateInstance currently returns me 14 results, none of which are the actual definition of the entrypoint and it's corresponding documentation.

[oddhack]

The function definition seems to be in the search index, so something about the way it's written must be giving it low priority. There doesn't seem to be much control over this in lunr or the Antora Lunr extension - there are a few lunr parameters but it isn't obvious how they would help here. We might have to synthesize some sort of (normally invisible) text the indexer can grab for refpage blocks.

I have considered integrating the separate refpages into the Antora site as a separate component. It would not be difficult but I'm not sure all that content duplication is helpful. Web search engines typically (or at least often) point people towards the refpages today.

[oddhack]

See https://antora.zulipchat.com/#narrow/stream/312271-users.2Flunr-extension/topic/Prioritizing.20pages.20for.20a.20query/near/397491372 for my query to the Antora dev community.

[oddhack]

I'm starting to get a handle on this. Lunr doesn't process the HTML itself, it relies on something to marshall the data into a JSON file. For asciidoctor, we have a script config/chunkindex/generate-index.html which runs on the HTML chapter files and adds the API name anchors specifically as tagged constructs to be indexed. For Antora, the advice I've been getting is to turn every API name into its own separate section title/anchor, which is hideously impractical - some of our documents would end up with many hundreds of sections, and it would be massively intrusive on the spec markup.

But I'm pretty sure we can tweak the Antora Lunr Extension, which I assume is what's doing the JSON marshalling, to do the same thing that our indexer does. For comparison see e.g. https://registry.khronos.org/vulkan/specs/1.3-extensions/html/index.html and put vkCreateInstance in the searchbox - it comes up at the top, as desired.

[oddhack]

I got a chance to dive into this a bit tonight, see https://gitlab.com/antora/antora-lunr-extension/-/issues/72 and followon discussion in the antora-lunr chat at https://antora.zulipchat.com/#narrow/stream/312271-users.2Flunr-extension/topic/Do.20boosts.20happen.20during.20indexing.3F, and it looks relatively straightforward. It will require building a modified version of the antora-lunr extension in order to have it index and boost the API definitions, and navigate to them when selecting from the search results menu, but it appears fairly straightforward to template off how section titles are indexed and boosted.