meilisearch/docs-searchbar.js

Front-end search bar for documentation with Meilisearch

Website | Roadmap | Meilisearch Cloud | Blog | Documentation | FAQ | Discord

⚡ A lightning-fast search engine that fits effortlessly into your apps, websites, and workflow 🔍

Meilisearch helps you shape a delightful search experience in a snap, offering features that work out-of-the-box to speed up your workflow.

🔥 Try it! 🔥

✨ Features

• Search-as-you-type: find search results in less than 50 milliseconds
• Typo tolerance: get relevant matches even when queries contain typos and misspellings
• Filtering and faceted search: enhance your users' search experience with custom filters and build a faceted search interface in a few lines of code
• Sorting: sort results based on price, date, or pretty much anything else your users need
• Synonym support: configure synonyms to include more relevant content in your search results
• Geosearch: filter and sort documents based on geographic data
• Extensive language support: search datasets in any language, with optimized support for Chinese, Japanese, Hebrew, and languages using the Latin alphabet
• Security management: control which users can access what data with API keys that allow fine-grained permissions handling
• Multi-Tenancy: personalize search results for any number of application tenants
• Highly Customizable: customize Meilisearch to your specific needs or use our out-of-the-box and hassle-free presets
• RESTful API: integrate Meilisearch in your technical stack with our plugins and SDKs
• Easy to install, deploy, and maintain

📖 Documentation

You can consult Meilisearch's documentation at https://www.meilisearch.com/docs.

🚀 Getting started

For basic instructions on how to set up Meilisearch, add documents to an index, and search for documents, take a look at our Quick Start guide.

⚡ Supercharge your Meilisearch experience

Say goodbye to server deployment and manual updates with Meilisearch Cloud. No credit card required.

🧰 SDKs & integration tools

Install one of our SDKs in your project for seamless integration between Meilisearch and your favorite language or framework!

Take a look at the complete Meilisearch integration list.

⚙️ Advanced usage

Experienced users will want to keep our API Reference close at hand.

We also offer a wide range of dedicated guides to all Meilisearch features, such as filtering, sorting, geosearch, API keys, and tenant tokens.

Finally, for more in-depth information, refer to our articles explaining fundamental Meilisearch concepts such as documents and indexes.

📊 Telemetry

Meilisearch collects anonymized data from users to help us improve our product. You can deactivate this whenever you want.

To request deletion of collected data, please write to us at [email protected]. Don't forget to include your Instance UID in the message, as this helps us quickly find and delete your data.

If you want to know more about the kind of data we collect and what we use it for, check the telemetry section of our documentation.

📫 Get in touch!

Meilisearch is a search engine created by Meili, a software development company based in France and with team members all over the world. Want to know more about us? Check out our blog!

🗞 Subscribe to our newsletter if you don't want to miss any updates! We promise we won't clutter your mailbox: we only send one edition every two months.

💌 Want to make a suggestion or give feedback? Here are some of the channels where you can reach us:

• For feature requests, please visit our product repository
• Found a bug? Open an issue!
• Want to be part of our Discord community? Join us!

Thank you for your support!

👩‍💻 Contributing

Meilisearch is, and will always be, open-source! If you want to contribute to the project, please take a look at our contribution guidelines.

📦 Versioning

Meilisearch releases and their associated binaries are available in this GitHub page.

The binaries are versioned following SemVer conventions. To know more, read our versioning policy.

Differently from the binaries, crates in this repository are not currently available on crates.io and do not follow SemVer conventions.

docs-searchbar.js's Issues

Use Meili's style and main color

It might be cool to use the Meili's color and a better style (if you are inspired) for our own dropdown.

All the files are:

