Merge pull request #217 from JoelMarcey/custom-docs-subdir

Allow custom path for the location of 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/generate.js

@@ -129,7 +129,7 @@ function execute() {
       }
     } else {
       if (metadata.language === "en") {
-        file = CWD + "/../docs/" + metadata.source;
+        file = CWD + "/../" + readMetadata.getDocsPath() + "/" + metadata.source;
       } else {
         file =
           CWD + "/translated_docs/" + metadata.language + "/" + metadata.source;
@@ -219,9 +219,9 @@ function execute() {
   });
 
   // copy docs assets if they exist
-  if (fs.existsSync(CWD + "/../docs/assets")) {
+  if (fs.existsSync(CWD + "/../" + readMetadata.getDocsPath() + "/assets")) {
     fs.copySync(
-      CWD + "/../docs/assets",
+      CWD + "/../" + readMetadata.getDocsPath() + "/assets",
       CWD + "/build/" + siteConfig.projectName + "/docs/assets"
     );
   }

lib/server/readMetadata.js

@@ -13,9 +13,12 @@ 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");
 
+
+
 let languages;
 if (fs.existsSync(CWD + "/languages.js")) {
   languages = require(CWD + "/languages.js");
@@ -29,6 +32,17 @@ if (fs.existsSync(CWD + "/languages.js")) {
   ];
 }
 
+// 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.customDocsPath
+    ? siteConfig.customDocsPath
+    : "docs";
+}
 // returns map from id to object containing sidebar ordering info
 function readSidebar() {
   let allSidebars;
@@ -114,7 +128,7 @@ function extractMetadata(content) {
 function processMetadata(file) {
   const result = extractMetadata(fs.readFileSync(file, "utf8"));
 
-  const regexSubFolder = /docs\/(.*)\/.*/;
+  let regexSubFolder = new RegExp("/" + escapeStringRegexp(getDocsPath()) + "\/(.*)\/.*/");
 
   let language = "en";
   const match = regexSubFolder.exec(file);
@@ -190,7 +204,7 @@ function generateMetadataDocs() {
     console.error(e);
     process.exit(1);
   }
-  
+
   const regexSubFolder = /translated_docs\/(.*)\/.*/;
 
   const enabledLanguages = [];
@@ -202,7 +216,7 @@ function generateMetadataDocs() {
   const defaultMetadatas = {};
 
   // metadata for english files
-  let files = glob.sync(CWD + "/../docs/**");
+  let files = glob.sync(CWD + "/../" + getDocsPath() + "/**");
   files.forEach(file => {
     let language = "en";
 
@@ -210,7 +224,7 @@ function generateMetadataDocs() {
 
     if (extension === ".md" || extension === ".markdown") {
       const res = processMetadata(file);
-      
+
       if (!res) {
         return;
       }
@@ -389,6 +403,7 @@ function generateMetadataBlog() {
 }
 
 module.exports = {
+  getDocsPath,
   readSidebar,
   extractMetadata,
   processMetadata,

lib/server/server.js

@@ -177,7 +177,7 @@ function execute(port) {
       }
     } else {
       if (metadata.language === "en") {
-        file = CWD + "/../docs/" + metadata.source;
+        file = CWD + "/../" + readMetadata.getDocsPath() + "/" + metadata.source;
       } else {
         file =
           CWD + "/translated_docs/" + metadata.language + "/" + metadata.source;
@@ -485,7 +485,7 @@ function execute(port) {
   // serve static assets from these locations
   app.use(
     siteConfig.baseUrl + "docs/assets/",
-    express.static(CWD + "/../docs/assets")
+    express.static(CWD + "/../" + readMetadata.getDocsPath() + "/assets")
   );
   app.use(
     siteConfig.baseUrl + "blog/assets/",

lib/version.js

@@ -65,7 +65,7 @@ const versionFolder = CWD + "/versioned_docs/version-" + version;
 mkdirp.sync(versionFolder);
 
 // copy necessary files to new version, changing some of its metadata to reflect the versioning
-let files = glob.sync(CWD + "/../docs/*");
+let files = glob.sync(CWD + "/../" + readMetadata.getDocsPath() + "/*");
 files.forEach(file => {
   const ext = path.extname(file);
   if (ext !== ".md" && ext !== ".markdown") {

lib/write-translations.js

@@ -48,7 +48,7 @@ function execute() {
   };
 
   // look through markdown headers of docs for titles and categories to translate
-  let files = glob.sync(CWD + "/../docs/**");
+  let files = glob.sync(CWD + "/../" + readMetadata.getDocsPath() + "/**");
   files.forEach(file => {
     const extension = path.extname(file);
     if (extension === ".md" || extension === ".markdown") {
@@ -91,7 +91,7 @@ function execute() {
   files.forEach(file => {
     if (!file.endsWith("-sidebars.json")) {
       if (file.endsWith("-sidebar.json")) {
-        console.warn(`Skipping ${file}. Make sure your sidebar filenames follow this format: 'version-VERSION-sidebars.json'.`);        
+        console.warn(`Skipping ${file}. Make sure your sidebar filenames follow this format: 'version-VERSION-sidebars.json'.`);
       }
       return;
     }

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",