Integrate a relevant search bar to your documentation

You might have noticed the search bar in this documentation.

And you are probably wanting the same for your own documentation!

This tutorial will guide you through the steps of building a relevant and powerful search bar for your documentation 🚀

  1. Run a MeiliSearch Instance
  2. Scrape your content
  3. Integrate the Search Bar

Run a MeiliSearch Instance

First of all, you need your documentation content to be scraped and pushed into a MeiliSearch instance.

You can install and run MeiliSearch on your machine using curl.

  1. curl -L https://install.meilisearch.com | sh
  2. ./meilisearch --master-key=myMasterKey

There are other ways to install MeiliSearch.

MeiliSearch is open-source and can run either on your server or on any cloud provider.

NOTE

The host URL and the API key you will provide in the next steps correspond to the credentials of this MeiliSearch instance.
In the example above, the host URL is http://localhost:7700 and the API key is myMasterKey.

Scrape your Content

The Meili team provides and maintains a scraper toolAdd a Search Bar to Your Docs - 图1 (opens new window) to automatically read the content of your website and store it into an index in MeiliSearch.

Configuration File

The scraper tool needs a configuration file to know what content you want to scrape. This is done by providing selectors (e.g. the HTML tag).

Here is an example of a basic configuration file:

  1. {
  2.   "index_uid": "docs",
  3.   "start_urls": ["https://www.example.com/doc/"],
  4.   "sitemap_urls": ["https://www.example.com/sitemap.xml"],
  5.   "stop_urls": [],
  6.   "selectors": {
  7.     "lvl0": {
  8.       "selector": ".docs-lvl0",
  9.       "global": true,
  10.       "default_value": "Documentation"
  11.     },
  12.     "lvl1": {
  13.       "selector": ".docs-lvl1",
  14.       "global": true,
  15.       "default_value": "Chapter"
  16.     },
  17.     "lvl2": ".docs-content .docs-lvl2",
  18.     "lvl3": ".docs-content .docs-lvl3",
  19.     "lvl4": ".docs-content .docs-lvl4",
  20.     "lvl5": ".docs-content .docs-lvl5",
  21.     "lvl6": ".docs-content .docs-lvl6",
  22.     "text": ".docs-content p, .docs-content li"
  23.   }
  24. }

The index_uid field is the index identifier in your MeiliSearch instance in which your website content is stored. The scraping tool will create a new index if it does not exist.

The docs-content class is the main container of the textual content in this example. Most of the time, this tag is a <main> or an <article> HTML element.

lvlX selectors should use the standard title tags like h1, h2, h3, etc. You can also use static classes. Set a unique id or name attribute to these elements.

Every searchable lvl elements outside this main documentation container (for instance, in a sidebar) must be global selectors. They will be globally picked up and injected to every document built from your page.

If you use VuePress for your documentation, you can check out the configuration fileAdd a Search Bar to Your Docs - 图2 (opens new window) we use in production.
In our case, the main container is theme-default-content and the selector the titles and sub-titles are h1, h2…

TIP

More optional fields are availableAdd a Search Bar to Your Docs - 图3 (opens new window) to fit your need.

Run the Scraper

You can run the scraper with Docker. With our local MeiliSearch instance set up at the first step, we run:

  1. docker run -t --rm \
  2.   --network=host \
  3.   -e MEILISEARCH_HOST_URL='http://localhost:7700' \
  4.   -e MEILISEARCH_API_KEY='myMasterKey' \
  5.   -v <absolute-path-to-your-config-file>:/docs-scraper/config.json \
  6.   getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json

NOTE

If you don’t want to use Docker, here are other ways to run the scraperAdd a Search Bar to Your Docs - 图4 (opens new window).

<absolute-path-to-your-config-file> should be the absolute path of your configuration file defined at the previous step.

The API key you must provide should have the permissions to add documents into your MeiliSearch instance. In a production environment, we recommend providing the private key instead of the master key, as it is safer and it has enough permissions to perform such requests.
More about MeiliSearch authentication.

TIP

We recommend running the scraper at each new deployment of your documentation, as we do for the MeiliSearch’s oneAdd a Search Bar to Your Docs - 图5 (opens new window).

Integrate the Search Bar

If your documentation is not a VuePress application, you can directly go to this section.

For a VuePress Documentation

If you use VuePress for your documentation, we provide a Vuepress pluginAdd a Search Bar to Your Docs - 图6 (opens new window). This plugin is used in production in the MeiliSearch documentation.

In your VuePress project:

  1. yarn add vuepress-plugin-meilisearch
  1. npm install vuepress-plugin-meilisearch

In your config.js file:

  1. module.exports = {
  2.   plugins: [
  3.     [
  4.       "vuepress-plugin-meilisearch",
  5.       {
  6.         "hostUrl": "<your-meilisearch-host-url>",
  7.         "apiKey": "<your-meilisearch-api-key>",
  8.         "indexUid": "docs"
  9.       }
  10.     ],
  11.   ],
  12. }

The hostUrl and the apiKey fields are the credentials of the MeiliSearch instance. Following on from this tutorial, they are respectively http://localhost:7700 and myMasterKey.
indexUid is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the config file.

These three fields are mandatory, but more optional fields are availableAdd a Search Bar to Your Docs - 图7 (opens new window) to customize your search bar.

WARNING

Since the configuration file is public, we strongly recommend providing the MeiliSearch public key in a production environment, which is enough to perform search requests.
Read more about MeiliSearch authentication.

For All Kinds of Documentation

If you don’t use VuePress for your documentation, we provide a front-end SDKAdd a Search Bar to Your Docs - 图8 (opens new window) to integrate a powerful and relevant search bar to any documentation website.

  1. <!DOCTYPE html>
  2. <html>
  3.   <head>
  4.     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docs-searchbar.js@{version}/dist/cdn/docs-searchbar.min.css" />
  5.   </head>
  7.   <body>
  8.     <input type="search" id="search-bar-input">
  9.     <script src="https://cdn.jsdelivr.net/npm/docs-searchbar.js@{version}/dist/cdn/docs-searchbar.min.js"></script>
  10.     <script>
  11.       docsSearchBar({
  12.         hostUrl: '<your-meilisearch-host-url>',
  13.         apiKey: '<your-meilisearch-api-key>',
  14.         indexUid: 'docs',
  15.         inputSelector: '#search-bar-input',
  16.         debug: true // Set debug to true if you want to inspect the dropdown
  17.       });
  18.     </script>
  19.   </body>
  20. </html>

The hostUrl and the apiKey fields are the credentials of the MeiliSearch instance. Following on from this tutorial, they are respectively http://localhost:7700 and myMasterKey.
indexUid is the index identifier in your MeiliSearch instance in which your website content is stored. It has been defined in the config file.
inputSelector is the id attribute of the HTML search input tag.

WARNING

We strongly recommend providing the MeiliSearch public key in a production environment, which is enough to perform search requests.
Read more about MeiliSearch authentication.

The default behavior of this library fits perfectly for a documentation search bar, but you might need some customizationsAdd a Search Bar to Your Docs - 图9 (opens new window).

NOTE

For more concrete examples, you can check out this basic HTML fileAdd a Search Bar to Your Docs - 图10 (opens new window) or this more advanced Vue fileAdd a Search Bar to Your Docs - 图11 (opens new window).

What’s next?

At this point you should have a working search engine on your website, congrats! 🎉
You can check this tutorial if you now want to run MeiliSearch in production!