Algolia Search Engine Integration

Algolia Search for HTML5 Outputs

Paligo has a built-in HTML5 search that is fast and convenient, as it does not require any additional setting up. However, if you need a high-end Enterprise-grade search, you may prefer to use Algolia.

Algolia is a third-party subscription service that provides advanced search features. It can search all languages, is extremely fast, and gives you a wider range of information and features. Another benefit is that it does not use a crawler, and so works even if your site is behind authentication. It is customizable too.

To set up Algolia search for HTML5 outputs:

Preparation for Algolia Integration

To use Algolia with Paligo, you need an Algolia account (https://algolia.com).

If you choose to start on a trial Algolia account, it is important that you choose either the free plan or purchase a paid plan as soon as possible. The Algolia trial does not automatically convert to the free plan, and so your search may become disabled when the trial expires.

When you have an Algolia account, you can connect it to Paligo.

Connect Paligo to Algolia

You need to have an Algolia account (https://www.algolia.com), and go to the Integration settings in Paligo and add your Search Only Key, Index API key, and Application Id from your Algolia account.

Note

Do not use the Admin API Key. That key should always be kept secret.

  1. Log in to Paligo via a user account that has administrator permissions.

  2. Select your profile name in the upper right corner to display a menu, and then select Settings.

  3. In the Settings view, select the Integrations tab.

  4. In the Algolia module, select the Add button.

    algoliasettings.png
  5. Inside your Algolia account, select the API Keys menu item on the right.

  6. Copy the Application ID and the API Key (Search Only Key), and paste them into each respective field in the integration settings inside Paligo.

  7. In the Algolia account, still in the API Keys section, select the tab All API Keys.

  8. Click New API Key. Leave all fields as they are, except a description (whatever you like), and the field ACL, where you should add the operations addObject and deleteObject.

    algolia-index-api-key.png
  9. Click Create.

  10. Copy the key and paste it into the Index API Key field in the Paligo integration settings.

  11. Select Save.

Enable Algolia Search in your HTML5 Output

When you have connected Paligo to your Algolia account, enable the search in your output:

  1. Create an HTML5 layout (or modify an existing one), and select the Search Engine settings. Set Use Algolia Search to Enable.

    use-agolia-search.jpg

    By default, Paligo will create or update an index with a name that is the same as the ID of the publication.

    If you set a custom index name for the Algolia index, you will need to go to your Algolia account to change the name before any changes are set live.

    If you do not use a custom index name, every time you publish, your changes are live immediately.

  2. Publish your publication. In the publishing settings, make sure you choose HTML5 and select the HTML5 layout that you set to use Algolia.

  3. In your Algolia account, select the index created when you published. Then make the following settings.

    1. In Search behavior > Deduplication and Grouping, set Distinct to true and Attribute for Distinct to title or url.

      algoliadistinct.png

      Tip

      You have several options to customize your search here as it fits your purposes. For instance, you may want to set the "Attribute for distinct" to "url" for example if you have the same topics reused in the same publication.

    2. In Relevance Essentials > Searchable attributes Ranking, add title and body and drag them into the order of importance.

      algoliasearchable.png

Your search should now work in your published HTML5 content. If you re-publish, Paligo will update the index in your Algolia account if you are using the default UUID name. If you have chosen to use a custom name, Paligo will create a new index, and it will only be used live until you rename it in the Algolia account to the name you chose as custom name.

Note

If you have a previous customization stylesheet for your HTML5 output, you may have to contact support to make sure it's compatible with the Algolia search. In some cases, the customization may need to be modified.

Faceted search page with Algolia

With Algolia, it's also possible to create a separate search page with more capabilities. Out of the box, it is possible to enable faceted search.

Faceted search means the ability to use filters to narrow down the search. In Paligo, you can use taxonomies to map to such filter facets. To enable a separate advanced search page with faceted filtering, do the following:

Note

The faceted search page is only available for the HTML5 Help Center theme.

  1. In the Layout Editor, under the Search engine section, make these settings apart from the ones already made above for Algolia:

    • Enable Create separate search page for Algolia.

    • Enable Output taxonomies as facets for Algolia Search page.

    • If you want facet filters that are just flat lists of check boxes, enter the name(s) of the taxonomy tree(s) to use for these in Taxonomies to use for flat Algolia facets. (The name of the taxonomy tree is the root level taxonomy tag).

    • If you want facet filters that are hierarchical trees, similar to the taxonomy tree itself, enter the name(s) of the taxonomy tree(s) to use for these in Taxonomies to use for hierarchical Algolia facets.

  2. Publish using this layout where you have made the settings. Then in your Algolia account, go to the index created (or updated), and define the attribute to use for facets.

    Set the attributes (based on the taxonomies in Paligo) to not searchable.

    facets-attributes.jpg
  3. Your portal page will now have a link under the main search box, "Advanced search", leading to this faceted search page. On the right of the search results pane, there will be a filter pane with the facets you have defined. The end user can use them to narrow down search results based on the category they are searching for:

    facets-output.png

Algolia DocSearch

Algolia has an extra feature called DocSearch. Paligo supports DocSearch in both of our HTML5 Help Center themes.

To use DocSearch, you first need to you need to apply to Algolia.

You can then:

  1. Set the Algolia integration settings (Connect Paligo to Algolia.

  2. Enable the Algolia search in your HTML5 layout and make sure you also enable the Use Algolia DocSearch option feature. Save the layout when you have finished.

  3. Use a text editor or similar application to create a custom CSS file. Add the following to your custom CSS:

    /* Algolia DocSearch */
    .site-sidebar{
        overflow-x: initial;
        overflow-y: initial;
    }

    Tip

    If you use a layout based on Theme 1, the above is all you need. If you use one based on Theme 2, you also need to make a few further tweaks to the CSS to make it fit well within that theme. You are of course free to style it as you like, but the CSS below is a simple suggested adjustment:

    .algolia-autocomplete .ds-dropdown-menu:before{
        display: none!important;
    }
    .tool-search-form .algolia-autocomplete.algolia-autocomplete-right .ds-dropdown-menu{
        left: 23%!important;
        margin: 0px 0 0!important;
        max-width: 1000px;
    }
    .tool-search {
    margin-bottom: -15px;
    }

    This centers the search box on content pages, makes it wider, and removes the arrow on the search box (which would not fit well with Theme 2).

  4. Upload the custom CSS file to your HTML5 layout. You can upload it in the CSS, JS, logos and other assets settings, in the CSS box. Save the layout when you have uploaded the file.

    custom-css-upload.jpg