Icarus User Guide - Search Plugin

This article covers search plugin configurations supported by Icarus.

This article is also available in 简体中文.

The following search plugins are provided by ppoffice/hexo-component-inferno. Please refer to it for a complete list of supported plugins and their configuration details.

Visitors open the search box by clicking the search button on the navigation bar. Except for Baidu Search, the search box can also be opened with the keyboard and closed with Esc. See Keyboard Shortcuts for details.

Algolia

Installation GuidePreview

1. Install the hexo-algolia plugin under the root directory of your Hexo site.

2. Register and log into Algolia. Click the “Create Index” button on the dashboard when you log in for the first time. Then, enter the name of the index and click the “Create” button to complete index creation.

   
   

3. Next, click “API Keys” on the left navigation bar, copy “Application ID” and “Search-Only API Key” on the page. Open site configuration file _config.yml under the root directory of your Hexo site and fill in the above information to the hexo-algolia plugin configurations.

   
   

   For example, the following Algolia index information:

   Algolia Index Information

   Algolia Index Name: My-Hexo-Site
   Application ID: ABCDEFGHIJKL
   Search-Only API Key: 7b08fca7d42412cee901a25643124221

   maps to the following plugin configuration:

   _config.yml

   algolia:
       applicationID: ABCDEFGHIJKL
       indexName: My-Hexo-Site
       apiKey: 7b08fca7d42412cee901a25643124221

4. Go back to the “API Keys” page from the Algolia dashboard and switch to the “All API Keys” tab. Click the “New API Key” button. On the popup “Create API Key” dialog, select the index you created in step 2 in the “Indices” select box. Then, add addObject, deleteObject, listIndexes, deleteIndex to the “ACL” field. Click the “Create” button to finish key creation. Copy the API key you just created, e.g., 727fbd8c998fe419318fa350db6793ca.

   
   

5. Open a Windows Command Prompt (CMD) or Linux/macOS terminal and change the working directory to the root directory of your Hexo site. Set the HEXO_ALGOLIA_INDEXING_KEY environment variable to the API key you created in the last step. This variable is used by hexo-algolia when uploading indices to Algolia.

   On Windows:

   Windows Command Prompt (CMD)

   C:\Users\you> cd path/to/your/hexo/site
   C:\Users\you> set HEXO_ALGOLIA_INDEXING_KEY=727fbd8c998fe419318fa350db6793ca

   On Linux/macOS:

   Linux/macOS Terminal

   $ cd path/to/your/hexo/site
   $ export HEXO_ALGOLIA_INDEXING_KEY="727fbd8c998fe419318fa350db6793ca"

   Then, run the following commands to clean up your site and upload indices to Algolia:

   Windows Command Prompt or Linux/macOS Terminal

   $ hexo clean
   $ hexo algolia

6. Finally, set the search engine to Algolia in your theme configurations:

   _config.icarus.yml

   search:
       type: algolia
       excerpt: excerpt        # Optional. Defaults to `excerpt`

   excerpt is the name of the attribute of your Algolia records that is shown as the preview text of each search result. Set it if your records keep the text of the posts in another attribute. The search results show the title and the preview text as plain text with the matched words highlighted: since hexo-component-inferno 4.2.0, HTML tags in the preview text are removed, and other HTML in the records is escaped instead of being rendered.

Baidu Search

Installation Guide

1. Open theme configuration file and set search engine to Baidu:

   _config.icarus.yml

   search:
       type: baidu

   Baidu Search sends visitors to the Baidu website to search your site, which is limited to the domain in the url setting of your site configuration file _config.yml. Make sure url is the address of your site. The search box of Baidu Search has no keyboard shortcuts.

Google Custom Search Engine (CSE)

Google now seems to call this service Programmable Search Engine, so its pages may look different from the screenshots below.

Installation GuidePreview

1. Log into your Google account and visit Google CSE to create a CSE. Type in the URL of your site (without http:// or https://) in the “Sites to Search” field. Select the correct language from the “Language” select box. Then, fill in the “Name of the search engine”. Click the “Create” button to finish engine creation.

   
   

2. Then, click the “Get code” button on the right side of “Add it to your site”. Copy the value of cx to the search settings in your theme’s configurations.

   
   

   For example, the following HTML code:

   Google CSE HTML code

   <script async src="https://cse.google.com/cse.js?cx=012345601234560123456:abcdefghijklmn"></script>
   <div class="gcse-search"></div>

   maps to the following theme configuration:

   _config.icarus.yml

   search:
       type: google_cse
       cx: 012345601234560123456:abcdefghijklmn

Insight

Installation Guide

1. Insight is the default search engine of this site. You can enable it using the following theme configuration:

   _config.icarus.yml

   search:
       type: insight
       index_pages: true       # Optional. Defaults to `true`. Set to `false` to exclude pages from search results.

2. Insight does not need any external service. When you generate your site, it saves the text of your posts, pages, categories, and tags to a content.json file, which the search box downloads and searches in the browser. Since hexo-component-inferno 4.2.0, the keywords are matched as plain text instead of regular expressions, and the search results are escaped and shown as plain text. You can also use ↑ and ↓ to select a search result and Enter to open it.

Keyboard Shortcuts

Except for Baidu Search, all search plugins above support the following keyboard shortcuts:

• / opens the search box, unless you are typing in an input field, a text area, or other editable content.
• Ctrl + K (⌘ Command + K on macOS) opens the search box, even when you are typing.
• Esc closes the search box, and the focus returns to where it was before the search box opened.

Focusing the search button on the navigation bar, for example with Tab, does not open the search box. Press Enter or Space on it, or click it, instead. Moving the focus out of the open search box, for example with Tab, closes it.

Something wrong with this article? Click here to submit your revision.