algolia / docsearch

:blue_book: The easiest way to add search to your documentation.

The easiest way to add search to your documentation – for free.

Documentation • JavaScript Playground • React Playground

---

DocSearch crawls your documentation, pushes the content to an Algolia index and provides a dropdown search experience on your website.

Preview

Light	Dark

Usage

Don't have your Algolia credentials yet? Apply to DocSearch!

JavaScript

Installation

yarn add @docsearch/js@3
# or
npm install @docsearch/js@3

If you don’t want to use a package manager, you can use a standalone endpoint:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>

Get started

To get started, you need a container for your DocSearch component to go in. If you don’t have one already, you can insert one into your markup:

<div id="docsearch"></div>

Then, insert DocSearch into it by calling the docsearch function and providing the container. It can be a CSS selector or an Element.

Make sure to provide a container (for example, a div), not an input. DocSearch generates a fully accessible search box for you.

import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});

React

Installation

yarn add @docsearch/react@3
# or
npm install @docsearch/react@3

If you don’t want to use a package manager, you can use a standalone endpoint:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@3"></script>

Get started

DocSearch generates a fully accessible search box for you.

import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indexName="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;

Styling

Read documentation →

Related projects

DocSearch is made of the following repositories:

• algolia/docsearch: DocSearch source code.
• algolia/docsearch/packages/website: DocSearch website and documentation.
• algolia/docsearch-configs: DocSearch websites configurations that DocSearch powers.
• algolia/docsearch-scraper: DocSearch crawler that extracts data from your documentation.

License

MIT

docsearch's Issues

Remove the "generated with DocToc" from the readme

Here is the actual TOC:

We should remove the "generated with DocToc"

update to latest autocomplete.js

To allow overriding default css classes

Analytics / usage metrics?

What's the best way to know what queries users are looking for the most, and where they landed depending on their search?

npm package installation fails on Windows

Due to the fact npm-zepto has an install script that fails on Windows.

npm WARN optional Skipping failed optional dependency /chokidar/fsevents:
npm WARN notsup Not compatible with your operating system or architecture: [email protected]
npm WARN optional Skipping failed optional dependency /browser-sync/chokidar/fsevents:
npm WARN notsup Not compatible with your operating system or architecture: [email protected]
npm WARN [email protected] requires a peer of angular@< 2 but none was installed.
npm WARN [email protected] requires a peer of jquery@>= 1.7 but none was installed.
npm ERR! Windows_NT 6.1.7601
npm ERR! argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install"
npm ERR! node v6.2.2
npm ERR! npm  v3.9.5
npm ERR! code ELIFECYCLE

npm ERR! [email protected] install: `script/build`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] install script 'script/build'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the npm-zepto package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     script/build
npm ERR! You can get information on how to open an issue for this project with:
npm ERR!     npm bugs npm-zepto
npm ERR! Or if that isn't available, you can get their info via:
npm ERR!     npm owner ls npm-zepto
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR!     C:\Users\IEUser\design-system-internal\npm-debug.log

Search Result only showing one title

My search results only show one webpage title, if at all. I am using the stock CSS and js files but I can not get it to look like your example.

Could it be a bug with the docsearch-scraper not indexing the page title as well? What do you need to help trouble shoot?

how to set target="_blank" on search result links

I'd like to make the links in the widget open in a new tab.

Is there a blessed path to modify the markup of the search results template so I can add target="_blank" to the links returned by a search?

Deploy the website to gh-pages

In order to synchronize it with https://community.algolia.com/documentation-search/

Uncaught (in promise) Error: [groupBy]: Object has no key

I am trying to use docsearch with an index I have on algolia (i.e. not crawled by algolia). However, I am getting a Uncaught (in promise) Error: [groupBy]: Object has no key error in my console.

I tried setting the Attribute for distinct to one of my attributes (page ID) and tried setting Distinct to true and the numerical values, but I still get the groupBy error.

I see some references to properties named lvl0, lvl1 ... lvl6. Are these automatically generated or do I have to add these properties to my index?

Cannot use links in the generated documentation

The documentation page displayed on the website is created from the README, by splitting it on specific patterns.

Unfortunatly, when defining links with a syntax of [my link][42], the reference to [42] is defined at the end of the file, and stripped from the extraction.

@jerskouille do you have an idea on how to hack the build-docs script to do that?

Cmd+F / Ctrl+F keybinding

Would be great to jump directly to DocSearch using the default search key combinations.

How often does the crawler run?

With a new release of our site that (soon) uses DocSearch coming up soon, we're going to introduce information architecture changes. Some pages will inevitably 404 and I was wondering how long it would take the DocSearch crawler to re-index the new site architecture.

Search results showing up "behind" other div

