Merge pull request #95 from webdoc-labs/feature/search

Feature: Algolia search integration and final polishes

Author: ShukantPal

packages/webdoc-cli/README.md

@@ -65,3 +65,55 @@ The `docs` object has options to configure the generation of the document tree.
   * `"scope"`: Order by scope as follows: static, instance, inner.
   * `"access"`: Order by access as follows: public, protected, private.
   * `"name"`: Order alphabetically by the simple-name.
+
+### opts
+
+The `opts` object has additional CLI options.
+
+```json
+{
+  "opts": {
+    "destination": "docs",
+    "export": "api.json",
+    "template": "@webdoc/default-template"
+  }
+}
+```
+
+* `opts.destination`: (optional) The destination path for the generated documentation files.
+* `opts.export`: (optional) The file where the API schema is exported.
+* `opts.template`: (optional) The template package to use. This defaults to "@webdoc/default-template".
+
+#### template
+
+The `template` object is used by the site template.
+
+```json
+{
+  "applicationName": "{ <i>webdoc</i> }",
+  "meta": {
+    "og:title": "webdoc",
+    "og:description": "webdoc API documentation",
+    "og:image": "https://camo.githubusercontent.com/1427d2fdabd8790c93ca05cbfb653e2c6a8ab5694e671a04aa3af3fcef313539/68747470733a2f2f692e6962622e636f2f5a4850395044382f4c6f676f2d4672616d652d352e706e67",
+    "og:url": "{{url}}",
+    "og:site_name": "webdoclabs.com"
+  },
+  "repository": "http://github.com/webdoc-labs/webdoc",
+  "integrations": {
+    "search": {
+      "provider": "algolia",
+      "apiKey": "kadlfj232983lkqwem",
+      "indexName": "webdoc-example",
+      "appId": "349o39841;akdsfu"
+    }
+  }
+}
+```
+
+* `template.applicationName`: The name of the documented software. This is usually used to fill the app bar and tab title.
+* `template.meta`: (optional) This can be used to define the `<meta>` key-value tags. The `{{url}}` variable can be used
+  to put in the site URL for each page (you have to provide the `siteDomain` and `siteRoot`).
+* `template.repository`: (optional) This can be used to link documents to their location in the source code. The only supported repository is GitHub.
+* `template.integrations`: (optional) Integrations with 3rd party solutions in your template. This object is dependent on which template you're using. For @webdoc/default-template, the following integrations are available:
+  * `search`: This is used as the backend for the global site search. You'll need to create an Algolia account yourself and provide
+    the `apiKey`, `appId`, `indexName`. (The only supported provider is "algolia" right now)

packages/webdoc-cli/src/config.js

