feat: Allow modifying docs url prefix (#914)

* Allow other routes than /docs in the URL

siteConfig.js has a new mandatory field named *docsRoute* which default
value is 'docs' and that can be customized by the user.

This change will allow users who uses the library to host guides and
tutorials to customize their websites by assign 'docsRoute' values
like 'tutorials' or 'guides'.

Fixes #879

* Make "docsRoute" field optional

* Isolate docsRoute login in getDocsRoute function

* Rename docsRoute to docsUrl

* Run prettier

* Remove old folders

* fix: Restore docusaurus reference link

* fix: Add `docsUrl` param fallback. Refactor multiple function calls

* Fix linting errors

* Update description for docsUrl field

* Reduce redundant calls to getDocsUrl

* Replace a missed use case for `docsUrl` instead of the function call

* Move `getDocsUrl` out from `server/routing.js` to `server/utils.js`

**Why?**
Because `routing.js` is exporting all router RegEx's, and the
`getDocsUrl` suffices more as a util

* WiP: Align leading slashes and fix routing around `docsUrl`

Checklist:
- [x] Added `removeDuplicateLeadingSlashes` util to make sure there is only
one leading slash
- [-] Fix edge cases for routing:
  - [x] `docsUrl: ''`
  - [ ] `docsUrl: '/'`
  - [ ] make it work with languages
  - [ ] make it work with versioning

* Make leading slashes canonical cross routing and generated links

This ensures correct routing for customized `baseUrl` and `docsUrl`.

- Changed all routing functions to take `siteConfig` instead of
`siteConfig.baseUrl`
- Updated tests accordingly

* Alternative fallback for `docsUrl`

* rework/ fix implementation

* cleanup

* refactor and add docs for config props

* fix typo

* fix broken url

v1/lib/server/__tests__/docs.test.js

@@ -66,7 +66,11 @@ const rawContent3 = metadataUtils.extractMetadata(doc3).rawContent;
 const rawContentRefLinks = metadataUtils.extractMetadata(refLinks).rawContent;
 
 describe('mdToHtmlify', () => {
-  const mdToHtml = metadataUtils.mdToHtml(Metadata, '/');
+  const siteConfig = {
+    baseUrl: '/',
+    docsUrl: 'docs',
+  };
+  const mdToHtml = metadataUtils.mdToHtml(Metadata, siteConfig);
 
   test('transform nothing', () => {
     const content1 = docs.mdToHtmlify(
@@ -100,7 +104,7 @@ describe('mdToHtmlify', () => {
         language: 'en',
       },
     };
-    const customMdToHtml = metadataUtils.mdToHtml(customMetadata, '/');
+    const customMdToHtml = metadataUtils.mdToHtml(customMetadata, siteConfig);
     const content3 = docs.mdToHtmlify(
       rawContent3,
       customMdToHtml,

v1/lib/server/__tests__/readMetadata.test.js

@@ -30,7 +30,7 @@ jest.mock('../env', () => ({
   },
 }));
 
-jest.mock(`${process.cwd()}/siteConfig.js`, () => true, {virtual: true});
+jest.mock(`${process.cwd()}/siteConfig.js`, () => ({}), {virtual: true});
 jest.mock(`${process.cwd()}/sidebar.json`, () => true, {virtual: true});
 
 describe('readMetadata', () => {

v1/lib/server/__tests__/routing.test.js

@@ -4,11 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-const routing = require('../routing');
+const routing = require('../routing.js');
 
 describe('Blog routing', () => {
-  const blogRegex = routing.blog('/');
-  const blogRegex2 = routing.blog('/react/');
+  const blogRegex = routing.blog({baseUrl: '/'});
+  const blogRegex2 = routing.blog({baseUrl: '/react/'});
 
   test('valid blog', () => {
     expect('/blog/test.html').toMatch(blogRegex);
@@ -34,8 +34,8 @@ describe('Blog routing', () => {
 });
 
 describe('Docs routing', () => {
-  const docsRegex = routing.docs('/');
-  const docsRegex2 = routing.docs('/reason/');
+  const docsRegex = routing.docs({baseUrl: '/', docsUrl: 'docs'});
+  const docsRegex2 = routing.docs({baseUrl: '/reason/', docsUrl: 'docs'});
 
   test('valid docs', () => {
     expect('/docs/en/test.html').toMatch(docsRegex);
@@ -87,8 +87,8 @@ describe('Dot routing', () => {
 });
 
 describe('Feed routing', () => {
-  const feedRegex = routing.feed('/');
-  const feedRegex2 = routing.feed('/reason/');
+  const feedRegex = routing.feed({baseUrl: '/'});
+  const feedRegex2 = routing.feed({baseUrl: '/reason/'});
 
   test('valid feed url', () => {
     expect('/blog/atom.xml').toMatch(feedRegex);
@@ -137,8 +137,8 @@ describe('Extension-less url routing', () => {
 });
 
 describe('Page routing', () => {
-  const pageRegex = routing.page('/');
-  const pageRegex2 = routing.page('/reason/');
+  const pageRegex = routing.page({baseUrl: '/', docsUrl: 'docs'});
+  const pageRegex2 = routing.page({baseUrl: '/reason/', docsUrl: 'docs'});
 
   test('valid page url', () => {
     expect('/index.html').toMatch(pageRegex);
@@ -164,8 +164,8 @@ describe('Page routing', () => {
 });
 
 describe('Sitemap routing', () => {
-  const sitemapRegex = routing.sitemap('/');
-  const sitemapRegex2 = routing.sitemap('/reason/');
+  const sitemapRegex = routing.sitemap({baseUrl: '/'});
+  const sitemapRegex2 = routing.sitemap({baseUrl: '/reason/'});
 
   test('valid sitemap url', () => {
     expect('/sitemap.xml').toMatch(sitemapRegex);

v1/lib/server/config.js

@@ -0,0 +1,31 @@
+/**
+ * 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 fs = require('fs-extra');
+
+module.exports = function loadConfig(configPath, deleteCache = true) {
+  if (deleteCache) {
+    delete require.cache[configPath];
+  }
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    config = require(configPath); // eslint-disable-line
+  }
+
+  /* Fill default value */
+  const defaultConfig = {
+    customDocsPath: 'docs',
+    docsUrl: 'docs',
+  };
+  Object.keys(defaultConfig).forEach(field => {
+    if (!(field in config)) {
+      config[field] = defaultConfig[field];
+    }
+  });
+
+  return config;
+};

v1/lib/server/docs.js

@@ -5,16 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 const CWD = process.cwd();
-const siteConfig = require(`${CWD}/siteConfig.js`);
 const {join} = require('path');
 const fs = require('fs-extra');
 const React = require('react');
+const loadConfig = require('./config');
+
+const siteConfig = loadConfig(`${CWD}/siteConfig.js`);
 const env = require('./env.js');
 const {renderToStaticMarkupWithDoctype} = require('./renderUtils');
 const readMetadata = require('./readMetadata.js');
 const {insertTOC} = require('../core/toc.js');
 const {getPath} = require('../core/utils.js');
 
+const docsPart = `${siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''}`;
+
 function getFilePath(metadata) {
   if (!metadata) {
     return null;
@@ -125,7 +129,10 @@ function replaceAssetsLink(oldContent) {
     }
     return fencedBlock
       ? line
-      : line.replace(/\]\(assets\//g, `](${siteConfig.baseUrl}docs/assets/`);
+      : line.replace(
+          /\]\(assets\//g,
+          `](${siteConfig.baseUrl}${docsPart}assets/`,
+        );
   });
   return lines.join('\n');
 }
@@ -152,7 +159,10 @@ function getMarkup(rawContent, mdToHtml, metadata) {
 }
 
 function getRedirectMarkup(metadata) {
-  if (!env.translation.enabled || !metadata.permalink.includes('docs/en')) {
+  if (
+    !env.translation.enabled ||
+    !metadata.permalink.includes(`${docsPart}en`)
+  ) {
     return null;
   }
   const Redirect = require('../core/Redirect.js');

v1/lib/server/generate.js

@@ -21,7 +21,8 @@ async function execute() {
   const chalk = require('chalk');
   const Site = require('../core/Site.js');
   const env = require('./env.js');
-  const siteConfig = require(`${CWD}/siteConfig.js`);
+  const loadConfig = require('./config.js');
+  const siteConfig = loadConfig(`${CWD}/siteConfig.js`);
   const translate = require('./translate.js');
   const feed = require('./feed.js');
   const sitemap = require('./sitemap.js');
@@ -68,7 +69,7 @@ async function execute() {
   fs.removeSync(join(CWD, 'build'));
 
   // create html files for all docs by going through all doc ids
-  const mdToHtml = metadataUtils.mdToHtml(Metadata, siteConfig.baseUrl);
+  const mdToHtml = metadataUtils.mdToHtml(Metadata, siteConfig);
   Object.keys(Metadata).forEach(id => {
     const metadata = Metadata[id];
     const file = docs.getFile(metadata);
@@ -85,9 +86,13 @@ async function execute() {
     if (!redirectMarkup) {
       return;
     }
+    const docsPart = `${siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''}`;
     const redirectFile = join(
       buildDir,
-      metadata.permalink.replace('docs/en', 'docs'),
+      metadata.permalink.replace(
+        new RegExp(`^${docsPart}en`),
+        siteConfig.docsUrl,
+      ),
     );
     writeFileAndCreateFolder(redirectFile, redirectMarkup);
   });
@@ -332,7 +337,7 @@ async function execute() {
                 title={ReactComp.title}
                 description={ReactComp.description}
                 metadata={{id: pageID}}>
-                <ReactComp language={language} />
+                <ReactComp config={siteConfig} language={language} />
               </Site>,
             );
             writeFileAndCreateFolder(
@@ -353,7 +358,7 @@ async function execute() {
             config={siteConfig}
             description={ReactComp.description}
             metadata={{id: pageID}}>
-            <ReactComp language={language} />
+            <ReactComp config={siteConfig} language={language} />
           </Site>,
         );
         writeFileAndCreateFolder(
@@ -371,7 +376,7 @@ async function execute() {
             config={siteConfig}
             description={ReactComp.description}
             metadata={{id: pageID}}>
-            <ReactComp language={language} />
+            <ReactComp config={siteConfig} language={language} />
           </Site>,
         );
         writeFileAndCreateFolder(

v1/lib/server/metadataUtils.js

@@ -65,7 +65,8 @@ function extractMetadata(content) {
 
 // mdToHtml is a map from a markdown file name to its html link, used to
 // change relative markdown links that work on GitHub into actual site links
-function mdToHtml(Metadata, baseUrl) {
+function mdToHtml(Metadata, siteConfig) {
+  const {baseUrl, docsUrl} = siteConfig;
   const result = {};
   Object.keys(Metadata).forEach(id => {
     const metadata = Metadata[id];
@@ -73,10 +74,15 @@ function mdToHtml(Metadata, baseUrl) {
       return;
     }
     let htmlLink = baseUrl + metadata.permalink.replace('/next/', '/');
-    if (htmlLink.includes('/docs/en/')) {
-      htmlLink = htmlLink.replace('/docs/en/', '/docs/en/VERSION/');
+
+    const baseDocsPart = `${baseUrl}${docsUrl ? `${docsUrl}/` : ''}`;
+
+    const i18nDocsRegex = new RegExp(`^${baseDocsPart}en/`);
+    const docsRegex = new RegExp(`^${baseDocsPart}`);
+    if (i18nDocsRegex.test(htmlLink)) {
+      htmlLink = htmlLink.replace(i18nDocsRegex, `${baseDocsPart}en/VERSION/`);
     } else {
-      htmlLink = htmlLink.replace('/docs/', '/docs/VERSION/');
+      htmlLink = htmlLink.replace(docsRegex, `${baseDocsPart}VERSION/`);
     }
     result[metadata.source] = htmlLink;
   });

v1/lib/server/readMetadata.js

@@ -16,10 +16,14 @@ const metadataUtils = require('./metadataUtils');
 const env = require('./env.js');
 const blog = require('./blog.js');
 
-const siteConfig = require(`${CWD}/siteConfig.js`);
+const loadConfig = require('./config');
+
+const siteConfig = loadConfig(`${CWD}/siteConfig.js`);
 const versionFallback = require('./versionFallback.js');
 const utils = require('./utils.js');
 
+const docsPart = `${siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''}`;
+
 const SupportedHeaderFields = new Set([
   'id',
   'title',
@@ -166,7 +170,9 @@ function processMetadata(file, refDir) {
     versionPart = 'next/';
   }
 
-  metadata.permalink = `docs/${langPart}${versionPart}${metadata.id}.html`;
+  metadata.permalink = `${docsPart}${langPart}${versionPart}${
+    metadata.id
+  }.html`;
 
   // change ids previous, next
   metadata.localized_id = metadata.id;
@@ -238,18 +244,24 @@ function generateMetadataDocs() {
           baseMetadata.id = baseMetadata.id
             .toString()
             .replace(/^en-/, `${currentLanguage}-`);
-          if (baseMetadata.permalink)
+          if (baseMetadata.permalink) {
             baseMetadata.permalink = baseMetadata.permalink
               .toString()
-              .replace(/^docs\/en\//, `docs/${currentLanguage}/`);
-          if (baseMetadata.next)
+              .replace(
+                new RegExp(`^${docsPart}en/`),
+                `${docsPart}${currentLanguage}/`,
+              );
+          }
+          if (baseMetadata.next) {
             baseMetadata.next = baseMetadata.next
               .toString()
               .replace(/^en-/, `${currentLanguage}-`);
-          if (baseMetadata.previous)
+          }
+          if (baseMetadata.previous) {
             baseMetadata.previous = baseMetadata.previous
               .toString()
               .replace(/^en-/, `${currentLanguage}-`);
+          }
           baseMetadata.language = currentLanguage;
           defaultMetadatas[baseMetadata.id] = baseMetadata;
         });

v1/lib/server/routing.js

@@ -4,35 +4,44 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-function blog(baseUrl) {
-  return new RegExp(`^${baseUrl}blog/.*html$`);
+function blog(siteConfig) {
+  return new RegExp(`^${siteConfig.baseUrl}blog/.*html$`);
 }
 
-function docs(baseUrl) {
-  return new RegExp(`^${baseUrl}docs/.*html$`);
+function docs(siteConfig) {
+  const docsPart = `${siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''}`;
+  return new RegExp(`^${siteConfig.baseUrl}${docsPart}.*html$`);
 }
 
 function dotfiles() {
   return /(?!.*html$)^\/.*\.[^\n/]+$/;
 }
 
-function feed(baseUrl) {
-  return new RegExp(`^${baseUrl}blog/(feed.xml|atom.xml)$`);
+function feed(siteConfig) {
+  return new RegExp(`^${siteConfig.baseUrl}blog/(feed.xml|atom.xml)$`);
 }
 
 function noExtension() {
   return /\/[^.]*\/?$/;
 }
 
-function page(baseUrl) {
+function page(siteConfig) {
   const gr = regex => regex.toString().replace(/(^\/|\/$)/gm, '');
+
+  if (siteConfig.docsUrl === '') {
+    return new RegExp(
+      `(?!${gr(blog(siteConfig))})^${siteConfig.baseUrl}.*.html$`,
+    );
+  }
   return new RegExp(
-    `(?!${gr(docs(baseUrl))}|${gr(blog(baseUrl))})^${baseUrl}.*.html$`,
+    `(?!${gr(blog(siteConfig))}|${gr(docs(siteConfig))})^${
+      siteConfig.baseUrl
+    }.*.html$`,
   );
 }
 
-function sitemap(baseUrl) {
-  return new RegExp(`^${baseUrl}sitemap.xml$`);
+function sitemap(siteConfig) {
+  return new RegExp(`^${siteConfig.baseUrl}sitemap.xml$`);
 }
 
 module.exports = {

v1/lib/server/server.js

@@ -27,6 +27,7 @@ function execute(port) {
   const feed = require('./feed');
   const sitemap = require('./sitemap');
   const routing = require('./routing');
+  const loadConfig = require('./config');
   const CWD = process.cwd();
   const join = path.join;
   const sep = path.sep;
@@ -76,12 +77,9 @@ function execute(port) {
   }
 
   function reloadSiteConfig() {
-    removeModuleAndChildrenFromCache(join(CWD, 'siteConfig.js'));
-    siteConfig = require(join(CWD, 'siteConfig.js'));
-
-    if (siteConfig.highlight && siteConfig.highlight.hljs) {
-      siteConfig.highlight.hljs(require('highlight.js'));
-    }
+    const siteConfigPath = join(CWD, 'siteConfig.js');
+    removeModuleAndChildrenFromCache(siteConfigPath);
+    siteConfig = loadConfig(siteConfigPath);
   }
 
   function requestFile(url, res, notFoundCallback) {
@@ -109,12 +107,13 @@ function execute(port) {
 
   const app = express();
 
-  app.get(routing.docs(siteConfig.baseUrl), (req, res, next) => {
+  app.get(routing.docs(siteConfig), (req, res, next) => {
     const url = decodeURI(req.path.toString().replace(siteConfig.baseUrl, ''));
     const metadata =
       Metadata[
         Object.keys(Metadata).find(id => Metadata[id].permalink === url)
       ];
+
     const file = docs.getFile(metadata);
     if (!file) {
       next();
@@ -122,11 +121,11 @@ function execute(port) {
     }
     const rawContent = metadataUtils.extractMetadata(file).rawContent;
     removeModuleAndChildrenFromCache('../core/DocsLayout.js');
-    const mdToHtml = metadataUtils.mdToHtml(Metadata, siteConfig.baseUrl);
+    const mdToHtml = metadataUtils.mdToHtml(Metadata, siteConfig);
     res.send(docs.getMarkup(rawContent, mdToHtml, metadata));
   });
 
-  app.get(routing.sitemap(siteConfig.baseUrl), (req, res) => {
+  app.get(routing.sitemap(siteConfig), (req, res) => {
     sitemap((err, xml) => {
       if (err) {
         res.status(500).send('Sitemap error');
@@ -137,7 +136,7 @@ function execute(port) {
     });
   });
 
-  app.get(routing.feed(siteConfig.baseUrl), (req, res, next) => {
+  app.get(routing.feed(siteConfig), (req, res, next) => {
     res.set('Content-Type', 'application/rss+xml');
     const file = req.path
       .toString()
@@ -151,7 +150,7 @@ function execute(port) {
     next();
   });
 
-  app.get(routing.blog(siteConfig.baseUrl), (req, res, next) => {
+  app.get(routing.blog(siteConfig), (req, res, next) => {
     // Regenerate the blog metadata in case it has changed. Consider improving
     // this to regenerate on file save rather than on page request.
     reloadMetadataBlog();
@@ -177,7 +176,7 @@ function execute(port) {
     }
   });
 
-  app.get(routing.page(siteConfig.baseUrl), (req, res, next) => {
+  app.get(routing.page(siteConfig), (req, res, next) => {
     // Look for user-provided HTML file first.
     let htmlFile = req.path.toString().replace(siteConfig.baseUrl, '');
     htmlFile = join(CWD, 'pages', htmlFile);
@@ -232,6 +231,7 @@ function execute(port) {
         language = parts[i];
       }
     }
+
     let englishFile = join(CWD, 'pages', file);
     if (language && language !== 'en') {
       englishFile = englishFile.replace(sep + language + sep, `${sep}en${sep}`);
@@ -272,7 +272,7 @@ function execute(port) {
           title={ReactComp.title}
           description={ReactComp.description}
           metadata={{id: path.basename(userFile, '.js')}}>
-          <ReactComp language={language} />
+          <ReactComp config={siteConfig} language={language} />
         </Site>,
       );
 
@@ -339,7 +339,9 @@ function execute(port) {
 
   // serve static assets from these locations
   app.use(
-    `${siteConfig.baseUrl}docs/assets`,
+    `${siteConfig.baseUrl}${
+      siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''
+    }assets`,
     express.static(join(CWD, '..', readMetadata.getDocsPath(), 'assets')),
   );
   app.use(

v1/lib/server/sitemap.js

@@ -14,7 +14,9 @@ const CWD = process.cwd();
 const sitemap = require('sitemap');
 const utils = require('../core/utils');
 
-const siteConfig = require(`${CWD}/siteConfig.js`);
+const loadConfig = require('./config');
+
+const siteConfig = loadConfig(`${CWD}/siteConfig.js`);
 
 const readMetadata = require('./readMetadata.js');
 
@@ -70,8 +72,12 @@ module.exports = function(callback) {
     .forEach(key => {
       const doc = Metadata[key];
       const docUrl = utils.getPath(doc.permalink, siteConfig.cleanUrl);
+      const docsPart = `${siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''}`;
       const links = enabledLanguages.map(lang => {
-        const langUrl = docUrl.replace('docs/en/', `docs/${lang.tag}/`);
+        const langUrl = docUrl.replace(
+          new RegExp(`^${docsPart}en/`),
+          `${docsPart}${lang.tag}/`,
+        );
         return {lang: lang.tag, url: langUrl};
       });
       urls.push({

v1/lib/server/versionFallback.js

@@ -14,8 +14,9 @@ const metadataUtils = require('./metadataUtils');
 
 const env = require('./env.js');
 const utils = require('./utils.js');
+const loadConfig = require('./config');
 
-const siteConfig = require(`${CWD}/siteConfig.js`);
+const siteConfig = loadConfig(`${CWD}/siteConfig.js`);
 
 const ENABLE_TRANSLATION = fs.existsSync(`${CWD}/languages.js`);
 
@@ -187,14 +188,16 @@ function processVersionMetadata(file, version, useVersion, language) {
 
   const latestVersion = versions[0];
 
+  const docsPart = `${siteConfig.docsUrl ? `${siteConfig.docsUrl}/` : ''}`;
+  const versionPart = `${version !== latestVersion ? `${version}/` : ''}`;
   if (!ENABLE_TRANSLATION && !siteConfig.useEnglishUrl) {
-    metadata.permalink = `docs/${
-      version !== latestVersion ? `${version}/` : ''
-    }${metadata.original_id}.html`;
+    metadata.permalink = `${docsPart}${versionPart}${
+      metadata.original_id
+    }.html`;
   } else {
-    metadata.permalink = `docs/${language}/${
-      version !== latestVersion ? `${version}/` : ''
-    }${metadata.original_id}.html`;
+    metadata.permalink = `${docsPart}${language}/${versionPart}${
+      metadata.original_id
+    }.html`;
   }
   metadata.id = metadata.id.replace(
     `version-${useVersion}-`,