I added the search input to a template that has a navbar setup. When I use the search, the results a cut off because its being rendered behind another element. I cant for the life of me figure out how to change the z-index of the search box to send it to the front. Is there any way that I can do that?

This is the template I am using with couscous.io: https://github.com/CouscousPHP/Template-ReadTheDocs

Any help would be wonderful.

Override the APP_ID

We should be able to override the APP_ID. Right now it is not possible => https://github.com/algolia/docsearch/blob/master/src/lib/DocSearch.js#L41

Set lighter default grayscale colors

The current default colors are too dark and aggressive.
https://github.com/algolia/docsearch.js/blob/develop/src/styles/_variables.scss

cc @Shipow

Remove the url+anchor concatenation

There is something confusing with the way we store the url and anchor.

The scraper index both a anchor field and a url one, but the url already contains the anchor. We do that because we're doing a distinct on the url. But the JS client also concatenate the url and anchor, which results in weird things.

I think we should:

• Remove the anchor field from the scraper
• Remove the concatenation from the JS client

Questions about the service

I am hoping someone here can help answer some questions for me. I really like docsearch and would like to include it in our documentation, but I cant seem to find anything covering the following questions:

1. Can it securely connect to a different git enterprise? My company has our own github enterprise and thats where our documentation will be stored.
2. Would our data encrypted on the backend? Security is a major thing for us, and a lot of our documentation would be internal facing.
3. If 1 & 2 cant be done, is there a on prem solution?

Thanks for taking the time to help me out.

Image missing in the doc

Add opengraph & twitter metas

Docsearch Integration with Community Algolia is buggy.

At page https://community.algolia.com/instantsearch.js/ doing a search would yield 404 Page not found!
Screenshots attached.

Can it crawl a single page application?

I am transitioning form static-site to a single page app using polymer-project, do you think Algolia can crawl that website?

Click on a suggestion doesn't work

Throws a Cannot read property 'setVal' of undefined.

Bug in Chrome: fonts don't show

Steps to reproduce:

1. Go to https://www.lightningdesignsystem.com/components/badges/
2. Perform a search
3. Part of the text simply doesn't show

I'm blaming Chrome, but I wonder if you had any idea where that could come from and if there was a fix.

Explain how to customize the colors

By providing a CSS snippet in the documentation to match the ESLint colors for instance.

Search results not formatting well.

I am using docsearch scrapper to write my indexs, but for the search side I can not get it to format correctly. When I use the example, all of the results are listed with only the width of my search box. Its totally un-readable.

css and javascript is not my realm of knowledge, so I am sure I am missing something.

Here is my javascript:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css" />
<script type="text/javascript" src="js/docsearch.min.js"></script>
        <script type="text/javascript">
          docsearch({
                    apiKey: '27d0176XXXXXXXX,
                    indexName: 'git_hub_pages',
                    inputSelector: '#search-input'
                });

        </script>

My search box looks like this:

<div class="navbar-form navbar-left hidden-xs hidden-sm">
                      <input id="search-input" type="text" class="form-control" placeholder="Search...">
                  </div>

Let me know if you need more info or have a idea to try. Thanks!

Display a no result message, when there is no result.

For now when there is no result found for the typed search query, it just hides the dropdown.
Since that dropdown displays the search results and not only "search suggestions", it would be great to inform the user that there is not result matching its query.

utmz

The library should automatically add the right utmz links when a click on powered by is done:

• source: docsearch
• campaign name: poweredby
• ad content: domain name

Class name ".searchbox" is too generic

Currently the generated styles use a .searchbox class name. This is very generic and can (does, actually) lead to conflicts with existing styles.

Would it be possible to namespace it ? For instance, .docsearch-searchbox.

Does nothing if inputSelector finds 2 or more tags

If there is in the page 2 or more selectors that matches inputSelector it does nothing.

UI improvement of the "used by" homepage's section

A suggestion of UI that improves the way how "popular website using DocSearch" are featured.

Additionally to the new layout, I suggest we should also update the wording.

JS and website release process

Be able to npm run release much like instantsearch.js

Docsearch ends up using my jQuery

Rename CSS classes to not use `ads-` prefix

ads stands for Algolia DocSearch, but it is blocked by ad blockers (tested with µBlock). We will have to rename our classes to use something else.

The isSubCategoryHeader flag is not taken into account

As a result, it always displays the left column content.

Add a option to override handleSelected

utils.groupBy should be case-insensitive

On some websites, the categories on which we're grouping on don't share the same case. For the grouping, it makes a lot of sense to actually consider the lowercase form only.

Road to self-serve

With the team we decided to improve the design of DocSearch and how can let you customize the UI in an easy way. This redesign will include:

• New design of the dropdown
• Dropdown configurator

