v2: prepare to move

v2/lib/load/docs/index.js

@@ -0,0 +1,129 @@
+const path = require('path');
+const globby = require('globby');
+const createOrder = require('./order');
+const loadSidebars = require('./sidebars');
+const processMetadata = require('./metadata');
+const {getSubFolder, idx} = require('../utils');
+
+async function loadDocs({siteDir, docsDir, env, siteConfig}) {
+  // @tested - load all sidebars including versioned sidebars
+  const docsSidebars = loadSidebars({siteDir, env});
+
+  // @tested - build the docs ordering such as next, previous, category and sidebar
+  const order = createOrder(docsSidebars);
+
+  /* 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 defaultLangTag = idx(env, ['translation', 'defaultLanguage', 'tag']);
+  const versioningEnabled = idx(env, ['versioning', 'enabled']);
+  const versions =
+    (versioningEnabled && idx(env, ['versioning', 'versions'])) || [];
+
+  /* Prepare metadata container */
+  const docsMetadatas = {};
+
+  /* metadata for default docs files */
+  const docsFiles = await globby(['**/*.md'], {
+    cwd: docsDir
+  });
+  await Promise.all(
+    docsFiles.map(async source => {
+      /* 
+        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}/'`);
+      }
+
+      const metadata = await processMetadata(
+        source,
+        docsDir,
+        env,
+        order,
+        siteConfig
+      );
+      docsMetadatas[metadata.id] = metadata;
+    })
+  );
+
+  /* metadata for non-default-language docs */
+  if (translationEnabled) {
+    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 processed 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,
+          siteConfig
+        );
+        docsMetadatas[metadata.id] = metadata;
+      })
+    );
+  }
+
+  /* metadata for versioned docs */
+  if (versioningEnabled) {
+    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,
+          siteConfig
+        );
+        docsMetadatas[metadata.id] = metadata;
+      })
+    );
+  }
+
+  /* Get the titles of the previous and next ids so that we can use them */
+  Object.keys(docsMetadatas).forEach(currentID => {
+    const previousID = idx(docsMetadatas, [currentID, 'previous']);
+    if (previousID) {
+      const previousTitle = idx(docsMetadatas, [previousID, 'title']);
+      docsMetadatas[currentID].previous_title = previousTitle || 'Previous';
+    }
+    const nextID = idx(docsMetadatas, [currentID, 'next']);
+    if (nextID) {
+      const nextTitle = idx(docsMetadatas, [nextID, 'title']);
+      docsMetadatas[currentID].next_title = nextTitle || 'Next';
+    }
+  });
+
+  return {
+    docsSidebars,
+    docsMetadatas
+  };
+}
+
+module.exports = loadDocs;

v2/lib/load/docs/metadata.js

@@ -0,0 +1,170 @@
+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 enabledLanguages = idx(env, ['translation', 'enabledLanguages']);
+    const langTags =
+      (enabledLanguages && enabledLanguages.map(lang => lang.tag)) || [];
+    if (langTags.includes(detectedLangTag)) {
+      return detectedLangTag;
+    }
+    const defaultLanguage = idx(env, ['translation', 'defaultLanguage']);
+    if (defaultLanguage && defaultLanguage.tag) {
+      return defaultLanguage.tag;
+    }
+  }
+  return undefined;
+}
+
+function getVersion(filepath, refDir, env) {
+  const versioningEnabled = idx(env, ['versioning', 'enabled']);
+  if (versioningEnabled) {
+    const subFolder = getSubFolder(filepath, refDir);
+    if (subFolder) {
+      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,
+  siteConfig
+) {
+  const filepath = path.resolve(refDir, source);
+  const fileString = await fs.readFile(filepath, 'utf-8');
+  const {metadata} = parse(fileString);
+
+  /* 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 defaultLangTag = idx(env, ['translation', 'defaultLanguage', 'tag']);
+  let versionRefDir = refDir;
+  if (language && language !== defaultLangTag) {
+    versionRefDir = path.join(refDir, language);
+  }
+  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 (language) {
+    metadata.id = metadata.id.replace(new RegExp(`^${language}-`), '');
+  }
+
+  if (version) {
+    metadata.id = metadata.id.replace(new RegExp(`^version-${version}-`), '');
+  }
+
+  const dirName = path.dirname(source);
+  if (dirName !== '.') {
+    let prefix = dirName;
+    if (language) {
+      prefix = prefix.replace(new RegExp(`^${language}`), '');
+    }
+    prefix = prefix.replace(/^\//, '');
+    if (version) {
+      prefix = prefix.replace(new RegExp(`^version-${version}`), '');
+    }
+    prefix = prefix.replace(/^\//, '');
+    if (prefix) {
+      metadata.id = `${prefix}/${metadata.id}`;
+    }
+  }
+
+  /* 
+    The docs file source
+    e.g: `@docs/hello.md` or `@versioned_docs/version-1.0.0/hello.md` 
+  */
+  if (language && language !== defaultLangTag) {
+    metadata.source = `@translated_docs/${source}`;
+  } else if (version && version !== 'next') {
+    metadata.source = `@versioned_docs/${source}`;
+  } else {
+    metadata.source = `@docs/${source}`;
+  }
+
+  /* Build the permalink */
+  const {baseUrl, docsUrl} = siteConfig;
+
+  /* 
+    if user has own custom permalink defined in frontmatter
+    e.g: :baseUrl:docsUrl/:langPart/:versionPart/endiliey/:id
+  */
+  if (metadata.permalink) {
+    metadata.permalink = path.resolve(
+      metadata.permalink
+        .replace(/:baseUrl/, baseUrl)
+        .replace(/:docsUrl/, docsUrl)
+        .replace(/:langPart/, langPart)
+        .replace(/:versionPart/, versionPart)
+        .replace(/:id/, metadata.id)
+    );
+  } else {
+    metadata.permalink = `${baseUrl}${docsUrl}/${langPart}${versionPart}${
+      metadata.id
+    }`;
+  }
+
+  /* if version */
+  if (version && version !== 'next') {
+    metadata.id = `version-${version}-${metadata.id}`;
+  }
+
+  /* save localized id before adding language on it */
+  metadata.localized_id = metadata.id;
+
+  /* if language */
+  if (language) {
+    metadata.id = `${language}-${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;
+};

v2/lib/load/docs/order.js

@@ -0,0 +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]);
+      // 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;
+};

v2/lib/load/docs/sidebars.js

@@ -0,0 +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); // 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;
+};