From e273dfc13b4031d4d20180d0de30b1c5280d2bf8 Mon Sep 17 00:00:00 2001
From: Joel Marcey <joelm@fb.com>
Date: Thu, 9 Nov 2017 09:55:26 -0800
Subject: [PATCH] Allow the docs not to just be in a folder called `docs`

Also:
- regex escaping
- update api documentation
---
 docs/api-site-config.md    | 10 ++++++++++
 lib/core/nav/HeaderNav.js  | 10 ++++++----
 lib/server/readMetadata.js | 11 +++++++----
 package.json               |  1 +
 website/siteConfig.js      |  2 +-
 5 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/docs/api-site-config.md b/docs/api-site-config.md
index e5619476e105..bd8f9e6bf168 100644
--- a/docs/api-site-config.md
+++ b/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.
diff --git a/lib/core/nav/HeaderNav.js b/lib/core/nav/HeaderNav.js
index 8af423055426..baa0a3cf0bad 100644
--- a/lib/core/nav/HeaderNav.js
+++ b/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'."
         );
       }
diff --git a/lib/server/readMetadata.js b/lib/server/readMetadata.js
index a24780c670fa..d4ebeca7ec53 100644
--- a/lib/server/readMetadata.js
+++ b/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);
diff --git a/package.json b/package.json
index 4c4da7029386..ba531d8d1c42 100644
--- a/package.json
+++ b/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",
diff --git a/website/siteConfig.js b/website/siteConfig.js
index dd24bd38e8cd..d2c15c911102 100644
--- a/website/siteConfig.js
+++ b/website/siteConfig.js
@@ -68,7 +68,7 @@ const siteConfig = {
   copyright: "Copyright © " + new Date().getFullYear() + " Facebook Inc.",
   highlight: {
     theme: "solarized-dark"
-  }
+  },
 };