Enable sub-directories in docs/

lib/__tests__/build-files.test.js

@@ -42,7 +42,7 @@ beforeAll(() => {
  generateSite();
  return Promise.all([
  glob(docsDir + '/**/*.md'),
- glob(buildDir + '/' + siteConfig.projectName + '/docs/*.html'),
+ glob(buildDir + '/' + siteConfig.projectName + '/docs/**/*.html'),
  glob(docsDir + '/assets/*'),
  glob(buildDir + '/' + siteConfig.projectName + '/img/*'),
  ]).then(function(results) {

lib/core/DocsLayout.js

@@ -12,6 +12,7 @@ const DocsSidebar = require('./DocsSidebar.js');
 const OnPageNav = require('./nav/OnPageNav.js');
 const Site = require('./Site.js');
 const translation = require('../server/translation.js');
+const path = require('path');
 
 // component used to generate whole webpage for docs, including sidebar/header/footer
 class DocsLayout extends React.Component {
@@ -54,7 +55,12 @@ class DocsLayout extends React.Component {
  {metadata.previous_id && (
  <a
  className="docs-prev button"
- href={metadata.previous_id + '.html'}>
+ href={
+ path
+ .relative(metadata.localized_id, metadata.previous_id)
+ .replace('\\', '/')
+ .replace(/^\.\.\//, '') + '.html'
+ }>
  ←{' '}
  {i18n
  ? translation[this.props.metadata.language][
@@ -70,7 +76,12 @@ class DocsLayout extends React.Component {
  {metadata.next_id && (
  <a
  className="docs-next button"
- href={metadata.next_id + '.html'}>
+ href={
+ path
+ .relative(metadata.localized_id, metadata.next_id)
+ .replace('\\', '/')
+ .replace(/^\.\.\//, '') + '.html'
+ }>
  {i18n
  ? translation[this.props.metadata.language][
  'localized-strings'

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,14 +135,28 @@ function processMetadata(file) {
  }
 
  const rawContent = result.rawContent;
- metadata.source = path.basename(file);
 
  if (!metadata.id) {
  metadata.id = path.basename(file, path.extname(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;
  }
@@ -216,7 +223,7 @@ function generateMetadataDocs() {
  const extension = path.extname(file);
 
  if (extension === '.md' || extension === '.markdown') {
- const res = processMetadata(file);
+ const res = processMetadata(file, path.join(CWD, '../', getDocsPath()));
 
  if (!res) {
  return;
@@ -255,23 +262,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,27 @@ 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 =
+ 'version-' +
+ useVersion +
+ '/' +
+ (subDir ? subDir + '/' + path.basename(file) : path.basename(file));
 
  const latestVersion = versions[0];
 

lib/version.js

@@ -66,12 +66,18 @@ function makeHeader(metadata) {
  return header;
 }
 
+function writeFileAndCreateFolder(file, content, encoding) {
+ mkdirp.sync(path.dirname(file));
+
+ fs.writeFileSync(file, content, encoding);
+}
+
 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 + '/../' + readMetadata.getDocsPath() + '/*');
+let files = glob.sync(CWD + '/../' + readMetadata.getDocsPath() + '/**');
 files.forEach(file => {
  const ext = path.extname(file);
  if (ext !== '.md' && ext !== '.markdown') {
@@ -102,9 +108,18 @@ files.forEach(file => {
  metadata.original_id = metadata.id;
  metadata.id = 'version-' + version + '-' + metadata.id;
 
- const targetFile = versionFolder + '/' + path.basename(file);
+ let filePath = path.basename(file);
+ const subDir = readMetadata.getSubDir(file);
+ if (subDir) {
+ filePath = subDir + '/' + filePath;
+ }
+ const targetFile = versionFolder + '/' + filePath;
 
- fs.writeFileSync(targetFile, makeHeader(metadata) + rawContent, 'utf8');
+ writeFileAndCreateFolder(
+ targetFile,
+ makeHeader(metadata) + rawContent,
+ 'utf8'
+ );
 });
 
 // copy sidebar if necessary

lib/write-translations.js

@@ -52,7 +52,8 @@ function execute() {
  if (extension === '.md' || extension === '.markdown') {
  let res;
  try {
- res = readMetadata.processMetadata(file);
+ const docsDir = path.join(CWD, '../', readMetadata.getDocsPath());
+ res = readMetadata.processMetadata(file, docsDir);
  } catch (e) {
  console.error(e);
  process.exit(1);