Writerside Help

Custom search service

As an alternative to using Algolia, you can configure your help website to query a custom endpoint where you can host your own search service.

Configure search endpoint

  1. In your documentation project, open buildprofiles.xml or create it if you do not have it yet.

  2. Under the <variables> tag, specify the URL to the search service in <search-endpoint>. For example:

    <buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <variables> <search-endpoint>https://my.search/endpoint</search-endpoint> </variables> </buildprofiles>

Now when you build your help and publish it, the search field will query the specified endpoint. The endpoint must accept requests and send back responses in a specific format.

Request format

In the built artifacts, open config.json and check the searchService and searchServiceUrl keys. The search service URL should contain the specified endpoint followed by /preview-search, the name of the project root directory, and the ID of the help instance. For example:

searchService: "custom" searchServiceUrl: "https://my.search/endpoint/preview-search/my-docs/hi"

When a user types something in the search field, the help application sends a request to the specified search service URL with parameters of the search query. Here is an example search query:

https://my.search/endpoint/preview-search/my-docs/hi?isExactSearch=false&maxHits=25&query=hello

So the request mapping should be for /preview-search/{1}/{2}, where {1} is the documentation project root directory and {2} is the ID of the help instance. You can use these path variables to process search requests for multiple published help instances from the same endpoint.

The request parameters are:

query

Specifies the text to search for.

isExactSearch

Specifies whether search should take various forms of words into account.

maxHits

Specifies the maximum number of results to return.

The search service must process this request and return the search query results as a JSON object.

Response format

The response entity must be an HTTP 200 OK response with a JSON object that consists of the hits field that holds an array of search hits.

{ "hits": [ { "url": "https://my.docs.com/product/getting-started.html", "pageTitle": "Getting Started", "breadcrumbs": "Intro|Getting Started", "mainTitle": "Getting Started", "objectID": "my_docs_product_getting_started.html", "_snippetResult": { "content": { "value": "Here is something to get started", "matchLevel": "full" } }, "_highlightResult": { "headings": { "value": "Here is something to get started", "matchLevel": "none", "matchedWords": [ "hello" ] }, "content": { "value": "Here is something to get started", "matchLevel": "full", "fullyHighlighted": false, "matchedWords": [ "hello" ] }, "pageTitle": { "value": "Getting Started", "matchLevel": "none", "matchedWords": [] }, "metaDescription": { "value": "", "matchLevel": "none", "matchedWords": [] }, "breadcrumbs": { "value": "Intro|Getting Started", "matchLevel": "none", "matchedWords": [] }, "mainTitle": { "value": "Getting Started", "matchLevel": "none", "matchedWords": [] } } } ], "nbHits": 1, "page": 0, "nbPages": 1, "hitsPerPage": 25, "query": "hello", "queryID": "3e3d57a27d66323ad411a561ce35bb78" }

This JSON contains everything the help application needs to render search results: page title, URL, breadcrumbs, the snippet to show, and the words to highlight.

Sample search service

As an example, you can try running our search service. It is a JAR file that runs as a Spring Boot application and can use Algolia indexes produced by the Writerside builder to provide responses to search requests.

Test run the search service

  1. Download writerside-search-1.0.jar.

  2. Run the following command to start the service without any search indexes:

    java -jar writerside-search-1.0.jar run
  3. Send a request to the created endpoint to test the service: http://127.0.0.1:8080/preview-search/foo/bar?isExactSearch=false&query=test

  4. The response should return zero hits because there is no search index to query against:

    {"nbHits":0,"queryID":"e6e726f8-ebce-4296-ad9c-de8ee4bd3543","hits":[]}

Run search service with index

  1. Build your documentation website with the Docker builder. It produces a ZIP archive with Algolia indexes, for example algolia-indexes-HI.zip.

  2. Unpack the Algolia indexes and specify the path to the directory when running the search service:

    java -jar writerside-search-1.0.jar run --algolia-indexes=/path/to/algolia-indexes-HI/

Now, if you query the service at http://127.0.0.1:8080/preview-search/foo/bar?isExactSearch=false&query=test, it will return results for "test" based on the indexes that it loads into memory.

Set the search endpoint in buildprofiles.xml to http://127.0.0.1:8080, then build and run your help website on a local server. The search should now query the search service against the specified indexes.

Last modified: 14 March 2024