Global Search Feature Overview

The purpose of global search feature is to provide users the ability to search solution contents, such as tutorials, blogs, installation guides etc.. This new feature is available across all main information pages on website version 1.6+. Users can search for contents in any versions of website by selecting the target search version.

Implementation

The global search feature is implemented based on a 3rd party library named DocSearch, which handles all the backend jobs including crawling the website and generating indices, performing search and displaying the results. You can learn about how DocSearch works from this link how Does DocSearch Works. To integrate such service into MXNet website, a search UI for collecting user input is implemented and connected to DocSearch via provided JavaScript API.

Here is a list of added/modified files:

  • M docs/static_site/src/_includes/head.htm - added new tags for loading JavaScript and stylesheet from DocSearch

  • M docs/static_site/src/_includes/header.html - added Search UI with version dropdown for both wide and narrow screen

  • M docs/static_site/src/assets/main.scss - import globalSearch.scss

  • M docs/static_site/src/_sass/minima/_layout.scss - add adaptive css styles based on media query

  • M docs/static_site/src/_config_prod.yml - add an array to generate the search bar version dropdown
  • M docs/static_site/src/_config.yml - add an array to generate the search bar version dropdown
  • M docs/static_site/src/_config_beta.yml - add an array to generate the search bar version dropdown

  • Add docs/static_site/src/assets/img/search-icon.svg - the search icon

  • Add docs/static_site/src/assets/js/globalSearch.js - connect <input> to DocSearch, add listener, UI animation

  • Add docs/static_site/src/_sass/globalSearch.scss - all UI related styles, including search bar and result panel

Search UI

The global search UI is styled appropriately for both wide and narrow screens across all popular browsers. On a wider screen the UI is displayed as an icon at the rightmost top navigation bar. And when triggered by clicking on the icon, the navigation bar will disappear and the search bar expends to its full length. On a narrow screen, the search UI is inside the dropdown navigation bar. The search result will update as you type, and keyboard navigation is also enabled.

DocSearch Config

Apart from adding search UI to front end, we also need to maintain a config file in DocSearch-config GitHub repo. This is the configuration file DocSearch use on its web crawler to extract data from MXNet website which has direct impact on the quality of search result. Here is the link to MXNet website config from DocSearch. To update this config, submit a PR to this repo listed below with information about the change and your identity. DocSearch team will review the PR and then deploy the change. Please note that DocSearch team will not verify the config change, so testing your config locally is recommended before submitting the PR. To test your config, you need to create an Algolia account and run the web crawler locally or on an EC2 instance. Configure your local web crawler to send data to your account by applying your Algolia API key, for detailed process please follow this link: run your own web crawler. It normally takes one day for the changes to reflect on the search result, because DocSearch team run the web crawler every 24 hours. For detailed rules about the best practice of the configuration, please see custom JSON configuration file.

Analytics Dashboard

DocSearch grants us limited access to Algolia analytics dashboard for MXNet website, there are statistics about the search feature, including 'popular search', 'number of users' and 'no result rate' etc. If you need access to this dashboard, please reach out to yangshia@amazon.com. 

Global search on v1.6 website

Because v1.6 website is stored as static artifacts, to make minimum changes to each html files and ensure maintainability, all global search logics are combined into one JavaScript file named 'globalSearch.js'. It contains the logic of loading related css, js, and inject search UI to the navbar.


  • No labels