Merge branch 'develop' into docs/calendar-widget

docgen/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing
+
+This guide explains how the documentation process works for InstantSearch.js.
+
+## Frontmatter
+
+The frontmatter of your [Markdown](https://en.wikipedia.org/wiki/Markdown) page describes the metadata that will be generated at compile time.
+
+We offer several attributes that allow to customize the rendering of your documentation or guide. You don't need to specify the ones that default to a value ([see example](#example)).
+
+### Attributes
+
+#### `title`
+
+> `string` | no default
+
+The title of your page.
+
+#### `mainTitle`
+
+> `string` | no default
+
+The name of the category of your page.
+
+#### `layout`
+
+> `string` | no default
+
+The layout of your page among [`docgen/layouts/`](layouts/) (i.e. [`main.pug`](layouts/main.pug)).
+
+#### `category`
+
+> `string` | no default
+
+The category of your page.
+
+#### `name`
+
+> `string` | no default
+
+The name to use for the file name of the [URL](https://en.wikipedia.org/wiki/URL).
+
+#### `withHeadings`
+
+> `boolean` | defaults to `false`
+
+`true` if the page should contain headings, `false` otherwise.
+
+#### `navWeight`
+
+> `number` | no default
+
+The number that describes the order of the page in the menu.
+
+#### `editable`
+
+> `boolean` | defaults to `false`
+
+`true` if you want to display the "Edit this page" link, `false` otherwise.
+
+#### `githubSource`
+
+> `string` | no default
+
+If the page is `editable`, link to its source on GitHub for the "Edit this page" link.
+
+#### `appId`
+
+> `string` | defaults to `latency`
+
+The Algolia application ID to run the code samples on.
+
+#### `apiKey`
+
+> `string` | defaults to `6be0576ff61c053d5f9a3225e2a90f76`
+
+The API key of the app to run the code samples on.
+
+#### `index`
+
+> `string` | defaults to `instant_search`
+
+The index name of the app to run the code samples on.
+
+### Example
+
+```markdown
+---
+title: Introduction
+mainTitle: Widgets
+layout: widget-showcase.pug
+category: widgets
+withHeadings: true
+navWeight: 100
+editable: true
+githubSource: docgen/src/widgets.md
+---
+
+The start of your page...
+```

docgen/assets/js/bindRunExamples.js

@@ -9,7 +9,8 @@ window.search = instantsearch({
   urlSync: false,
   searchParameters: {
     hitsPerPage: 3
-  }
+  },
+  ...window.searchConfig
 });
 
 const el = html => {

docgen/middlewares.js

@@ -3,6 +3,7 @@ import layouts from 'metalsmith-layouts';
 import msWebpack from 'ms-webpack';
 import navigation from 'metalsmith-navigation';
 import nav from './plugins/navigation.js';
+import searchConfig from './plugins/searchConfig.js';
 import sass from 'metalsmith-sass';
 import inPlace from 'metalsmith-in-place';
 import copy from 'metalsmith-copy';
@@ -42,6 +43,7 @@ const common = [
     source: '../dist',
     destination: './examples/tourism',
   }),
+  searchConfig(),
   ignore(fileName => {
     // This is a fix for VIM swp files inside src/,
     // We could also configure VIM to store swp files somewhere else

docgen/plugins/searchConfig.js

@@ -0,0 +1,26 @@
+import {forEach} from 'lodash';
+
+// Injects search config from the frontmatter Markdown page to the `window` object.
+// This allows to run code snippets in any Algolia index.
+export default function() {
+  return function(files, metalsmith, done) {
+    forEach(files, (data, path) => {
+      const {appId, apiKey, indexName} = data;
+
+      if (appId || apiKey || indexName) {
+        data.contents =
+          data.contents +
+          `<script>
+            window.searchConfig = {
+              ${appId ? `appId: '${appId}',` : ''}
+              ${apiKey ? `apiKey: '${apiKey}',` : ''}
+              ${indexName ? `indexName: '${indexName}',` : ''}
+            };
+          </script>`
+          .replace(/\s/g, '');
+      }
+    });
+
+    done();
+  };
+}