Enable sub-directories in docs/ (#705)

lib/server/readMetadata.js

@@ -15,7 +15,7 @@ const chalk = require('chalk');
 const env = require('./env.js');
 const siteConfig = require(CWD + '/siteConfig.js');
 const versionFallback = require('./versionFallback.js');
-const escapeStringRegexp = require('escape-string-regexp');
+const utils = require('./utils.js');
 
 const SupportedHeaderFields = new Set([
   'id',
@@ -121,17 +121,10 @@ function extractMetadata(content) {
   return {metadata, rawContent: both.content};
 }
 
-// process the metadata for a document found in the docs folder
-function processMetadata(file) {
+// process the metadata for a document found in either 'docs' or 'translated_docs'
+function processMetadata(file, refDir) {
   const result = extractMetadata(fs.readFileSync(file, 'utf8'));
-
-  let regexSubFolder = new RegExp(
-    '/' + escapeStringRegexp(getDocsPath()) + '/(.*)/.*/'
-  );
-
-  const match = regexSubFolder.exec(file);
-  let language = match ? match[1] : 'en';
-
+  const language = utils.getLanguage(file, refDir) || 'en';
   const metadata = {};
   for (const fieldName of Object.keys(result.metadata)) {
     if (SupportedHeaderFields.has(fieldName)) {
@@ -142,7 +135,6 @@ function processMetadata(file) {
   }
 
   const rawContent = result.rawContent;
-  metadata.source = path.basename(file);
 
   if (!metadata.id) {
     metadata.id = path.basename(file, path.extname(file));
@@ -150,6 +142,21 @@ function processMetadata(file) {
   if (metadata.id.includes('/')) {
     throw new Error('Document id cannot include "/".');
   }
+
+  // If a file is located in a subdirectory, prepend the subdir to it's ID
+  // Example:
+  //  (file: 'docusaurus/docs/projectA/test.md', ID 'test', refDir: 'docs')
+  //  returns 'projectA/test'
+  const subDir = utils.getSubDir(file, refDir);
+  if (subDir) {
+    metadata.id = `${subDir}/${metadata.id}`;
+  }
+
+  // Example: `docs/projectA/test.md` source is `projectA/test.md`
+  metadata.source = subDir
+    ? `${subDir}/${path.basename(file)}`
+    : path.basename(file);
+
   if (!metadata.title) {
     metadata.title = metadata.id;
   }
@@ -209,6 +216,7 @@ function generateMetadataDocs() {
   const defaultMetadatas = {};
 
   // metadata for english files
+  const docsDir = path.join(CWD, '../', getDocsPath());
   let files = glob.sync(CWD + '/../' + getDocsPath() + '/**');
   files.forEach(file => {
     let language = 'en';
@@ -216,7 +224,7 @@ function generateMetadataDocs() {
     const extension = path.extname(file);
 
     if (extension === '.md' || extension === '.markdown') {
-      const res = processMetadata(file);
+      const res = processMetadata(file, docsDir);
 
       if (!res) {
         return;
@@ -255,23 +263,17 @@ function generateMetadataDocs() {
   });
 
   // metadata for non-english docs
-  const regexSubFolder = /translated_docs\/(.*?)\/.*/;
+  const translatedDir = path.join(CWD, 'translated_docs');
   files = glob.sync(CWD + '/translated_docs/**');
   files.forEach(file => {
-    let language = 'en';
-    const match = regexSubFolder.exec(file);
-    if (match) {
-      language = match[1];
-    }
-
-    if (enabledLanguages.indexOf(language) === -1) {
+    if (!utils.getLanguage(file, translatedDir)) {
       return;
     }
 
     const extension = path.extname(file);
 
     if (extension === '.md' || extension === '.markdown') {
-      const res = processMetadata(file);
+      const res = processMetadata(file, translatedDir);
       if (!res) {
         return;
       }

lib/server/server.js

@@ -130,7 +130,7 @@ function execute(port) {
   // handle all requests for document pages
   const app = express();
 
-  app.get(/docs\/.*html$/, (req, res, next) => {
+  app.get(/^\/docs\/.*html$/, (req, res, next) => {
     let url = req.path.toString().replace(siteConfig.baseUrl, '');
 
     // links is a map from a permalink to an id for each document

lib/server/utils.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const path = require('path');
+const escapeStringRegexp = require('escape-string-regexp');
+const env = require('./env.js');
+
+// Return the subdirectory path from a reference directory
+// Example:
+//  (file: 'docs/projectA/test.md', refDir: 'subDir')
+//  returns 'projectA'
+function getSubDir(file, refDir) {
+  let subDir = path.dirname(path.relative(refDir, file));
+  subDir = subDir.replace('\\', '/');
+  return subDir !== '.' ? subDir : null;
+}
+
+// Get the corresponding enabled language locale of a file.
+// Example:
+//  (file: '/website/translated_docs/ko/projectA/test.md', refDir: 'website/translated_docs')
+//  returns 'ko'
+function getLanguage(file, refDir) {
+  let regexSubFolder = new RegExp(
+    '/' + escapeStringRegexp(path.basename(refDir)) + '/(.*)/.*/'
+  );
+  const match = regexSubFolder.exec(file);
+
+  // Avoid misinterpreting subdirectory as language
+  if (match && env.translation.enabled) {
+    const enabledLanguages = env.translation
+      .enabledLanguages()
+      .map(language => language.tag);
+    if (enabledLanguages.indexOf(match[1]) !== -1) {
+      return match[1];
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  getSubDir,
+  getLanguage,
+};

lib/server/versionFallback.js

@@ -12,6 +12,7 @@ const path = require('path');
 const assert = require('assert');
 
 const env = require('./env.js');
+const utils = require('./utils.js');
 const siteConfig = require(CWD + '/siteConfig.js');
 
 const ENABLE_TRANSLATION = fs.existsSync(CWD + '/languages.js');
@@ -194,7 +195,25 @@ function diffLatestDoc(file, id) {
 // the version of the file to be used, and its language
 function processVersionMetadata(file, version, useVersion, language) {
   const metadata = extractMetadata(fs.readFileSync(file, 'utf8')).metadata;
-  metadata.source = 'version-' + useVersion + '/' + path.basename(file);
+
+  // Add subdirectory information to versioned_doc metadata
+  // Example: `versioned_docs/version-1.1.6/projectA/readme.md` file with id `version-1.1.6-readme`
+  // and original_id `readme` will have metadata id of `version-1.1.6-projectA/readme` and original_id `projectA/readme`
+  const subDir = utils.getSubDir(
+    file,
+    path.join(CWD, 'versioned_docs', `version-${useVersion}`)
+  );
+  if (subDir) {
+    metadata.original_id = `${subDir}/${metadata.original_id}`;
+    metadata.id = metadata.id.replace(
+      `version-${useVersion}-`,
+      `version-${useVersion}-${subDir}/`
+    );
+  }
+
+  metadata.source = subDir
+    ? `version-${useVersion}/${subDir}/${path.basename(file)}`
+    : `version-${useVersion}/${path.basename(file)}`;
 
   const latestVersion = versions[0];