Configure search

Currently, Writerside provides a built-in solution that provides search for local preview and relies on Algolia as an external service for search in published documentation.

Create Algolia application and search index

Sign up for an Algolia account.
The free plan is limited to 10,000 search requests per month and 1 million total records. You can compare plans at https://www.algolia.com/pricing/.
On the Algolia applications page, Click Create Application.
Configure application parameters, select a region for your datacenter, and create the application.
On the Algolia application page, go to Data sources | Indices and click Create Index.
Provide an informative name and create the index.
On the index page, go to Configuration | Facets, and click Add an attribute under Attributes for faceting.
Add two attributes: product and version.
Click Review and Save Settings and confirm.

Add Algolia parameters to Writerside build configuration

In your documentation project, open the cfg/buildprofiles.xml file.
You might have to create it if it is a new documentation project.
In the <variables> tag specify the following:
<algolia-id>
Algolia application ID
<algolia-index>
Algolia index name
<algolia-api-key>
Algolia Search-Only API Key
<web-root>
Your domain name.
If you do not have one, specify any fake URL, such as https://some.domain/
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> <algolia-id>TGW4GIW73X</algolia-id> <algolia-index>index_name</algolia-index> <algolia-api-key>29effd68f91893202311a653263f1fb8</algolia-api-key> <web-root>https://some.domain</web-root> </variables> <build-profile instance="instance_id"/> </buildprofiles>
You can find the application ID and API keys in your Algolia account settings under API Keys.
Commit and push these changes, then build and publish the help instance with these configuration parameters.

Publish your search index to Algolia

To reply to search requests from your help, Algolia needs the search index from the build artifact that you published. Depending on the CI/CD that you use, follow the instructions for TeamCity or GitHub Actions.

If you do not yet have a TeamCity configuration for building your help artifacts, set it up as described in Build on TeamCity Cloud.
Create a separate build configuration for publishing search indexes to your Algolia application.
Configure it to use the following Docker image:
registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-2
This image will run the help-publication-agent script.
Create a Command line type step with the following command:
env "algolia-key=${'$'}ALGOLIA_KEY" java -jar /opt/builder/help-publication-agent.jar \ update-index \ --application-name ${'$'}ALGOLIA_APP_NAME \ --index-name ${'$'}ALGOLIA_INDEX_NAME \ --product ${'$'}CONFIG_JSON_PRODUCT \ --version ${'$'}CONFIG_JSON_VERSION \ --index-directory algolia-index/ \ 2>&1 | tee algolia-update-index-log.txt
In General Settings, in the Artifact path field, add algolia-update-index-log.txt to write logs.
In Dependencies, add artifacts produced by your help build configuration: webhelp.zip and algolia-indexes-*.zip!** => algolia-index. This action unpacks the ZIP archive with indexes to algolia-index.
In Parameters, add the following environment variables:
env.ALGOLIA_APP_NAME
Algolia application ID
env.ALGOLIA_INDEX_NAME
Name of Algolia index
env.ALGOLIA_KEY
Algolia Admin API Key.
This is a private key. Set the type of this parameter to Password, so that users without proper permissions will not see its value.
env.CONFIG_JSON_PRODUCT
Help instance ID from the tree file or the value of the web-path attribute specified in writerside.cfg if it is different from the ID
env.CONFIG_JSON_VERSION
Help instance version (usually the same as the branch name) specified in writerside.cfg
You can find the application ID and API keys in your Algolia account settings under API Keys.
Save the build configuration settings and click Deploy. After it finishes successfully, go to the index in your Algolia account and make sure that the index records have really been uploaded.

You will need to upload new search index records every time you publish a new help build.

If you do not yet have a GitHub Actions workflow that builds your help artifacts, set it up as described in Build and publish on GitHub.
In your repository on GitHub, go to Settings | Secrets and variables | Actions, and add a New repository secret called ALGOLIA_KEY with Algolia Admin API Key from your Algolia account.
You can find the application ID and API keys in your Algolia account settings under API Keys.
Go to your existing GitHub Actions workflow YAML file and add a job that publishes Algolia indexes to your application:
publish-indexes: # Requires the build-job results needs: build runs-on: ubuntu-latest container: image: registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-2 steps: - uses: actions/checkout@v3 - uses: actions/download-artifact@v3 with: name: algolia-indexes - name: Unzip artifact run: | unzip -O UTF-8 -qq ${{ env.ALGOLIA_ARTIFACT }} -d algolia-indexes env "algolia-key=${{env.ALGOLIA_KEY}}" java -jar /opt/builder/help-publication-agent.jar \ update-index \ --application-name ${{env.ALGOLIA_APP_NAME}} \ --index-name ${{env.ALGOLIA_INDEX_NAME}} \ --product ${{env.CONFIG_JSON_PRODUCT}} \ --version ${{env.CONFIG_JSON_VERSION}} \ --index-directory algolia-indexes/ \ 2>&1 | tee algolia-update-index-log.txt
Add the following environment variables to the workflow:
env.ALGOLIA_APP_NAME
Algolia application ID
env.ALGOLIA_INDEX_NAME
Name of Algolia index
env.ALGOLIA_KEY
Algolia Admin API Key.
This is a private key. Store it as a secret and reference via ${{ secrets.ALGOLIA_KEY }}.
env.ALGOLIA_ARTIFACT
The name of the ZIP archive with Algolia indexes from the build artifacts.
env.CONFIG_JSON_PRODUCT
Help instance ID from the tree file or the value of the web-path attribute specified in writerside.cfg if it is different from the ID
env.CONFIG_JSON_VERSION
Help instance version (usually the same as the branch name) specified in writerside.cfg
You can find the application ID and API keys in your Algolia account settings under API Keys.
For example:
env: ALGOLIA_APP_NAME: TGW4GIW73X ALGOLIA_INDEX_NAME: index_name ALGOLIA_KEY: ${{ secrets.ALGOLIA_KEY }} ALGOLIA_ARTIFACT: algolia-indexes-HI.zip CONFIG_JSON_PRODUCT: HI CONFIG_JSON_VERSION: 1.0
Run the publish-indexes job. After it finishes successfully, go to the index in your Algolia account and make sure that the index records have really been uploaded.

After you upload the index records to Algolia, you can check that search works in your published help.

Last modified: 08 December 2023