@@ -31,19 +31,22 @@ type ConfigSchema = {
     template?: string,
   },
   template: {
+    applicationName: string,
     siteDomain?: string,
     siteRoot: string,
     mainPage?: {
       title?: string
     },
+    meta: any,
     default: {
       includeData?: true
     },
     apiExplorer?: {
       mode?: string
     },
     repository?: string,
-    outputSourceFiles?: boolean
+    outputSourceFiles?: boolean,
+    integrations: any,
   },
   version: {
     number?: 1
@@ -73,10 +76,12 @@ const defaultConfig: ConfigSchema = {
     template: "@webdoc/default-template",
   },
   template: {
+    applicationName: "{ <i>webdoc</i> }",
     siteRoot: "",
     mainPage: {
       title: "Main Page",
     },
+    meta: {},
     default: {
       includeDate: true,
     },
@@ -85,6 +90,7 @@ const defaultConfig: ConfigSchema = {
     },
     repository: undefined, // ex. GitHub repo holding source files to link source files
     // should contain branch - https://github.com/webdoc-js/webdoc/blob/master/
+    integrations: {},
   },
   version: {
     number: 1,

packages/webdoc-default-template/publish.js

@@ -177,7 +177,7 @@ async function outReadme(
   pipeline.render("pages/main-page.tmpl", {
     docs: [],
     readme,
-    title: "Test Template",
+    title: "Documentation",
     env: config,
   }, {outputFile});
 }
@@ -224,7 +224,6 @@ function outReference(
     }
 
     page = linker.processInternalURI(page, {outputRelative: true});
-
     let doc;
 
     try {

packages/webdoc-default-template/src/app/components/Explorer/ExplorerHeader.js

@@ -1,5 +1,6 @@
 import IconButton from "@material-ui/core/IconButton";
 import MenuIcon from "@material-ui/icons/Menu";
+import {appData} from "../../resource";
 import {makeStyles} from "@material-ui/core/styles";
 
 const useToggleButtonStyles = makeStyles({
@@ -27,7 +28,12 @@ export default function ExplorerHeader({
       >
         <MenuIcon />
       </IconButton>
-      <span className="explorer__header__title">{"{ "}<i>webdoc</i>{" }"}</span>
+      <span
+        className="explorer__header__title"
+        dangerouslySetInnerHTML={{
+          __html: appData.applicationName,
+        }}
+      />
     </section>
   );
 }

packages/webdoc-default-template/src/app/components/Explorer/ExplorerItem.js

@@ -32,10 +32,6 @@ export default function ExplorerItem(props) {
   const nodeId = props.data.$nodeId;
   const primary = props.data.page && isSamePage(props.data);
 
-  if (primary) {
-    console.log(props.data);
-  }
-
   const toggle = React.useCallback(
     () => props.toggle(nodeId),
     [nodeId],

packages/webdoc-default-template/src/app/components/Header/Header.js

@@ -1,4 +1,6 @@
 import {ExplorerHeader} from "../Explorer";
+import Search from "./Search";
+import {appData} from "../../resource";
 import {connect} from "react-redux";
 import store from "../../store";
 
@@ -18,7 +20,8 @@ export default connect(({explorerOpen}) => ({
         />}
       <div className="header__contents">
         <a className="header__link header__link__current">API Reference</a>
-        <a className="header__link">Guides</a>
+        {/* <a className="header__link">Guides</a> */ /* TODO: Add guides */}
+        {appData.integrations.search && <Search integration={appData.integrations.search} />}
       </div>
     </div>
   );

packages/webdoc-default-template/src/app/components/Header/Search.js

@@ -0,0 +1,73 @@
+import React from "react";
+import {getResourceURI} from "../../resource";
+
+export default function Search({
+  integration,
+}) {
+  const ref = React.useRef(null);
+  const enabled = React.useRef(false);
+
+  React.useEffect(
+    () => {
+      if (!ref.current || enabled.current) {
+        console.log("Input not found for search");
+        return;
+      }
+      if (integration.provider === "algolia") {
+        if (!window.docsearch) {
+          throw new Error("docsearch should be in global scope");
+        }
+
+        console.log("Initializing search");
+
+        window.docsearch({
+          apiKey: integration.apiKey,
+          appId: integration.appId,
+          indexName: integration.indexName,
+          inputSelector: "#search",
+          debug: false,
+        });
+
+        enabled.current = true;
+      }
+    },
+    [ref.current],
+  );
+
+  return (
+    <div
+      ref={ref}
+      className="search-container"
+      style={{
+        display: "grid",
+      }}
+    >
+      <input
+        id="search"
+        placeholder="Search"
+        style={{
+          backgroundColor: "#FBFBFB",
+          border: "1px solid rgba(0, 0, 0, .04)",
+          borderRadius: 4,
+          color: "rgba(0, 0, 0, 0.34)",
+          display: "flex",
+          fontSize: "12px",
+          height: "32px",
+          paddingLeft: "18px",
+          width: "240px",
+        }}
+      />
+      <img
+        src={getResourceURI("/icons/search.svg")}
+        style={{
+          alignSelf: "center",
+          justifySelf: "end",
+          marginTop: 2,
+          marginRight: 9,
+          pointerEvents: "none",
+          zIndex: 1,
+        }}
+      />
+    </div>
+  );
+}

packages/webdoc-default-template/src/app/resource.js

@@ -0,0 +1,11 @@
+export const appData = window.appData;
+
+export function getResourceURI(path) {
+  const root = window.appData.siteRoot;
+
+  if (!path.startsWith("/")) {
+    path = `/${path}`;
+  }
+
+  return root + path;
+}

packages/webdoc-default-template/src/styles/header.scss

@@ -22,6 +22,7 @@
   height: $header-height;
   top: 0;
   width: 100%;
+  z-index: 1;
 
   &__container {
     align-items: center;
@@ -40,7 +41,7 @@
     justify-content: flex-end;
     height: 100%;
 
-    * {
+    > * {
       margin-right: 42px;
     }
   }

packages/webdoc-default-template/src/styles/index.scss

@@ -13,3 +13,13 @@
 @import "footer";
 
 // @import "pages/api-index";
+
+.search-container > * {
+  grid-row: 1;
+  grid-column: 1;
+}
+
+#search:focus {
+  border: 1px solid rgba(0, 0, 0, 0.4);
+  outline: none;
+}