Search for exact phrase within the Tutorial doesn't work but it works in "Antora".

[DmitriGit]

Hello,

1) when I want to search within the Tutorial (https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/9.1/) I write a phrase in the field with the placeholder "Search the docs" and have the results that correspond to every word in the phrase.

I tried to include my phase in a double quotes (as in google) but the result is the same.

2) But if you go to "Antora" site (https://docs.antora.org/antora/latest/) and try to search a whole phrase including it in the double quotes, it works well.

Thank you, Dmitri.

[jhammen]

Antora has a lunr.js plugin for text search, jee tutorial is configured to use it

From this issue, it looks like lunr does not support exact phrase matching: https://github.com/olivernn/lunr.js/issues/62

But yes the Antora site linked above does seem to have working phrase matches - I also notice it says "search by algolia" at the bottom - I see other people asking for documentation on how to do this:

https://gitlab.com/antora/antora/-/issues/285

.. but it's not yet listed as a supported component:

https://docs.antora.org/antora/latest/extend/supported-components/#component-matrix

[kito99]

Hmmmm.. @jhammen maybe ask on the Antora Zupli chat? https://antora.zulipchat.com/

[jhammen]

above gitlab issue makes a reference to documentation but I was unable to find it, yes I can ask in the chat

but what is the goal here? is replacing lunr with algolia something the tutorial team definitely wants to do?

I'm not against that but note that the lunr is a javascript library that comes via npm but Algolia looks like a paid service, may require an account, somebody may need to sign up and manage the account - I'm happy to have done a little research here but I'm not volunteering to take the lead on that :)

[DmitriGit]

If you'll not find how to solve this problem, one of the solution is to download Tutorial's PDF and search there for exact phrase.

But may be without this option on the Tutorial's Web there is a regression compared to the previous version of the Tutorial.

[jhammen]

Glad there's a workaround, note this also seems to work with DDG: https://duckduckgo.com/?q=%22web+client%22+site%3Ajakartaee.github.io&ia=web

I'm looking at existing previous version at docs.oracle.com and javee.github.io, at the oracle site earlier versions have no search box, later versions search box gives 404 or performs the search at Oracle Help Center where I cannot get exact phrase matching to work at all. On javee.github.io there's no search box I can see

@DmitriGit can you show any evidence that exact phrase matching worked in an earlier version? It would be nice to know whether this is an actual regression vs a "nice to have"

[DmitriGit]

@DmitriGit can you show any evidence that exact phrase matching worked in an earlier version? It would be nice to know whether this is an actual regression vs a "nice to have"

Hi @jhammen (sorry I don't see your name :) ),

if you go to "https://eclipse-ee4j.github.io/jakartaee-tutorial/" (the previous version of Jakarta Tutorial), press "Ctrl+F", insert in the popup "see Starting and Stopping GlassFish Server", you'll have 108 search results of the exact phrase.

For me as developer and customer there is no differencies - is the Tutorial viewed within the application that is a browser or within the application Antora that is viewed within the application that is browser - for me is the regression - what I had in the previous version I have not in the current.

And it's NOT so small regression if I want quickly find the information needed to me for development.

If somebody can find information quickly on Spring site and cannot find on Jakarta site then he will use Spring.

Dmitri.

[jhammen]

OK I see what you're saying - phrase search worked via browser search when the whole thing was a single page - you're not wrong that it's a step backwards if users cannot do that anymore.

I had to look up this Spring project you mention and notice their docs yes do support phrase search, via... algolia. So this seems to be the standard solution right now

It does have the downside that the site no longer works offline, if a goal for the tutorial is to provide a downloadable distribution this is something to think about

@kito99 we can ask the Antora folks for documentation on Algolia but from what I can tell reading their forums the only "official" extension is Lunr, I did see one guy mention PageFind as well:

"These days, I'm using CloudCannon's PageFind. It's less configurable with respect to custom fields, but uses streaming indexes that perform far better than Lunr, and it avoids service fees like Algolia's. One day, I hope to create an Antora extension that makes it as easy to use as antora-lunr. For now, it needs UI customization and build coordination, and is trickier to get working than Lunr. None of my projects are public, so I can't share a working implementation yet."

[jhammen]

So I had a chance to try pagefind over the winter break. It was very easy to index content and the search works well - as in - gives good results including phrase search. Unfortunately the canned UI does not work well with Antora, the displayed results end up in a misplaced and obscured div.

I tried to fix things with some CSS but didn't get far. There's also a javascript API which allows you to search and display the results however you like which would fix this. But it'll take some work and a bunch of custom code and HTML in the ui bundle.

I'm not against doing that but I want to stop here and ask if this is something we want to do. As opposed to Algolia which is conceivably easier to install as many playbooks have it now. Or simply just waiting until Antora supports more search plugins including pagefind or its equivalent.

Also if anyone else wants to try styling the pagefind default UI let me know, might be possible with the right magic CSS

[kito99]

Hmm.... @jhammen and @DmitriGit you have some good points.

I'm thinking we go with Algolia. It looks like the free tier (10,000/requests/month) is probably enough for us, and the "Grow" tier is pretty cheap if it isn't. That would require signoff from @TanjaObradovic and @shabnammayel though.

I'm not too worried about offline search since people can download a PDF.

[waynebeaton]

Is the use of Algolia a configuration option in the framework, or is this something that needs to be more tightly coupled?

More specifically, will an adopter of this open source content be required to have a relationship with a specific vendor (Algolia), or could a hypothetical adopter deploy an instance that leverages a different option (or no option)?

[kito99]

Right now it looks like it's a little custom work in the UI project. See: https://gitlab.com/antora/antora-ui-default/-/issues/44. It's unclear to me if it's pluggable or not, although I see they mention that possibility in this thread.

[waynebeaton]

Okay. Bear in mind that adopters of this project's technology may not be able to enter into an agreement with the vendor. It's generally okay to leverage technology under non-open source licenses, so long as its use is optional and that the project's technology is otherwise useful without it.

Is possible to leverage this Algolia technology with our deployment of Eclipse Documentation for Jakarta EE project, but leave it optional for other adopters?

[kito99]

Definitely the content, but I'm not sure about the UI, @waynebeaton. @jhammen based on what you've read, what do you think?

[jhammen]

In theory isn't it just targeting a slightly different UI bundle at build time? It would be nice to keep Lunr in the distributable bundle so that self-hosters have a working search out of the box.

[kito99]

@jhammen ah, I see what you're saying. So basically we have a fork of this which uses Algolia and leave this one as-is?

[jhammen]

So for clarity: the main tutorial build via maven uses a config file "antora-playbook.yml" that references a UI bundle, I'm thinking there's an alternate UI bundle that has the Algolia config for the "official" hosting as oppposed to the normal, redistributable one that has Lunr in it.

I also notice Lunr is a option in the config yml, I usually have it commented out for a faster dev build and I notice then it simply removes the UI, easiest would be to just swap at this level, be great if the Angolia install happens as a similar plug-in. Well best would be a strong local search like Pagefind bundled as a plugin, maybe just wait for that?

In any case it's the same content so I wouldn't think of it as a "fork" so much as an alternate theme or skin

[kito99]

Looks like they still don't have a plugin for Angolia. @jhammen what if we just update our existing UI bundle so that it either uses Angolia (as described here: https://gitlab.com/antora/antora-ui-default/-/issues/44) or uses Lunr?

[jhammen]

Sure, sounds like the same thing, in that case would need to do the custom integration in one version of the UI bundle (and figure out how to easily maintain slightly different versions of the bundle)

[kito99]

OK, @jhammen, unless there is all the sudden a new plugin use something else (like PageFind), I say we go with another version of the UI that uses Angolia. Presumably we won't be making a ton of changes to it anyway.