GitHub Download

How to configure DocSearch in a supported Publii theme?

Our documentation themes support search using Algolia DocSearch. This search engine is free and works really well, providing an effective search solution even for expansive documentation projects.

How does it work?

Much like other search engines, DocSearch uses a scraper to index your site content; in simple terms, the scraper reads through your website and stores the data, which it can then collate to make a custom search that is effective for your site. Uniquely, DocSearch is targeted to documentation specifically; this means it is designed to help users more effectively find answers to specific questions or subjects within a narrow scope rather than looking for more generalised relevance, and it also offers autocomplete functionality to help users locate the sections that will be more helpful in answering their query.  

With the data collected, Algolia will automatically configure a search relevant to your site content, then provide methods to integrate the search into your site. The functionality for the search is handled by DocSearch itself; processing the search query and delivering results occurs separate from your site’s infrastructure.

Why DocSearch?

Publii already has support for Google’s search functionality, so why add DocSearch? This decision is based not on what each engine is trying to do, as the goal is the same; to provide you with the desired result. However, for a search engine to work effectively it must have an idea of what you are looking for. As DocSearch is aimed squarely at documentation searches, it will be more efficient and effective at answering specific queries and pointing you to relevant sections in the documentation, rather than the more general searches that Google provides. Think of it as having the option to use two different detectives; both are good at what they do, but each one has specific qualities that make them better at finding what you need in different circumstances!

DocSearch requirements

The process to add DocSearch to your Publii documentation site is not difficult or time-consuming, but it is a little bit more controlled than Google’s.

In order to use DocSearch, you must meet several conditions:

  1. Your website must be publicly available so that DocSearch can index it.
  2. Your website must be a documentation site. Algolia will reduce the scope of their scrap to helpful pages only.
  3. Your website is production-ready; that is, already contains content relevant and useful documentation. Algolia will not accept placeholder or lorem ipsum websites that are intended to be updated later.

How to get started?

Once your website is online and ready to add search functionality, you should submit it to DocSearch on their frontpage; the form in the header of the site will allow you to do this. You will only need provide the website URL and your email address so that you can receive the search credentials once they are ready; note that you will also need to be the owner of the website in question and confirm this when submitting your application. Once Algolia accept your submission they will send you the credentials for enabling your search via email.

After receiving the confirmation email, you will need to copy the following data from the provided credentials in the email to the Search section of the Theme settings screen in Publii:

  • apiKey: '3e5f958f78d72a8aa83b1c34f5123456',
  • indexName: 'getpublii',

Dosearch with Static Website

With this done, you can save the changes and the search will be ready to go. DocSearch will crawl your website every 24 hours to ensure your search is up-to-date; the DocSearch team recommend that your site includes a sitemap as this will allow it to better track changes, and it has the added benefit of being considered best practice for SEO! By default Publii generates a full sitemap for you, but if you would like to check that it is enabled or want to exclude content from the sitemap you can do so in the Settings → Advanced options → Sitemap section of the Publii interface.

Subscribe

Get the latest Publii news, updates and more delivered directly to your email inbox

You can change your mind at any time by clicking the unsubscribe link in the footer of any email you receive from us, or by contacting us at contact@tidycustoms.net. By clicking below, you agree that we may process your information in accordance with our Privacy Policy.