From 513031ae6469c75e4dc8010fce125e39f0777946 Mon Sep 17 00:00:00 2001 From: Marvin Chin Date: Sun, 3 Mar 2019 23:49:56 +0800 Subject: [PATCH] Add Algolia plugin (#718) --- docs/userGuide/makingTheSiteSearchable.md | 11 ++++-- docs/userGuide/plugins/algolia.mbdf | 42 +++++++++++++++++++++++ docs/userGuide/syntax/searchBars.mbdf | 3 ++ docs/userGuide/usingPlugins.md | 1 + src/plugins/algolia.js | 24 +++++++++++++ 5 files changed, 79 insertions(+), 2 deletions(-) create mode 100644 docs/userGuide/plugins/algolia.mbdf create mode 100644 src/plugins/algolia.js diff --git a/docs/userGuide/makingTheSiteSearchable.md b/docs/userGuide/makingTheSiteSearchable.md index 89326f3712..e7ed75591b 100644 --- a/docs/userGuide/makingTheSiteSearchable.md +++ b/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). - - + + +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). + 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. + + + {% from "njk/common.njk" import previous_next %} {{ previous_next('reusingContents', 'deployingTheSite') }} diff --git a/docs/userGuide/plugins/algolia.mbdf b/docs/userGuide/plugins/algolia.mbdf new file mode 100644 index 0000000000..13eb4e7547 --- /dev/null +++ b/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 + +``` + +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 + +``` diff --git a/docs/userGuide/syntax/searchBars.mbdf b/docs/userGuide/syntax/searchBars.mbdf index 6818489443..0c2fd58d61 100644 --- a/docs/userGuide/syntax/searchBars.mbdf +++ b/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).%% + ```html diff --git a/docs/userGuide/usingPlugins.md b/docs/userGuide/usingPlugins.md index 335a5c5420..9b544a6d54 100644 --- a/docs/userGuide/usingPlugins.md +++ b/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. + {% from "njk/common.njk" import previous_next %} {{ previous_next('usingHtmlJavaScriptCss', 'tweakingThePageStructure') }} diff --git a/src/plugins/algolia.js b/src/plugins/algolia.js new file mode 100644 index 0000000000..c5a85ff74e --- /dev/null +++ b/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 ``; +} + +module.exports = { + getLinks: (content, pluginContext, frontMatter, utils) => [utils.buildStylesheet(ALGOLIA_CSS_URL)], + getScripts: (content, pluginContext, frontMatter, utils) => + [utils.buildScript(ALGOLIA_JS_URL), buildAlgoliaInitScript(pluginContext)], +};