Paligo's HTML5 Help Center output has a built-in search feature that is suitable for many of our customers. But on the Business and Enterprise plans, we also have integrations with more advanced search engine services, such as Algolia.
Algolia is a powerful site search service that requires a subscription (see algolia.com for details). It is exceptionally fast, highly customizable, and supports advanced search features such as faceted search. Another benefit is that it does not use a crawler, and so works even if your site has authentication and requires users to log in.
Typically, Paligo customers use the Algolia integration to add:
-
Algolia search
This enhances the search feature of your published HTML5 Help Center, giving much faster results. You can also use Algolia's extensive customization features to control how your search works.
To get started, see Algolia Search.
-
Algolia faceted search
Faceted search allows users to search for terms and then narrow the search further by applying filters to the search results. There are two types of faceted search you can use with Paligo - "flat" faceted search and "hierarchical" faceted search. To learn about these, see Algolia Faceted Search.
Note
To use Algolia faceted search, first set up the regular Algolia search. When that is in place, you can Set Up Algolia Faceted Search.
To learn how to use JavaScript to customize your Algolia search beyond what is available in the layout settings, see Customize Algolia Search with JS.
You can use Algolia to enhance the search in your HTML5 Help Center outputs. When set up correctly, Algolia search replaces Paligo's default search and gives your help center a faster, more customizable search. It works even if your site uses authentication and you can set it up to give results as soon as a user enters three characters of a search query.
Algolia has many features for customizing your search and also supports faceted search, where users can apply filters to the search results.
To use Algolia search with your HTML5 Help Center(s), you need:
-
An Algolia account
-
A Paligo account on the Business or Enterprise plan (you will need to log in as an administrator)
For instructions on connecting Paligo to Algolia, see Set Paligo to use Algolia Search.
Note
When you have Algolia search working with Paligo, you can also set up Algolia faceted search. This is a more advanced search where users can apply filters to the search results.
If you prefer, you can use regular Algolia search without faceted search.
To set Paligo to use Algolia search for your HTML5 outputs:
To connect Paligo to Algolia:
-
If you do not already have an Algolia account, set one up at https://www.algolia.com.
-
Log in to Paligo via a user account that has administrator permissions.
-
Select the avatar in the top-right corner.
-
Select Settings from the menu.
-
Select the Integrations tab.
-
In the Algolia module, select the Add button (or Change if you are editing an existing Paligo-Algolia integration).
-
In a different browser tab or window, log in to your Algolia account and find the Application ID and API Key (Search Only Key). For information on how to find these API Key settings, see the official Algolia documentation.
-
In Algolia, copy the Application ID and then paste it into the Application ID field in Paligo.
-
In Algolia, copy the API Key (Search Only Key) and then paste it into the Search Only API Key field in Paligo.
If you are not using DocSearch, continue with the next step.
If you are using DocSearch rather than the licensed Algolia search, select Save and ignore the remaining steps in this procedure.
-
In Algolia, create a new API key. In its ACL field, add the operations addObject and deleteObject.
For details on creating a new API key, see the official Algolia documentation.
-
In Algolia, copy the new API key and then paste it into the Index API Key field in Paligo.
-
Check the box Use gateway to enable IP Allowlisting. Optional
When have connected Paligo to Algolia , the next step is to set up Algolia search in your HTML5 layout. There are several Algolia-related settings, some of which are optional, depending on whether you want to use Algolia's faceted search feature.
-
Select the Layout tab in the top menu.
Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
-
Select the layout to be updated or Create a Layout.
-
Select Search Engine in the sidebar.
-
Choose whether the layout should Use Algolia Search:
-
Enable
Sets Paligo to use the Algolia search engine for publications made using this layout.
-
Disable
Sets Paligo to use its own built-in search engine. The Algolia search engine is not used.
-
Default - To inherit the value for this setting from the base layout. The base layout is either a built-in layout provided by Paligo or another custom layout. To find out more, see Layout Relationships - Base, New, Duplicate.
-
-
Set the Use Algolia DocSearch option status:
-
Enable
Choose this option if your organization has been accepted into the Algolia DocSearch program. Algolia DocSearch is a special type of Algolia account that you have to apply for.
-
Disable
Choose this option if your organization is not using Algolia DocSearch.
-
-
If you want the Algolia index to have a specific name, enter the name in the Use custom index name for Algolia Search field. This only works when publishing publications in a single language. Leave the field clear to set Paligo to create indexes based on the publication IDs.
For more details, see Custom Index Name for Algolia Search.
-
Choose whether you want Paligo Create separate search page for Algolia:
-
Enable
Choose Enable if you want your output to use Algolia's faceted search.
-
Disable
Choose Disable if you do not want your output to use Algolia's faceted search.
-
-
Use Delayed search for Algolia to control what happens when a user starts typing in a search query:
-
Enable
Algolia will only start providing search results when the user has entered three characters in the search field. If you have set your output to use a separate search page for Algolia, the user has to press Enter to get results on that page.
-
Disable
Algolia will start providing results as soon as the user enters a character in the search field.
For more details on this feature, see Delay Search Results as Users Type Query.
-
-
Set Use breadcrumbs path in Algolia search results to:
-
Enable
To show the breadcrumb for a search result when you hover the cursor over the result.
The breadcrumb shows where the search result topic appears in the hierarchy.
If you use the Advanced Search option (below the main search field), the breadcrumb is shown as text below each search result.
-
Disable
To prevent the breadcrumb from appearing.
-
Default - To inherit the value for this setting from the base layout. The base layout is either a built-in layout provided by Paligo or another custom layout. To find out more, see Layout Relationships - Base, New, Duplicate.
-
-
Choose whether you want Paligo to Output taxonomies as facets for Algolia Search page:
-
Enable
Choose Enable if you want your output to use Algolia's faceted search.
-
Disable
Choose Disable if you do not want your output to use Algolia's faceted search.
-
-
If you want your output to use Algolia faceted search, you will need to set up taxonomies for each "facet". You need to enter the taxonomy names in one of the following fields:
-
Taxonomies to use for flat Algolia facets
Enter the name of each taxonomy that you want to use in a "flat" faceted search.
-
Taxonomies to use for hierarchical Algolia facets
Enter the name of the taxonomy that you want to use in a "hierarchical" faceted search.
In both cases, use a semi-colon to separate each taxonomy name, for example: brand;product;color. For details, see Set Up Algolia Faceted Search.
If you do not want Paligo to use faceted search, clear the fields.
-
-
Select Save.
Having Use Algolia Search set to Enable is the only requirement (in the Layout) for connecting Paligo to Algolia. If you intend to set up Algolia faceted search, you will need to change some of the other settings too, as described in Set Up Algolia Faceted Search. The other Algolia-related settings are optional.
To perform a search, Algolia needs an index. The index contains information about the content that Algolia should search for results.
The following steps explain how to create and edit the index. For this, we assume that you have already set up: and an HTML5 help center layout
-
An HTML5 help center layout so that Algolia is enabled.
-
In Paligo, use an HTML5 help center layout (that has Algolia enabled) to publish a publication (see General Publishing Process. When Paligo completes the publishing process, it uploads a JSON file to Algolia and creates an index.
To learn how to enable Algolia in an HTML5 help center layout, see Set Up Algolia Search in your HTML5 Layout.
-
In Algolia, select your application and look at the Index section. It lists each index that has been created for your application.
By default, Paligo creates an index for each language that you publish. Each index name consists of a language code prefix and the UUID of the publication. For example:
en-UUID-817f5a19-d0db-0059-32e9-a958b958b9f85e62
Note
If your HTML5 layout is set to use a text name instead of the publication ID, the index will have that name. For details, see Custom Index Name for Algolia Search.
-
Select the link for the index for the publication you published.
-
Select the Configuration tab.
-
In the SEARCH BEHAVIOR section, select Deduplication and Grouping.
-
Configure these settings:
-
Distinct
Set this to True.
-
Attribute for Distinct
Set this to either title or url.
-
-
In the RELEVANCE ESSENTIALS section, select Searchable Attributes.
-
Add searchable attributes for:
-
title
-
body
-
-
Set title and body to be ordered and then drag them into the order you want, where the top attribute in the list is most important. Typically, users set title as the top attribute.
-
If you published in multiple languages, repeat this procedure for the indexes Paligo created for the other languages.
Note
You only need to configure an index once. When you next publish the same publication, Paligo will update the index without changing the configuration you have in place.
Your HTML5 help center output should now be set up to use Algolia search. To learn how to test it, see Test your Algolia Search.
To test that Algolia search is working with your HTML5 Help Center:
-
Make sure that you have a working Internet connection.
-
Edit the HTML5 help center layout that you set up in Set Up Algolia Search in your HTML5 Layout:
-
Publish your content. In the publishing settings, choose HTML5 and select the HTML5 help center layout you edited in the previous step. Check the Debug box at the bottom and then select Publish.
Paligo publishes your content. A zip file downloads in the browser.
-
Unzip the downloaded file.
-
Open the unzipped file and browse to the out folder. Inside the out folder is an index.html file.
-
Open the index.html file in a browser.
-
In the search bar, type three or more letters of a phrase that you know exists in your help center content. If Algolia is correctly connected to your Paligo content, you will see a suggestion box appear as you type.
If there is no suggestion as you type, it is a sign that the Algolia search is not working correctly. This is usually because of incorrect settings (see Troubleshooting Algolia Search).
-
If you have set up faceted search and want to test it, select "advanced settings" under the search bar on the help portal page. The browser should show you a results page with filters on the left.
If you do not see a filters section, or the filters section is there but has no options, there is likely a problem in the setup (see Troubleshooting Algolia Search).
If you experience problems when setting up Algolia search, we recommend that you go through the configuration steps again carefully:
Some of the most common mistakes are:
-
Forgetting to enable Algolia in the layout
-
Typos or copying mistakes for the API keys in the Paligo integration settings
-
Configuring the wrong index in Algolia. You need to configure the index that matches your publication.
-
Publishing topics that only contain the title and a default para ("Insert text").
Empty topics and topics that only contain the title and a default paragraph ("insert text") will result in Paligo being unable to create the JSON file that Algolia needs.
When you publish with Algolia enabled, Paligo either creates a new index in Algolia or updates an existing one. By default, it sets the name of the index to match the UUID of the publication, but you can set up a custom index name if you prefer. Custom index names are only available for publications in a single language.
You can set the custom index name in the Layout you use for publishing. It is important that you set the custom name in Paligo before you publish to Algolia. If you publish to Algolia and then change the index name in Algolia, you will need to go back and change the index name in Paligo too, and then publish again.
Note
If you decide to use a custom name, be aware that Paligo will use the same name each time you publish. For this reason, don't use a custom name if you want to publish many publications with the same layout. If you do, each time you publish, Paligo will replace the index.
To control whether Paligo uses a custom index name:
-
Select the Layout tab in the top menu.
Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
-
Select the layout to be updated or Create a Layout.
-
Select Search Engine.
-
In the Use custom index name for Algolia Search field, enter the name for the index. This has to match the final index name that you want to use in Algolia.
-
Select Save.
-
Publish your content using the HTML5 layout you edited in the previous steps.
Paligo will publish the content and either create an index in Algolia or update an existing one. This index will have a name that is based on the UUID of the publication. But in the HTML of your content pages, the code will reference the custom index name. For this reason, you will need to rename the index in Algolia (see next step).
-
In Algolia, manually rename the index (that has is currently named to match the UUID of the publication). You must change the index name so that it is an exact match of the name you entered in the layout's Use custom index name for Algolia Search field.
When using Paligo and Algolia search, you can control how the search field works as users type in a search query. You can choose between:
-
Search returns results as soon as user starts entering a search term
-
Search returns results only after the user enters three characters of the search term*
*If your HTML5 help center is set up to use a separate search page for Algolia, results are only returned when the user presses Enter or selects submit.
To control the responsiveness of the search:
-
Select the Layout tab in the top menu.
Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
-
Select the layout to be updated or Create a Layout.
-
Select Search Engine.
-
Use Delayed search for Algolia to control what happens when a user starts typing in a search query:
-
Enable
Algolia will only start providing search results when the user has entered three characters in the search field. If you have set your output to use a separate search page for Algolia, the user has to press Enter to get results on that page.
-
Disable
Algolia will start providing results as soon as the user enters a character in the search field.
Tip
You can change the character limit by using JavaScript. For example, the following script changes the limit to 7:
var instantsearch_minlength = 7;
To add the script, use a code editor or text editor to create the script and save the file with a .js extension. Then upload the script as a custom JS script in your HTML5 Help Center layout (see Upload Customized JavaScript).
-
-
Select Save.
Note
For this procedure, we assume that the other settings for Algolia search are in place. To learn about these settings, see Connect Paligo to Algolia, Set Up Algolia Search in your HTML5 Layout, and Configure the Index in Algolia.
Algolia supports some customizations that are made by adjusting the parameters that are used in "calls" with an API client. These customizations need to be set up differently when using Algolia with Paligo as there is no API client involved (the Paligo integration handles the communications between Paligo and Algolia).
When you publish Paligo content with Algolia enabled, the pages load a JavaScript file called html5.algoliasearch.js. This file is included in the js folder of the output) and it defines the addSearch() function. If you look inside the addSearch() function, you can see the script we have used for Algolia search.
To customize the search, you can write your own addSearch() function in JavaScript and include the Algolia parameters you want to use. Upload your custom JavaScript to your HTML5 Help Center layout in Paligo. When you publish, your custom script will override the html5.algoliasearch.js script.
For details on uploading custom JavaScript to Paligo, see Upload Customized JavaScript.
If you need a customization that goes beyond overriding the parameters in the addSearch() function, Paligo may be able to provide that as a professional service project. For details, contact customer support with details of what you want to achieve. Note that there is a fee for professional services projects.
Faceted search is an advanced search feature that lets users apply further criteria to search results. They are often used on shopping web sites, where you can search for an item and then filter the results by size, color, style, and product type. In technical communication, they are popular for filtering search results to only show content for specific models, versions, subject matter, and other categorizations.
Algolia supports faceted search and you can use it with your Paligo content (one language only). There are two different styles of faceted search available: "flat" and "hierarchical".
With "flat" faceted search, there is a heading for each category of filter. Below the heading, there are checkboxes for each of the filters in that category.
When you check a box, Algolia displays search results that:
-
Are relevant to the search term (entered in the main search field)
-
Have a taxonomy tag that matches the name of the selected filter.
You can apply multiple filters at the same time and Algolia will update the search results.
With "hierarchical" faceted search, the filter categories are shown. If you select a category, it expands to reveal the facets you can use for filtering the search results.
When you select a facet, Algolia displays search results that:
-
Are relevant to the search term (entered in the main search field)
-
Have a taxonomy tag that matches the name of the selected filter.
With "hierarchical" faceted search, you can only apply one filter to the results. This is the default "out-of-the-box" behavior, but it may be possible to change how it works with a customization (a fee is required for professional services projects). For details, please contact customer support.
To learn how to set up the taxonomies, layout, and Algolia indexes for faceted search, see Set Up Algolia Faceted Search.
Algolia supports faceted search, which is an advanced search that allows users to filter search results. The following images shows "flat" faceted search, where there are headings with checkboxes for each filter. Paligo also supports "hierarchical" faceted search, where the filters are shown in a hierarchy, without checkboxes.
Faceted search is only available for one output language.
To set up Algolia faceted search, you must first set up the regular Algolia search (see Set Paligo to use Algolia Search). When you have Algolia search set up and working, there are three extra stages for flat faceted search: setting up your taxonomy, setting up your HTML5 layout for faceted search, and finally, setting up the Algolia index.
To use Algolia's faceted search with Paligo, you need to set up taxonomies to act as your "facets". Facets are filter categories.
-
In Paligo, create the taxonomy tags that you want to use as filter categories. You need to create a "parent" top-level taxonomy for each category type, and then individual taxonomy tags inside the categories. For example, to filter by model, you would create a "parent" taxonomy tag called "model". You would then create a "child" taxonomy tag for each model, such as "acme 100", "acme 200", "acme 300" and so on.
For additional filter categories, you add more "parent" and "child" taxonomy tags. For example, to add a "feature" category with filter options of "camera" and "flight", you would create a parent "feature" tag. You would then create a "camera" tag and a "flight" tag as "children" of the "feature" tag.
To learn more about creating taxonomies, see Create Taxonomy Tags.
-
Apply the taxonomy tags to your topics.
The HTML5 Help Center layout has settings for enabling faceted search and defining which taxonomies should be used as filter categories. You need to set these up before you publish.
-
Select the Layout tab in the top menu.
Paligo displays a list of Layouts. The list is empty if there are no custom Layouts in your Paligo instance.
-
Select the layout to be updated or Create a Layout.
-
Select Classes and attributes in the sidebar.
-
Set Output taxonomies to Enable.
This tells Paligo to include the taxonomies in the published output.
-
Select Search Engine in the sidebar.
-
Set Use Algolia Search to Enable.
-
Set Create separate search page for Algolia to Enable.
This tells Paligo to create a search page specifically for Algolia search. When you publish, it is available from an "advanced search" option that appears below the search field on the help center "portal page".
-
Set Output taxonomies as facets for Algolia Search page to Enable.
This tells Paligo to include taxonomies as "facets" (filter categories) on the Algolia search page.
-
Tell Paligo which "parent" taxonomies to use as a filter category. For this, use the field for the type of Algolia faceted search you want to create:
-
Taxonomies to use for flat Algolia facets
Use this field if you want flat Algolia faceted search.
-
Taxonomies to use for hierarchical Algolia facets
Use this field if you want hierarchical Algolia faceted search.
Enter the name(s) of each "parent" taxonomy that you want to be a filter category. You do not need to enter the "child" taxonomies. The names must be in lower case and use a semi-colon to separate the taxonomies, for example:
model;feature
-
-
Select Save.
To get the faceted search to work, you need to publish from Paligo so that Algolia gets an index for your publication. Paligo will create an index for each publication (1 index per language).
When your publication has an index in Algolia, you will need to configure the index to use facets. The facets are based on the taxonomy tags in Paligo (see Set Up Taxonomies for the Facets).
-
Publish your publication using the HTML5 Help Center layout you set up to use Algolia. To learn about publishing, see General Publishing Process.
When you publish, Paligo will send a JSON file to your Algolia instance. It will either:
-
Create a new index.
-
Recreate the entire index (if you have previously published this publication with Algolia enabled)
-
-
In Algolia, select your application and look at the Index section. It lists each index that has been created for your application.
By default, Paligo creates an index for each language that you publish. Each index name consists of a language code prefix and the UUID of the publication. For example:
en-UUID-817f5a19-d0db-0059-32e9-a958b958b9f85e62
Note
If your HTML5 layout is set to use a text name instead of the publication ID, the index will have that name. For details, see Custom Index Name for Algolia Search.
-
Select the link for the index for the publication you published.
-
Select the Configuration tab.
-
In the FILTERING AND FACETING section, select Facets.
-
Use the Add an attribute drop-down list to add the attributes for the filter categories. If Algolia does not include the required attributes in the list, there may be a problem with the Paligo-to-Algolia setup, see Test your Algolia Search.
-
For "flat" faceted search:
Add an attribute for each of the "parent" filter categories that you want to include. The drop-down list should include the facet names of your "parent" taxonomy tags. .
-
For "hierarchical" faceted search:
Add these attributes:
-
hierarchicalCategories.lvl0
-
hierarchicalCategories.lvl1
-
-
-
Make sure the attributes are set to not searchable.
-
Select Review and Save settings.
-
Select the Browse tab to see a preview of the facets.
Your faceted search should now work with your published output. To try it out, see Test your Algolia Faceted Search.
When you have set published your content with an Algolia-enabled layout, test that the faceted search is working:
-
Double-click on the zip file that downloaded in your browser when you published your content.
Your computer unzips the file, revealing its contents.
-
Browse to the out folder and open the
index.htmlfile that is inside it.The browser opens the Help Center "portal page".
-
On the help portal page, select the Advanced Options link below the main search field.
Paligo displays the Algolia search page.
-
Try using the filters to the side of the search results. Each of the check boxes is a "facet" and matches a taxonomy tag that you applied to your topics in Paligo. When you check a box, Algolia updates the search results so that they only include topics that have the selected facet.
-
For "flat" faceted search:
Enter a search term to get the results and then use the "facet" checkboxes to filter the results. There should be a checkbox for each "facet" and when you check a box, the results should filter so that they only include topics with that taxonomy/facet.
You can apply multiple filters at the same time, and Algolia will show the results that have all of the selected filters. For example, in the following image, the search results ("Thermal Camera", "Auto-Tracking", "Zoom" and "Camera Angle") all have the "acme 300" and "camera" taxonomy tags.
-
For "hierarchical" faceted search:
Enter a search term to get the results. Then expand any of the "parent" categories to reveal the "child" facets. Select a "child" facet and the results should update to show only topics that have that facet/taxonomy (and are relevant to the search term).
For example, in the following image, we expanded "feature" and then selected "camera". This filtered the search results so that they only show topics that have the camera facet/taxonomy (and are relevant to the search term).
-
If the faceted search is not working as expected, first check that the regular Algolia search is working (see Test your Algolia Search). If that is working, then check the common issues with faceted search.
If your Algolia faceted search is not working as expected, first check that regular Algolia search is working (see Test your Algolia Search).
When you are sure that the regular Algolia search is working, check that:
-
The taxonomy tags are applied to your topics in Paligo.
If you select a taxonomy tag in the Taxonomy Manager, Paligo displays a list of the topics and publications that have that tag.
For details, see Taxonomies View.
-
The taxonomy tags use lower case letters only.
This is required for the JSON file that Paligo sends to Algolia.
-
You have set the layout to include the correct taxonomy names. Also check that they are spelled correctly and that you have used the appropriate field (there are separate fields for "flat" and "hierarchical" faceted search).
For more information, see Set Up Algolia Faceted Search.
-
You have configured the index in Algolia correctly, see Configure Facets in the Algolia Index.
If you complete all of the above steps and still have issues with faceted search, contact Paligo customer support for help.
Comments
0 comments
Article is closed for comments.