feat:docs translation + versioning 💥

lib/load/docs/index.js

@@ -1,37 +1,113 @@
-const fs = require('fs-extra');
 const path = require('path');
-const fm = require('front-matter');
 const globby = require('globby');
-const {encodePath, fileToPath} = require('../utils');
+const createOrder = require('./order');
+const loadSidebars = require('./sidebars');
+const processMetadata = require('./metadata');
+const {getSubFolder, idx} = require('../utils');
 
-function parse(fileString) {
-  if (!fm.test(fileString)) {
-    return {metadata: null, content: fileString};
-  }
-  const {attributes: metadata, body: content} = fm(fileString);
+async function loadDocs({siteDir, docsDir, env}) {
+  // @tested - load all sidebars including versioned sidebars
+  const allSidebars = loadSidebars({siteDir, env});
 
-  return {metadata, content};
-}
+  // @tested - build the docs ordering such as next, previous, category and sidebar
+  const order = createOrder(allSidebars);
 
-async function loadDocs(docsDir) {
+  /* Settle versions & translations from environment */
+  const translationEnabled = idx(env, ['translation', 'enabled']);
+  const enabledLanguages =
+    translationEnabled && idx(env, ['translation', 'enabledLanguages']);
+  const enabledLangTags =
+    (enabledLanguages && enabledLanguages.map(lang => lang.tag)) || [];
+  const defaultLanguage = idx(env, ['translation', 'defaultLanguage']);
+  const defaultLangTag = defaultLanguage && defaultLanguage.tag;
+  const versioningEnabled = idx(env, ['versioning', 'enabled']);
+  const versions =
+    (versioningEnabled && idx(env, ['versioning', 'versions'])) || [];
+
+  /* Prepare metadata container */
+  const metadatas = {};
+
+  /* metadata for default docs files */
   const docsFiles = await globby(['**/*.md'], {
     cwd: docsDir
   });
-
-  const docsData = await Promise.all(
+  await Promise.all(
     docsFiles.map(async source => {
-      const filepath = path.resolve(docsDir, source);
-      const fileString = await fs.readFile(filepath, 'utf-8');
-      const {metadata} = parse(fileString);
+      /* 
+        Do not allow reserved version/ translated folder name in 'docs'
+        e.g: 'docs/version-1.0.0/' should not be allowed as it can cause unwanted bug
+      */
+      const subFolder = getSubFolder(path.resolve(docsDir, source), docsDir);
+      const versionsFolders = versions.map(version => `version-${version}`);
+      if ([...enabledLangTags, ...versionsFolders].includes(subFolder)) {
+        throw new Error(`You cannot have a folder named 'docs/${subFolder}/'`);
+      }
 
-      return {
-        path: encodePath(fileToPath(source)),
-        source,
-        ...metadata
-      };
+      const metadata = await processMetadata(source, docsDir, env, order);
+      metadatas[metadata.id] = metadata;
     })
   );
-  return docsData;
+
+  /* metadata for non-default-language docs */
+  const translatedDir = path.join(siteDir, 'translated_docs');
+  const translatedFiles = await globby(['**/*.md'], {
+    cwd: translatedDir
+  });
+  await Promise.all(
+    translatedFiles.map(async source => {
+      /* 
+        Do not process disabled & default languages folder in `translated_docs`
+        e.g: 'translated_docs/ja/**' should not be allowed if lang 'ja' is disabled
+      */
+      const translatedFilePath = path.resolve(translatedDir, source);
+      const detectedLangTag = getSubFolder(translatedFilePath, translatedDir);
+      if (
+        detectedLangTag === defaultLangTag ||
+        !enabledLangTags.includes(detectedLangTag)
+      ) {
+        return;
+      }
+
+      const metadata = await processMetadata(source, translatedDir, env, order);
+      metadatas[metadata.id] = metadata;
+    })
+  );
+
+  /* metadata for versioned docs */
+  const versionedDir = path.join(siteDir, 'versioned_docs');
+  const versionedFiles = await globby(['**/*.md'], {
+    cwd: versionedDir
+  });
+  await Promise.all(
+    versionedFiles.map(async source => {
+      const metadata = await processMetadata(source, versionedDir, env, order);
+      metadatas[metadata.id] = metadata;
+    })
+  );
+
+  /*
+   Get the titles of the previous and next ids so that we can use them
+  */
+  Object.keys(metadatas).forEach(metadata => {
+    if (metadatas[metadata].previous) {
+      if (metadatas[metadatas[metadata].previous]) {
+        metadatas[metadata].previous_title =
+          metadatas[metadatas[metadata].previous].title;
+      } else {
+        metadatas[metadata].previous_title = 'Previous';
+      }
+    }
+    if (metadatas[metadata].next) {
+      if (metadatas[metadatas[metadata].next]) {
+        metadatas[metadata].next_title =
+          metadatas[metadatas[metadata].next].title;
+      } else {
+        metadatas[metadata].next_title = 'Next';
+      }
+    }
+  });
+
+  return metadatas;
 }
 
 module.exports = loadDocs;

lib/load/docs/metadata.js

@@ -0,0 +1,127 @@
+const fs = require('fs-extra');
+const path = require('path');
+const {getSubFolder, idx, parse} = require('../utils');
+
+function getLanguage(filepath, refDir, env) {
+  const translationEnabled = idx(env, ['translation', 'enabled']);
+  if (translationEnabled) {
+    const detectedLangTag = getSubFolder(filepath, refDir);
+    const defaultLanguage = idx(env, ['translation', 'defaultLanguage']);
+    if (!detectedLangTag && defaultLanguage && defaultLanguage.tag) {
+      return defaultLanguage.tag;
+    }
+    const enabledLanguages = idx(env, ['translation', 'enabledLanguages']);
+    const langTags =
+      (enabledLanguages && enabledLanguages.map(lang => lang.tag)) || [];
+    return langTags.find(langTag => langTag === detectedLangTag);
+  }
+  return undefined;
+}
+
+function getVersion(filepath, refDir, env) {
+  const versioningEnabled = idx(env, ['versioning', 'enabled']);
+  if (versioningEnabled) {
+    const subFolder = getSubFolder(filepath, refDir);
+    if (!subFolder) {
+      return 'next';
+    }
+    const detectedVersion = subFolder.replace(/^version-/, '');
+    const versions = idx(env, ['versioning', 'versions']) || [];
+    if (versions.includes(detectedVersion)) {
+      return detectedVersion;
+    }
+    return 'next';
+  }
+  return undefined;
+}
+
+module.exports = async function processMetadata(source, refDir, env, order) {
+  const filepath = path.resolve(refDir, source);
+  const fileString = await fs.readFile(filepath, 'utf-8');
+  const {metadata} = parse(fileString);
+
+  /* source (relative to refDir) */
+  metadata.source = source;
+
+  /* default id is the file name */
+  if (!metadata.id) {
+    metadata.id = path.basename(source, path.extname(source));
+  }
+  if (metadata.id.includes('/')) {
+    throw new Error('Document id cannot include "/".');
+  }
+
+  /* default title is the id */
+  if (!metadata.title) {
+    metadata.title = metadata.id;
+  }
+
+  /* language */
+  const language = getLanguage(filepath, refDir, env);
+  metadata.language = language;
+  const langPart = (language && `${language}/`) || '';
+
+  /* version */
+  const versionRefDir = language ? path.join(refDir, language) : refDir;
+  const version = getVersion(filepath, versionRefDir, env);
+  metadata.version = version;
+  const latestVersion = idx(env, ['versioning', 'latestVersion']);
+  const versionPart =
+    (version && version !== latestVersion && `${version}/`) || '';
+
+  /* 
+    Convert temporarily metadata.id to the form of dirname/id without version/lang prefix
+    ex: file `versioned_docs/version-1.0.0/en/foo/bar.md` with id `version-1.0.0-bar` => `foo/bar`
+  */
+
+  if (version) {
+    metadata.id = metadata.id.replace(new RegExp(`^version-${version}-`), '');
+  }
+
+  const dirName = path.dirname(source);
+  if (dirName !== '.') {
+    let prefix = dirName;
+    if (version) {
+      prefix = prefix.replace(new RegExp(`^version-${version}`), '');
+    }
+    if (language) {
+      prefix = prefix.replace(new RegExp(`^${language}`), '');
+    }
+    if (prefix) {
+      prefix = prefix.replace(/^\//, '');
+      metadata.id = `${prefix}/${metadata.id}`;
+    }
+  }
+
+  /* Build the permalink without baseUrl */
+  metadata.permalink = `docs/${langPart}${versionPart}${metadata.id}`;
+
+  /* if version */
+  if (version && version !== 'next') {
+    metadata.id = `version-${version}-${metadata.id}`;
+  }
+
+  /* if language */
+  if (language) {
+    metadata.id = `${language}-${metadata.id}`;
+  }
+
+  /* localize id */
+  metadata.localized_id = metadata.id;
+
+  /* Determine order */
+  const id = metadata.localized_id;
+  if (order[id]) {
+    metadata.sidebar = order[id].sidebar;
+    metadata.category = order[id].category;
+    if (order[id].next) {
+      metadata.next_id = order[id].next;
+      metadata.next = (language ? `${language}-` : '') + order[id].next;
+    }
+    if (order[id].previous) {
+      metadata.previous_id = order[id].previous;
+      metadata.previous = (language ? `${language}-` : '') + order[id].previous;
+    }
+  }
+  return metadata;
+};

lib/load/docs/order.js

@@ -1,34 +1,36 @@
-// build the docs meta such as next, previous, category and sidebar
-module.exports = function createOrder(allSidebars = {}) {
-  const order = {};
-  if (!allSidebars) {
-    return order;
-  }
-  Object.keys(allSidebars).forEach(sidebar => {
-    const categories = allSidebars[sidebar];
-
-    let ids = [];
-    const categoryOrder = [];
-    Object.keys(categories).forEach(category => {
-      ids = ids.concat(categories[category]);
-      for (let i = 0; i < categories[category].length; i++) {
-        categoryOrder.push(category);
-      }
-    });
-
-    for (let i = 0; i < ids.length; i++) {
-      const id = ids[i];
-      let previous;
-      let next;
-      if (i > 0) previous = ids[i - 1];
-      if (i < ids.length - 1) next = ids[i + 1];
-      order[id] = {
-        previous,
-        next,
-        sidebar,
-        category: categoryOrder[i]
-      };
-    }
-  });
-  return order;
-};
+// build the docs meta such as next, previous, category and sidebar
+module.exports = function createOrder(allSidebars = {}) {
+  const order = {};
+  if (!allSidebars) {
+    return order;
+  }
+  Object.keys(allSidebars).forEach(sidebar => {
+    const categories = allSidebars[sidebar];
+
+    let ids = [];
+    const categoryOrder = [];
+    Object.keys(categories).forEach(category => {
+      ids = ids.concat(categories[category]);
+      // eslint-disable-next-line
+      for (let i = 0; i < categories[category].length; i++) {
+        categoryOrder.push(category);
+      }
+    });
+
+    // eslint-disable-next-line
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      let previous;
+      let next;
+      if (i > 0) previous = ids[i - 1];
+      if (i < ids.length - 1) next = ids[i + 1];
+      order[id] = {
+        previous,
+        next,
+        sidebar,
+        category: categoryOrder[i]
+      };
+    }
+  });
+  return order;
+};

lib/load/docs/sidebars.js

@@ -1,34 +1,35 @@
-const fs = require('fs-extra');
-const path = require('path');
-const {idx} = require('../utils');
-
-module.exports = function loadSidebars({siteDir, env}) {
-  let allSidebars = {};
-
-  // current sidebars
-  const sidebarsJSONFile = path.join(siteDir, 'sidebars.json');
-  if (fs.existsSync(sidebarsJSONFile)) {
-    allSidebars = require(sidebarsJSONFile);
-  }
-
-  // versioned sidebars
-  if (idx(env, ['versioning', 'enabled'])) {
-    const versions = idx(env, ['versioning', 'versions']);
-    versions &&
-      versions.forEach(version => {
-        const versionedSidebarsJSONFile = path.join(
-          siteDir,
-          'versioned_sidebars',
-          `version-${version}-sidebars.json`
-        );
-        if (fs.existsSync(versionedSidebarsJSONFile)) {
-          const sidebar = require(versionedSidebarsJSONFile);
-          Object.assign(allSidebars, sidebar);
-        } else {
-          const missingFile = path.relative(siteDir, versionedSidebarsJSONFile);
-          throw new Error(`Failed to load ${missingFile}. It does not exist.`);
-        }
-      });
-  }
-  return allSidebars;
-};
+const fs = require('fs-extra');
+const path = require('path');
+const {idx} = require('../utils');
+
+module.exports = function loadSidebars({siteDir, env}) {
+  let allSidebars = {};
+
+  // current sidebars
+  const sidebarsJSONFile = path.join(siteDir, 'sidebars.json');
+  if (fs.existsSync(sidebarsJSONFile)) {
+    allSidebars = require(sidebarsJSONFile); // eslint-disable-line
+  }
+
+  // versioned sidebars
+  if (idx(env, ['versioning', 'enabled'])) {
+    const versions = idx(env, ['versioning', 'versions']);
+    if (Array.isArray(versions)) {
+      versions.forEach(version => {
+        const versionedSidebarsJSONFile = path.join(
+          siteDir,
+          'versioned_sidebars',
+          `version-${version}-sidebars.json`
+        );
+        if (fs.existsSync(versionedSidebarsJSONFile)) {
+          const sidebar = require(versionedSidebarsJSONFile); // eslint-disable-line
+          Object.assign(allSidebars, sidebar);
+        } else {
+          const missingFile = path.relative(siteDir, versionedSidebarsJSONFile);
+          throw new Error(`Failed to load ${missingFile}. It does not exist.`);
+        }
+      });
+    }
+  }
+  return allSidebars;
+};