Allow the docs not to just be in a folder called docs

Also:
- regex escaping
- update api documentation

docs/api-site-config.md

@@ -62,6 +62,16 @@ headerLinks: [
 
 ### Optional Fields
 
+`customDocsPath` - By default, Docusaurus expects your documentation to be in a directory called `docs`. This directory is at the same level as the `website` directory (i.e., not inside the `website` directory). You can specify a custom path to your documentation with this field. **Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories**.
+
+```js
+customDocsPath: "docs/site"
+```
+
+```js
+customDocsPath: "website-docs"
+```
+
 `editUrl` - url for editing docs, usage example: `editUrl + 'en/doc1.md'`. If this field is omitted, there will be no "Edit this Doc" button for each document.
 
 `users` - The `users` array mentioned earlier.

lib/core/nav/HeaderNav.js

@@ -21,7 +21,8 @@ let versions;
 if (ENABLE_VERSIONING) {
   versions = require(CWD + "/versions.json");
 }
-require("../../server/readMetadata.js").generateMetadataDocs();
+const readMetadata = require("../../server/readMetadata.js");
+readMetadata.generateMetadataDocs();
 const Metadata = require("../metadata.js");
 
 // language dropdown nav item for when translations are enabled
@@ -221,9 +222,10 @@ class HeaderNav extends React.Component {
     }
     let search = false;
     headerLinks.forEach(link => {
-      if (link.doc && !fs.existsSync(CWD + "/../docs/")) {
+      if (link.doc && !fs.existsSync(CWD + "/../" + readMetadata.getDocsPath() + "/")) {
         throw new Error(
-          "You have 'doc' in your headerLinks, but no 'docs' folder exists one level up from " +
+          "You have 'doc' in your headerLinks, but no '" + readMetadata.getDocsPath() +
+            "' folder exists one level up from " +
             "'website' folder. Did you run `docusaurus-init` or `npm run examples`? If so, " +
             "make sure you rename 'docs-examples-from-docusaurus' to 'docs'."
         );
@@ -231,7 +233,7 @@ class HeaderNav extends React.Component {
       if (link.blog && !fs.existsSync(CWD + "/blog/")) {
         throw new Error(
           "You have 'blog' in your headerLinks, but no 'blog' folder exists in your " +
-            "website folder. Did you run `docusaurus-init` or `npm run examples`? If so, " +
+            "'website' folder. Did you run `docusaurus-init` or `npm run examples`? If so, " +
             "make sure you rename 'blog-examples-from-docusaurus' to 'blog'."
         );
       }

lib/server/readMetadata.js

@@ -13,6 +13,7 @@ const glob = require("glob");
 const chalk = require("chalk");
 const siteConfig = require(CWD + "/siteConfig.js");
 const versionFallback = require("./versionFallback.js");
+const escapeStringRegexp = require("escape-string-regexp");
 
 const ENABLE_VERSIONING = fs.existsSync(CWD + "/versions.json");
 
@@ -31,13 +32,15 @@ if (fs.existsSync(CWD + "/languages.js")) {
   ];
 }
 
-// Can add additional path information to the docs folder
+// Can have a custom docs path. Top level folder still needs to be in directory
+// at the same level as `website`, not inside `website`.
 //   e.g., docs/whereDocsReallyExist
+//         website-docs/
 // All .md docs still (currently) must be in one flat directory hierarchy.
 //   e.g., docs/whereDocsReallyExist/*.md (all .md files in this dir)
 function getDocsPath() {
-  return siteConfig.docsAdditionalPath
-    ? "docs" + siteConfig.docsAdditionalPath
+  return siteConfig.customDocsPath
+    ? siteConfig.customDocsPath
     : "docs";
 }
 // returns map from id to object containing sidebar ordering info
@@ -125,7 +128,7 @@ function extractMetadata(content) {
 function processMetadata(file) {
   const result = extractMetadata(fs.readFileSync(file, "utf8"));
 
-  let regexSubFolder = new RegExp("/" + getDocsPath() + "\/(.*)\/.*/");
+  let regexSubFolder = new RegExp("/" + escapeStringRegexp(getDocsPath()) + "\/(.*)\/.*/");
 
   let language = "en";
   const match = regexSubFolder.exec(file);

package.json

@@ -13,6 +13,7 @@
     "commander": "^2.11.0",
     "crowdin-cli": "^0.3.0",
     "diff": "^3.3.0",
+    "escape-string-regexp": "^1.0.5",
     "express": "^4.15.3",
     "feed": "^1.1.0",
     "fs-extra": "^3.0.1",

website/siteConfig.js

@@ -68,7 +68,7 @@ const siteConfig = {
   copyright: "Copyright © " + new Date().getFullYear() + " Facebook Inc.",
   highlight: {
     theme: "solarized-dark"
-  }
+  },
 };