Add Algolia plugin (#718)

docs/userGuide/makingTheSiteSearchable.md

@@ -23,13 +23,20 @@
 
 **All headings of levels 1-3 are captured in the search index** by default. You can change this setting using the [`headingIndexLevel` property of the `site.json`]({{ baseUrl }}/userGuide/siteConfiguration.html#headingindexinglevel).
 
-<include src="syntax/searchBars.mbdf" />
-<include src="syntax/keywords.mbdf" />
+<box type="info">
+
+MarkBind also provides a plugin for Algolia DocSearch, which provides full text search for your site.
+
+See: [User Guide: Using Plugins → Algolia: Enabling Algolia DocSearch]({{ baseUrl }}/userGuide/usingPlugins.html#algolia-enabling-algolia-docsearch).
+</box>
 
 <box type="warning">
 
 If you do not wish to use MarkBind's searchbar (e.g. you have an external service provider), it may be helpful to include the option `enableSearch: false` in your `site.json`. This stops MarkBind from indexing search headings and speeds up building.
 </box>
 
+<include src="syntax/searchBars.mbdf" />
+<include src="syntax/keywords.mbdf" />
+
 {% from "njk/common.njk" import previous_next %}
 {{ previous_next('reusingContents', 'deployingTheSite') }}

docs/userGuide/plugins/algolia.mbdf

@@ -0,0 +1,42 @@
+#### `algolia`: Enabling Algolia DocSearch
+
+This plugin allows you to use [Algolia DocSearch](https://community.algolia.com/docsearch/) for your site.
+
+To enable it, add `algolia` to your site's plugins, and supply the required options via the `pluginsContext`.  
+
+Name | Type | Default | Description
+---- | ---- | ------- | ------
+apiKey | `String` || The API key for your site's Algolia DocSearch setup
+indexName | `String` || The index name for your site's Algolia DocSearch setup
+algoliaOptions | `Object` | `{}` | A JSON object specifying [additional options for DocSearch](https://community.algolia.com/docsearch/behavior.html#algoliaoptions)
+debug | `Boolean` | `false` | Whether to turn on debug mode to allow inspection of CSS styles for the dropdown
+
+```js
+site.json
+{
+  ...
+  "plugins": [
+    "algolia"
+  ],
+  "pluginsContext": {
+    "algolia": {
+      "apiKey": "25626fae796133dc1e734c6bcaaeac3c", // replace with your site's api key
+      "indexName": "docsearch", // replace with your site's index name
+      "algoliaOptions": { "hitsPerPage": 10 }, // optional
+      "debug": false // optional
+    }
+  }
+}
+```
+
+To connect the `searchbar` component to Algolia DocSearch, add the `algolia` key.
+
+```html
+<searchbar placeholder="Search" algolia menu-align-right>
+```
+
+Alternatively, if you are using a custom search bar, you can assign the input field the id `algolia-search-input` to connect it to Algolia DocSearch.
+
+```html
+<input id="algolia-search-input">
+```

docs/userGuide/syntax/searchBars.mbdf

@@ -33,6 +33,7 @@ Enter a search term (eg. 'search bar') to see the search result dropdown.
 
 Name | Type | Default | Description
 ---- | ---- | ------- | ------
+algolia | `Boolean` | `false` | Whether the searchbar should be connected to [Algolia DocSearch]({{ baseUrl }}/userGuide/usingPlugins.html#algolia-enabling-algolia-docsearch).
 data | `Array` || The local data source for suggestions. Expected to be a primitive array. To use MarkBind's search functionality, set this value to `"searchData"`.
 menu-align-right | `Boolean` | `false` | Whether the search bar's dropdown list will be right-aligned.
 on-hit | `Function` || A callback function when you click or hit return on an item. To use MarkBind's search functionality, set this value to `"searchCallback"`.
@@ -48,6 +49,8 @@ See: [User Guide: Site Configuration → enableSearch]({{ baseUrl }}/userGuide/s
 
 %%{{ icon_info }} Related topic: [User Guide: Making the Site Searchable]({{ baseUrl }}/userGuide/makingTheSiteSearchable.html).%%
 
+%%{{ icon_info }} Related topic: [User Guide: Using Plugins → Algolia: Enabling Algolia DocSearch]({{ baseUrl }}/userGuide/usingPlugins.html#algolia-enabling-algolia-docsearch).%%
+
 <span id="short" class="d-none">
 
 ```html

docs/userGuide/usingPlugins.md

@@ -151,6 +151,7 @@ This will add the following link and script elements to the page:
 MarkBind has a set of built-in plugins that can be used immediately without installation.
 
 <include src="plugins/filterTags.mbdf" />
+<include src="plugins/algolia.mbdf" />
 
 {% from "njk/common.njk" import previous_next %}
 {{ previous_next('usingHtmlJavaScriptCss', 'tweakingThePageStructure') }}

src/plugins/algolia.js

@@ -0,0 +1,24 @@
+const ALGOLIA_CSS_URL = 'https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css';
+const ALGOLIA_JS_URL = 'https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js';
+const ALGOLIA_INPUT_SELECTOR = '#algolia-search-input';
+
+function buildAlgoliaInitScript(pluginContext) {
+  return `<script>
+    function initAlgolia() {
+      docsearch({
+        apiKey: "${pluginContext.apiKey}",
+        indexName: "${pluginContext.indexName}",
+        inputSelector: "${ALGOLIA_INPUT_SELECTOR}",
+        algoliaOptions: ${JSON.stringify(pluginContext.algoliaOptions || {})},
+        debug: ${pluginContext.debug || false},
+      });
+    }
+    MarkBind.afterSetup(initAlgolia);
+  </script>`;
+}
+
+module.exports = {
+  getLinks: (content, pluginContext, frontMatter, utils) => [utils.buildStylesheet(ALGOLIA_CSS_URL)],
+  getScripts: (content, pluginContext, frontMatter, utils) =>
+    [utils.buildScript(ALGOLIA_JS_URL), buildAlgoliaInitScript(pluginContext)],
+};