Idea

This configurator will give you the ability for to customize the design of the dropdown on top of your website without having a developed sense of design or doing some CSS. We know, only a very small pourcentage of our users are going beyond what we provide by default (Exception example: Apiary). We'll let advanced users editing their code by using Jsfiddle and/or opening files export.

Where are we in this process and what will be next steps?

• Define current issues
• Understand and analyze the needs
• Explore different layouts [WIP]
• Build Generator UI [WIP]
• Define dropdown layouts [WIP]
• Create category icons
• Create breadcrumb icons
• Collect feedback
• Define generator rules
• more coming...

---

[WIP] Generator UI

Allow to override empty template

Add a tweet/share button

docsearch dropdown width

Update the list of live implementations

Now that DocSearch is live, we might update the list of live implementations with a more relevant one.

From the top of my head I can list React Native and Marionnette. Any other comes to mind?

Pressing enter in search box only refreshes current page

What's happening

When typing something in the search (for example at vuejs.org/guide/), a dropdown of results appear. I can click on items listed in the dropdown, but if I press Enter, the dropdown disappears and the page is refreshed.

What I expect to happen

When pressing Enter, it would make sense to me if the top result in the search were navigated to, instead of refreshing the current page. If there's no top result, nothing should happen.

docsearch or docSearch

our <script> build is exposing docsearch() and npm is exposing docSearch. (currently the documentation wrongly uses docSearch)

Add a nice header to the readme

Along the lines of what we did for instantsearch

• Logo
• One line explanation
• Link to the website
• Badges

Re-import existing implementations?

Most of our example implementation are using the Jekyll plugin + custom autocomplete.js code. Should we move them to documentationsearch.js?

Default hitsPerPage not applied if algoliaOptions are specified

As soon as you specify some algoliaOptions, we lose the default hitsPerPage value. Would be better to keep that value as a default.

Grouping by lvl1 doesn't work if you don't have any

We should fallback on lvl0 if lvl1 is blank, otherwise the grouping is not matching what we're doing at display time.

docsearch css classes conflict with autocomplete.js

We currently have all the autocomplete.js css classes added by default (aa-*), thus if you have both docsearch on a website and autocomplete.js you may have css conflicts when trying to style things.

It depends on how you write css to style docsearch but if you style it like we did for example in our headers or our websites: using aa-* css classes then other autocomplete.js menus will inherit from the same style.

To avoid this situations we could use the new cssClasses option of autocomplete.js: https://github.com/algolia/autocomplete.js#options.

This is what is done on Algolia Places for instance: https://github.com/algolia/places/blob/master/src/places.js#L67 we change the default prefix, thus we avoid any conflicting CSS class name if other autocomplete.js menus are present.

What do you think?

How should we handle responsive breakpoints?

Taking eslint as an example, here is how we currently handle the various screen sizes:

Simple dropdown with only the heading displayed

Same dropdown, but we have enough space to also add a snippet

More space, we can add a secondary column and let the content breathe

Same as before, but the search input is just a part of the header, it no longer takes all the available space

I think this is a very important feature, that we should keep in our implementations. But I fail to see how we can do that in a generic way (ie. works for every design), or how to easily let users tweak it.

Here are the main problems:

• It is, in essence, really bound to the breakpoints defined in the parent layout (depending on the number of elements in the main menu, not all websites will change the display at the same breakpoints).
• The dropdown being position:absolute, all left/right/top/width values are dependent on the parent markup
• All the CSS code is thought as mobile-first. We set default styles for small mobile screens and only add more columns as the page width increases.
• I cannot simply add left: -20px, right: -20px for small screens and left: 0, max-width: 430px for bigger screen, this will make no sense for some layout.

If you have any ideas to solve the issues, or just comments on how, as users you would expect this to work, please, shoot.

cc @redox @vvo @ElPicador @bobylito @proudlygeek @alexandremeunier @Shipow @dustincoates @kokliKo @jerskouille

How to supply custom appID?

I am trying to use docsearch with an index I have uploaded to algolia (i.e. not having algolia crawl my site since it is only hosted locally at the moment).

This is the JS I am using:

<script type="text/javascript">
docsearch({
  apiKey: 'my API key',
  indexName: 'my index name',
  inputSelector: '#search-input',
  appID: 'my appID',
  debug: true
});
</script>

My apiKey, indexName and appID work using autocomplete.js. I saw that this should work according to the closed issue #31.

What am I doing wrong?

Build the actual JS/CSS library

The goal is to build a small JS/CSS library on top of autocomplete.js that displays the auto-completion menu we've done on various websites (including https://bootstrap.algolia.com/, http://eslint.org/, https://reactjs.algolia.com/, https://babeljs.algolia.com/, ...).