• in src/styles/*.scss for the CSS
• in src/lib/templates.js for the html

Hotkey / does not work

The autocomplete.js library does not recognize the / character as hotkey. You must pass 191 instead of '/' to get it worked.

The docs-searchbar.js should check the user input in autocompleteOptions.keyboardShortcuts: if there is a / it should replace it by 191 so that autocomplete.js can take it into account.

Text in backticks does not appear in search results

Observation:

• Text in backticks that is a heading show ups in search results
• Text in backticks that is regular text or in tables does not

1. createdAt:

• The first result is a heading: /reference/api/keys.md#key-object
• createdAt from /reference/api/indexes.md#index-object does not appear

2. uid

• Only shows uids that are headings:
  • /reference/api/keys.md#uid
  • /reference/api/tasks.md#uid
  • uid is used in the /reference/api/indexes.md#index-object table and almost every “Path parameters” table, but these are not part of the search results

3. databaseSize
   Only used in the /reference/api/stats.md#stats-object table but this table is not in the results

Add browser tests with Cypress

Cypress is a library to run tests in a browser.

To ensure this package work, we would like to add tests with Cypress.

Follow this guide to implement it: https://github.com/meilisearch/integration-guides/blob/main/guides/cypress.md

Feel free to ask any question about this issue implementation 🙂

Remove dupicated version mention

Version are both changed in package.json and version.js.

Creating a duplication of changes in each release. version.js is used by src/lib/main.js

import toFactory from 'to-factory'
import DocsSearchBar from './DocsSearchBar'
import version from './version'

We should find a solution to avoid this duplication

Update image inside of README with latest Meilisearch logo

Update image inside of README with latest Meilisearch logo. Currently it shows the old logo

Upgrade webpack cli to v4

And make the build work again.

https://github.com/meilisearch/docs-searchbar.js/pull/138/checks?check_run_id=1242282848

Question: search bar's cardinality with indexes

Can the searchbar work with multiple indexes or only one?

Change master branch to main

Let's be allies and make this change that means a lot.

Here is a blog post that explain a little more why it's important, and how to easily do it. It will be a bit more complicated with automation, but we still should do it!

Create environment where dark mode can be disabled or enabled

Description
As from this PR #340 when dark mode is set on OS it will automatically change the docs-searchbar.js to a dark mode. Disabling this is quite painful.

Dark mode in OS is not always the mode you want on your apps.

Solution

We should wrap the modes into classes in order to make them toggable. For example, using the solution suggested here

Add dark-mode

Dark mode is not enabled on the code and does not switch if implemented on another website.

Should we remove the ".lock" file?

We are thinking about removing (or not) the .lock file of this package.

Since this discussion concerns all the JS tools of the MeiliSearch organization, we created a centralized issue: meilisearch/integration-guides#53.

If you are interested in this topic, please read it and feel free to share your (professional or not) experience with us on this main issue. Every opinion would be really helpful! 😁

Scroll issue on Firefox 74.0

Someone reported an issue on Firefox 74.0 (Ubuntu):

The scroll is activated and we do not see the MeiliSearch logo anymore.

Fix security vulnerability by updating jest

Currently, the version of jest is 23.6.0 and the most recent one is v0.26.4.
This delay of version leads to security vulnerability because jest depends on jest-cli that depends on an old version of yargs that depends on an old version of yargs-parser (below v0.13.2, that is recommended to fix the vulnerability).

But updating jest leads to this error when running yarn test:

We should update jest to the latest major version.

Upgrade jest dependency

Currently, we cannot upgrade jest on this package because pass from the v23 to the v24 is breakable for our tests suite.

See #79.

If someone is ok to upgrade our tests and the jest dependency, that would be really appreciated 🙂

Autocomplete options

When passing an autocompleteOptions to the docsSearchBar function, a second input (HTML tag) is popping.
The autocompleteOptions are indeed not well passed in the autocomplete method.

Update of the URL linking to the SVG of the `Meilisearch` part appearing in `Powered by ..`

Following rebranding the Powered By MeiliSearch requires a new link to the SVG of the image. While it is not hosted on a CDN we cannot change the link.

Waiting on @qdequele to provide a link

Use Meili's logo in dropdown footer

Currently, the footer of the dropdown is a simple "Powered by MeiliSearch".
It could be cool to improve this footer with a logo.

Do not forget to link the logo to the landing page ;)

React based SDK

Are there any plans to make this based on a react with possibly some API exposed for tweaking it, so anyone can customize it as and how they want, using components based UI etc etc?

Make docs-searchbar compatible with typescript

For the moment when using docs-searchbar.js in an typescript environment, it raises an error because of a lack of declaration file. This can be prevented by providing a type file.

Better explanation on the issue here.

How to get grouped data

I have integrated Meilisearch. I scraped our markdown documentation myself. I have integrated docs-searchbar.js.
But, when I query my output is not "grouped" (like an SQL "group by")
Did I miss something in the scraping or is there something else I need to do?
My output:

But I want it to "group" like this:

my data looks like this:

  {
    "objectID": 133,
    "hierarchy_lvl0": "Contribution Guide",
    "hierarchy_lvl1": "Contribution Guide",
    "hierarchy_lvl2": "Helping to Resolve Existing Issues",
    "hierarchy_lvl3": null,
    "hierarchy_lvl4": "Testing Patches",
    "hierarchy_lvl5": null,
    "hierarchy_lvl6": null,
    "content": "You can also help out by examining pull requests that have been submitted to Quasar via GitHub. In order to apply someone's changes, you need to first create a dedicated branch: bash $ git checkout -b testing_branch Then, you can use their remote branch to update your codebase. For example, let's say the GitHub user JohnSmith has forked and pushed to a topic branch \"orange\" located at https://github.com/JohnSmith/quasar. bash $ git remote add JohnSmith https://github.com/JohnSmith/quasar.git $ git pull JohnSmith orange After applying their branch, test it out! Here are some things to think about: Does the change actually work? Does it have the proper documentation coverage? Should documentation elsewhere be updated? Do you like the implementation? Can you think of a nicer or faster way to implement a part of their change? Once you're happy that the pull request contains a good change, comment on the GitHub issue indicating your approval. Your comment should indicate that you like the change and what you like about it. Something like:  Example pull request comment I like the way you've restructured the code in card.vue - much nicer. Documentation is updated too.  If your comment simply reads \"+1\", then odds are that other reviewers aren't going to take it too seriously. Show that you took the time to review the pull request.",
    "anchor": "Testing-Patches",
    "url": "/contribution-guide/contribution-guide"
  },

As you can see, I have removed the hierarchy_radio_lvlX fields as I haven't figured out how they are to be used, so far.

Any help, suggestions, comments are welcomed. Thank you for your time and wonderful package.

Remove use of `!important` in CSS

There are !important in CSS. This is a bad practice and it would be nice to remove them.
If so, we have to be careful that it might be breaking.

Fix playground

The playground uses https://docs-search-bar.meilisearch.com that is down today. We need to update the playground to make it usable again.

docs-searchbar.js/playgrounds/javascript/src/index.js

Line 6 in a419a4a

hostUrl: 'https://docs-search-bar.meilisearch.com',

Add browser tests

Testing

With the same method used in meilisearch-js we should add a very simple test that tries out the search bar in doc-searchbar.js

How

As mvp we should add at least one test that does the following

1. Go the served webpage and check if it loads correctly
2. Using a library like puppeteer we should manipulate the DOM the following way.
   • Focus on the input
   • Change its value to a given search query, by mimicking typing behavior
   • Check for a dynamically created DOM element containing search results
   • Ensure this DOM element is not empty

Why

With these tests we check for two possible problems:

• Testing front-end webpage still works correctly, thus confirming that any fail will not come from the test itself
• Testing that DocSearchBar still works correctly when using a remote dataset that follows its requirements

MeiliSearchCommunicationError

Hey guys, I meet a problem when I use meilisearch-js.

In the old version, It works great. But yesterday, I did some refactor(nothing to do with meilisearch-js) and then, after I deployed my website, I found I can't use the search service.I've send request with masterKey. But problem is still here.

docs-searchbar.min.js:2 Uncaught (in promise) MeiliSearchCommunicationError: request to https://trantor-meilisearch.app.terminus.io/indexes/trantor/search failed, reason: connect ECONNREFUSED
    at t.<anonymous> (docs-searchbar.min.js:2:67933)
    at docs-searchbar.min.js:2:64772
    at Object.next (docs-searchbar.min.js:2:64877)
    at docs-searchbar.min.js:2:63815
    at new Promise (<anonymous>)
    at r (docs-searchbar.min.js:2:63563)
    at t.request (docs-searchbar.min.js:2:67624)
    at t.<anonymous> (docs-searchbar.min.js:2:68597)
    at docs-searchbar.min.js:2:64772
    at Object.next (docs-searchbar.min.js:2:64877)

and this is the code in my project

componentDidMount() {
  window.docsSearchBar({
    hostUrl: 'https://trantor-meilisearch.app.terminus.io/',
    apiKey: '',
    indexUid: 'trantor',
    inputSelector: '#search-input',
    meilisearchOptions: { limit: 99, matches: true }
  }, { limit: 50000 })
}

You can reproduce the problem in https://trantor-doc-test-mobile.app.terminus.io/v1.0.x/doc/quick-start/base-trantor

Project not compatible with node 16

Description
Node 16 is now the latest version of node. It is not the active version yet so we should not pro-actively solve this issue. Nonetheless the 26 octobre 2021 it will become the active version.

See node releases status

As for now, this project is not compatible with node 16 because of node-sass.

Current behavior
Node-sass v4 is not compatible with node 16. We should upgrade to v6

See related documentation

Environment (please complete the following information):

• OS: IOS
• MeiliSearch version: v.0.20.0
• docs-searchbar.js version: v1.1.11

Add a configuration to display searchbar in a modal

Description
It would be really nice to be able to display the search bar in a modal similar to the way Algolia does it. Then we could add multiple buttons on the site to trigger the search modal via events

Basic example

Add a scrolling system to see further results

Description
Search is limited to X first results.
We should be able to scroll inside the popup to see other results

Add 2021 to license year

I'll create a GitHub action for next years.

Allow the docs-searchbar to be invoked using keyboard shortcut

Description
The idea is to allow users to invoke the Meilisearch frontend search bar using a keyboard shortcut like cmd + K. A keyboard shortcut implementation to invoke the search bar is already present in the Algolia search bar and also Slack search bar and it makes it easier for users to do a search rather than have to go to the search bar in the navigation bar every time.

Basic example
The user can invoke the search by using a keyboard shortcut.
Algolia's implementation for reference:

Automatic dark/light mode toggle

As for now when the theme mode is changed on the system, docs-searchbar needs a reload to apply changes.

When adding this in the code:

@media (prefers-color-scheme: dark) { 
  div[data-ds-theme='dark'] {
    @if ($searchbox == true) {
      @include searchbox($searchbox-config-dark...);
    }
    @include dropdown($dropdown-config-dark...);
  }
}

the issue is resolved but introduces another problem. The user that integrates docs-searchbar.js might want to force data-ds-theme=dark without having the preferes-color-scheme to dark.

A solution must be find to answer all situations:

• Automatic toggling when theme is changed on system
• Forcing dark mode should be possible

Security vulnerabilities

This issue is to fix all the security vulnerabilities in the dependencies.

Make a clear explaination of what the repo does at the start of the readme

Docs-searchbar is a great tool if you know what it is. Arriving on the repo you are not met with enough explanation on what the plugin does.

Taking inspiration of instant-meilisearch an explanation should be added at the top of the repo.

Upgrade to jest v24-26 and babel to version 7

Because or Jest version is v23 we have vulnerabilities caused by yargs-parser.
We tried to fix it by using the resolutions, this introduced more problems. Also, resolutions are patches and not a solution.

linked issue: jestjs/jest#7424

This vulnerability has been fixed in jest v24>

Jest version 24 uses Babel 7:
https://jestjs.io/blog/2019/01/25/jest-24-refreshing-polished-typescript-friendly#typescript-support

But we use a previous version that is not compatible with jest v24.

To fix this problem properly we should consider upgrading jest to v24 or higher and babel to version 7.

Search multiple indexes?

It is possible to search multiple indexes at once?

Remove the node-notifier security vulnerability

We need to upgrade jest.

Bad highlighting on Chrome

function `checkArguments` only checks a few arguments

The checkArguments function receives the following parameters :

    hostUrl,
    apiKey,
    indexUid,
    inputSelector,
    debug,
    meilisearchOptions,
    queryDataCallback,
    autocompleteOptions,
    transformData,
    queryHook,
    handleSelected,
    enhancedSearchInput,
    layout

But it only checks:

• that apiKey, indexUid, and hostUrl are present
• that inputSelector is a string
• that there is an input in the page with inputSelector as CSS selector

All the other checks are missing. Maybe we should add them to have a more robust library.

Avoid having to reload the playground for it to work

When launching the playground

yarn serve

A webpage is opened that does not work until your reload the page. This should be fixed.

Remove support for node 12 and ensure support for node 18

Node version compatibilities should be changed in the tests and the readme.

See related issue.

Previous ensured compatibilities:

• Node 12
• Node 13
• Node 14

New compatibilities to ensure:

• Node 14
• Node 16
• Node 18

TODO:

• Update requirements/compatibilities in README.md.
• Update node versions tested in CI tests.

Remove warning during the build

$ yarn
[...]
$ yarn build
[...]
WARNING in configuration
The 'mode' option has not been set, webpack will fallback to 'production' for this value. Set 'mode' option to 'development' or 'production' to enable defaults for each environment.
You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/
[...]

Remove divisions inside scss as they are deprecated and will be removed in dart sass 2.0

In our styling files we are using divisions to create values for our styles, for example:

 $border-radius: $input-height / 2,

Unfortunately, this will become obsolete and should be replaced by the following

DEPRECATION WARNING: Using / for division is deprecated and will be removed in Dart Sass 2.0.0.

Recommendation: math.div($input-height, 1.6)

something is empty in search resultlist

Description

The search drop-down box does not display the content correctly.

Expected behavior

It should be like this:

Current behavior

vuepress

docs-searchbar.js

Screenshots or Logs
If applicable, add screenshots or logs to help explain your problem.

1. During the search, data was retrieved but not displayed
   

2. At first I thought it was my data problem, but I had the same problem using docs-scraper to grab docs.meilisearch.com documents.

docker code :

docker run -it --rm \
  --network=host \
  -e MEILISEARCH_HOST_URL=http://127.0.0.1:7700 \
  -e MEILISEARCH_API_KEY=zxczxc\
  -v /root/meilisearch/docs-scraper-config2.json:/docs-scraper/config.json \
  getmeili/docs-scraper:latest pipenv run ./docs_scraper config.json

config:

{
    "index_uid": "docs",
    "sitemap_urls": ["https://docs.meilisearch.com/sitemap.xml"],
    "start_urls": ["https://docs.meilisearch.com"],
    "selectors": {
      "lvl0": {
        "selector": ".sidebar-heading.open",
        "global": true,
        "default_value": "Documentation"
      },
      "lvl1": ".theme-default-content h1",
      "lvl2": ".theme-default-content h2",
      "lvl3": ".theme-default-content h3",
      "lvl4": ".theme-default-content h4",
      "lvl5": ".theme-default-content h5",
      "text": ".theme-default-content p, .theme-default-content li"
    },
    "strip_chars": " .,;:#",
    "scrap_start_urls": true,
    "custom_settings": {
      "synonyms": {
        "relevancy": ["relevant", "relevance"],
        "relevant": ["relevancy", "relevance"],
        "relevance": ["relevancy", "relevant"]
      }
    }
}

Environment (please complete the following information):

• OS: [ Linux CentOS]
• MeiliSearch version: [docker last v.0.22.0]
• docs-scraper version: [docker last 815baa3fc4fd v.0.10.5]
• docs-searchbar.js version: [v1.1.11 ~ v1.3.2]
• Browser: [Chrome version 93.0.4577.82] [Microsoft Edge 93.0.961.52]

Confirm compatibility with node 16

Description
Node 16 is now the latest version of node. It is not the active version yet so we should not proactively confirm compatibility with node 16. Nonetheless, the 26 October 2021 node 16 will become the active version and this is a reminder for that we have to guarantee compatibility.

See node releases status

Environment (please complete the following information):

• OS: IOS
• MeiliSearch version: v.0.20.0
• docs-searchbar.js version: v1.1.11

Changes after the Node.js v10 EOL (2021-04-30)

Related meilisearch/meilisearch-js#760

Node 10 is the end of life since April 2021. It becomes more and more unsupported by the libraries we use in our different JS project. Until now we had to make a workaround to keep compatibility with node 10.

As for the official EOL of node, we should also drop support for node 10 and stay up-to-date with the libraries that upgraded without node 10 support.

We need to:

• Remove the tests with node.js v10 in the CIs
• Ensure no library has been blocked to avoid losing node 10 compatibility

When the title contains Chinese, an error will be reported

Add browser tests

Testing

With the same method used in meilisearch-js we should add a very simple test that tries out the search bar in doc-searchbar.js

How

As mvp we should add at least one test that does the following

1. Go the served webpage and check if it loads correctly
2. Using a library like puppeteer we should manipulate the DOM the following way.
   • Focus on the input
   • Change its value to a given search query, by mimicking typing behavior
   • Check for a dynamically created DOM element containing search results
   • Ensure this DOM element is not empty

Why

With these tests we check for two possible problems:

• Testing front-end webpage still works correctly, thus confirming that any fail will not come from the test itself
• Testing that DocSearchBar still works correctly when using a remote dataset that follows its requirements

Usage on README

Currently, we don't know how to use docs-searchbar.js

• Add usage
• Add examples
• Add details about options that we can pass to docsSearchBar function
• Add details about how to customize the CSS

Using docs-searchbar.js library without using docs-scraper tool

Here is the question from one of our users on Slack:

Hey guys - if I want to use the awesome search bar at https://github.com/meilisearch/docs-searchbar.js but don't use the scraper (I'm pushing content via API calls), how do I address the "Object has no key lvl0" error? What metadata do I need to push?

The scraper: https://github.com/meilisearch/docs-scraper
Related tutorial: https://docs.meilisearch.com/resources/howtos/search_bar_for_docs.html

Cypress tests should not work with a remote MeiliSearch instance

Maybe I'm wrong and the Cypress tests are not working with a remote MeiliSearch instance, but it looks like they are using the https://docs-search-bar.meiliseasrch.com instance, which is not recommended. This remote instance is indeed the MeiliSearch instance used by the documentation to provide a search bar. It's not an easy task to upgrade this instance since it's very impactful for the users of the docs. Our CI should definitely not rely on this instance.

Plus, it's not convenient at all to update a remote instance to make CI tests work. A CI should be as independent as possible.
We should download locally (in the CI) a MeiliSearch that will be used for the cypress tests 🙂