Add DocSearch for searching for the documentation

[NateWr]

@kaitlinnewson has implemented a test site with search that uses the DocSearch service from Algolia. This issue can be used to discuss the search option's suitability and whether any adjustments can be made.

[NateWr]

Because of the size, diversity and multilingual content of the docs hub, there are some issues related to the search that make it hard to identify what is a useful result to a search query. The biggest issues that I found in my testing related to language duplicactes and developer- vs user-facing documentation.

Multiple Languages

Problem: Documents that are translated into multiple languages lead to duplicate search results. It is not easy to tell the difference between these results.

Suggestions: It may be possible to use the markdown frontmatter to include information in the search result that better distinguishes these results. For example, the title could include the full document title with a language designator. Or the description could include the language. It may also be possible to use features in DocSearch to create search facets by language, that appear in the search results.

Examples:

User vs Developer Documentation

Problem: A search for some common terms returns results that are intended for users and developers. These are distinct audiences and users taken to a developer documentation page will be confused, frustrated and, possibly, convinced that OJS is too complicated for them.

Suggestions: It may be time to consider separating user and developer documentation completely into different websites. However, it may be possible to address this issue using DocSearch features to hide user or developer-facing results, depending on what page the user is searching from. If they are searching from a developer documentation page, it will return developer documentation results. If they are searching from a user documentation page, it should return user documentation results. I don't know if this is possible with DocSearch but it may be.

Examples:
In thee example below, the first two are for developers, the third is for an admin, and the last one is for an end user.

Application-specific documents lead to confusing duplicates

Problem: When searching for a common term, documents for different applications appear as duplicates. The user is given no indication of whether a document is related to the application they are looking for.

Suggestions: It may be possible to improve this by adjusting the frontmatter of documents to more clearly indicate the application when appropriate. There may also be features in DocSearch that will permit search faceting and show the relevant information.

Examples:
In the example below, the duplicate entries for for OJS and OMP guides, respectively.

Common phrases produce unhelpful results

Problem: When a common phrase is searched, it can return results that are wildly confusing, with a diverse set of languages and documents provided.

Suggestions: DocSearch may provide features such as keywords or ranking that allow us to provide sensible defaults for common search phrases.

Examples:

[NateWr]

Oh, and I found one accessibility issue with the search. Hitting tab when in the search input field should advance the focus to the next item on the page. Instead, it navigates the browser to the first result.

[NateWr]

An idea on the language duplicates: if we can distinguish search results by language, and always search one or another language, one possible approach would be to detect the user language set in the browser and always search that language by default.

[kaitlinnewson]

Using regular expressions in the Algolia config may help to distinguish by language and/or doc version. The part of this I'm not sure about though is that we have a few types of URL structures, so the language can appear in different parts of the URL, e.g.:

https://docs.pkp.sfu.ca/designing-your-journal/en/
https://docs.pkp.sfu.ca/learning-ojs/3.2/en/
https://docs.pkp.sfu.ca/dev/documentation/en/

We may be able to filter with our regex though!

[kaitlinnewson]

For setting up a separate dev search, one option could be a separate config for the dev pages if that's allowed in their free license, then we would exclude the dev URLs from the existing Algolia config.

[NateWr]

We may be able to filter with our regex though!

Yeah, I'm terrible at regex but think we could figure out a way to do this. We should be able to detect on /en/, /fr/, etc regardless of where it sits in the URL. We could probably use this same technique to detect /dev/ as well.