Enable sub-directories in docs/

crowdin.yaml

@@ -5,8 +5,8 @@ preserve_hierarchy: true
 
 files:
  -
- source: '/docs/*.md'
- translation: '/website/translated_docs/%locale%/%original_file_name%'
+ source: '/docs/**/*.md'
+ translation: '/website/translated_docs/%locale%/**/%original_file_name%'
  languages_mapping: &anchor
  locale:
  'af': 'af'

docs/guides-translation.md

@@ -140,8 +140,8 @@ preserve_hierarchy: true
 
 files:
  -
- source: '/docs/*.md'
- translation: '/website/translated_docs/%locale%/%original_file_name%'
+ source: '/docs/**/*.md'
+ translation: '/website/translated_docs/%locale%/**/%original_file_name%'
  languages_mapping: &anchor
  locale:
  'de': 'de'

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,9 +12,20 @@ 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 {
+ getRelativeURL = (from, to) => {
+ const extension = this.props.config.cleanUrl ? '' : '.html';
+ return (
+ path
+ .relative(from, to)
+ .replace('\\', '/')
+ .replace(/^\.\.\//, '') + extension
+ );
+ };
+
  render() {
  const metadata = this.props.metadata;
  const content = this.props.children;
@@ -28,7 +39,6 @@ class DocsLayout extends React.Component {
  this.props.metadata.localized_id
  ] || this.props.metadata.title
  : this.props.metadata.title;
- const extension = this.props.config.cleanUrl ? '' : '.html';
  return (
  <Site
  config={this.props.config}
@@ -55,7 +65,10 @@ class DocsLayout extends React.Component {
  {metadata.previous_id && (
  <a
  className="docs-prev button"
- href={metadata.previous_id + extension}>
+ href={this.getRelativeURL(
+ metadata.localized_id,
+ metadata.previous_id
+ )}>
  ←{' '}
  {i18n
  ? translation[this.props.metadata.language][
@@ -71,7 +84,10 @@ class DocsLayout extends React.Component {
  {metadata.next_id && (
  <a
  className="docs-next button"
- href={metadata.next_id + extension}>
+ href={this.getRelativeURL(
+ metadata.localized_id,
+ metadata.next_id
+ )}>
  {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;
  }
@@ -209,14 +216,15 @@ 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';
 
  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];
 

lib/version.js

@@ -13,6 +13,7 @@ const path = require('path');
 const mkdirp = require('mkdirp');
 const chalk = require('chalk');
 const readMetadata = require('./server/readMetadata.js');
+const utils = require('./server/utils.js');
 const versionFallback = require('./server/versionFallback.js');
 const env = require('./server/env.js');
 
@@ -66,12 +67,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 +109,17 @@ files.forEach(file => {
  metadata.original_id = metadata.id;
  metadata.id = 'version-' + version + '-' + metadata.id;
 
- const targetFile = versionFolder + '/' + path.basename(file);
+ const docsDir = path.join(CWD, '../', readMetadata.getDocsPath());
+ const subDir = utils.getSubDir(file, docsDir);
+ const targetFile = subDir
+ ? `${versionFolder}/${subDir}/${path.basename(file)}`
+ : `${versionFolder}/${path.basename(file)}`;
 
- fs.writeFileSync(targetFile, makeHeader(metadata) + rawContent, 'utf8');
+ writeFileAndCreateFolder(
+ targetFile,
+ makeHeader(metadata) + rawContent,
+ 'utf8'
+ );
 });
 
 // copy sidebar if necessary

lib/write-translations.js

@@ -46,13 +46,14 @@ function execute() {
  };
 
  // look through markdown headers of docs for titles and categories to translate
+ const docsDir = path.join(CWD, '../', readMetadata.getDocsPath());
  let files = glob.sync(CWD + '/../' + readMetadata.getDocsPath() + '/**');
  files.forEach(file => {
  const extension = path.extname(file);
  if (extension === '.md' || extension === '.markdown') {
  let res;
  try {
- res = readMetadata.processMetadata(file);
+ res = readMetadata.processMetadata(file, docsDir);
  } catch (e) {
  console.error(e);
  process.exit(1);