feat: allow custom docsUrl & custom permalink

lib/load/config.js

@@ -24,7 +24,9 @@ module.exports = function loadConfig(siteDir, deleteCache = true) {
     'highlight',
     'markdownPlugins',
     'configureWebpack',
-    'chainWebpack'
+    'chainWebpack',
+    'docsUrl',
+    'customFields'
   ];
   const missingFields = requiredFields.filter(field => !config[field]);
   if (missingFields && missingFields.length > 0) {
@@ -33,8 +35,16 @@ module.exports = function loadConfig(siteDir, deleteCache = true) {
     );
   }
 
+  /* 
+    User's own array of custom fields, 
+    e.g: if they want to include some field so they can access it later from `props.siteConfig`
+  */
+  const {customFields = []} = config;
+
+  /* We don't allow useless/ not meaningful field */
+  const allowedFields = [...requiredFields, ...optionalFields, ...customFields];
   const uselessFields = Object.keys(config).filter(
-    field => ![...requiredFields, ...optionalFields].includes(field)
+    field => !allowedFields.includes(field)
   );
   if (uselessFields && uselessFields.length > 0) {
     throw new Error(

lib/load/docs/index.js

@@ -5,7 +5,7 @@ const loadSidebars = require('./sidebars');
 const processMetadata = require('./metadata');
 const {getSubFolder, idx} = require('../utils');
 
-async function loadDocs({siteDir, docsDir, env}) {
+async function loadDocs({siteDir, docsDir, env, siteConfig}) {
   // @tested - load all sidebars including versioned sidebars
   const allSidebars = loadSidebars({siteDir, env});
 
@@ -18,8 +18,7 @@ async function loadDocs({siteDir, docsDir, env}) {
     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 defaultLangTag = idx(env, ['translation', 'defaultLanguage', 'tag']);
   const versioningEnabled = idx(env, ['versioning', 'enabled']);
   const versions =
     (versioningEnabled && idx(env, ['versioning', 'versions'])) || [];
@@ -43,7 +42,13 @@ async function loadDocs({siteDir, docsDir, env}) {
         throw new Error(`You cannot have a folder named 'docs/${subFolder}/'`);
       }
 
-      const metadata = await processMetadata(source, docsDir, env, order);
+      const metadata = await processMetadata(
+        source,
+        docsDir,
+        env,
+        order,
+        siteConfig
+      );
       metadatas[metadata.id] = metadata;
     })
   );
@@ -57,7 +62,7 @@ async function loadDocs({siteDir, docsDir, env}) {
     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
+        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);
@@ -68,7 +73,13 @@ async function loadDocs({siteDir, docsDir, env}) {
         return;
       }
 
-      const metadata = await processMetadata(source, translatedDir, env, order);
+      const metadata = await processMetadata(
+        source,
+        translatedDir,
+        env,
+        order,
+        siteConfig
+      );
       metadatas[metadata.id] = metadata;
     })
   );
@@ -80,7 +91,13 @@ async function loadDocs({siteDir, docsDir, env}) {
   });
   await Promise.all(
     versionedFiles.map(async source => {
-      const metadata = await processMetadata(source, versionedDir, env, order);
+      const metadata = await processMetadata(
+        source,
+        versionedDir,
+        env,
+        order,
+        siteConfig
+      );
       metadatas[metadata.id] = metadata;
     })
   );
@@ -88,22 +105,16 @@ async function loadDocs({siteDir, docsDir, env}) {
   /*
    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';
-      }
+  Object.keys(metadatas).forEach(currentID => {
+    const previousID = idx(metadatas, [currentID, 'previous']);
+    if (previousID) {
+      const previousTitle = idx(metadatas, [previousID, 'title']);
+      metadatas[currentID].previous_title = previousTitle || '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';
-      }
+    const nextID = idx(metadatas, [currentID, 'next']);
+    if (nextID) {
+      const nextTitle = idx(metadatas, [nextID, 'title']);
+      metadatas[currentID].next_title = nextTitle || 'Next';
     }
   });
 

lib/load/docs/metadata.js

@@ -36,14 +36,17 @@ function getVersion(filepath, refDir, env) {
   return undefined;
 }
 
-module.exports = async function processMetadata(source, refDir, env, order) {
+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);
 
-  /* source (relative to refDir) */
-  metadata.source = source;
-
   /* default id is the file name */
   if (!metadata.id) {
     metadata.id = path.basename(source, path.extname(source));
@@ -63,11 +66,9 @@ module.exports = async function processMetadata(source, refDir, env, order) {
   const langPart = (language && `${language}/`) || '';
 
   /* version */
+  const defaultLangTag = idx(env, ['translation', 'defaultLanguage', 'tag']);
   let versionRefDir = refDir;
-  if (
-    language &&
-    language !== idx(env, ['translation', 'defaultLanguage', 'tag'])
-  ) {
+  if (language && language !== defaultLangTag) {
     versionRefDir = path.join(refDir, language);
   }
   const version = getVersion(filepath, versionRefDir, env);
@@ -104,8 +105,37 @@ module.exports = async function processMetadata(source, refDir, env, order) {
     }
   }
 
-  /* Build the permalink without baseUrl */
-  metadata.permalink = `docs/${langPart}${versionPart}${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 = 'docs'} = siteConfig;
+
+  /* 
+    if user has own custom permalink defined in frontmatter
+    e.g: :baseUrl:docsUrl/:langPart:versionPartendiliey/:id
+  */
+  if (metadata.permalink) {
+    metadata.permalink = 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') {

lib/load/index.js

@@ -20,7 +20,7 @@ module.exports = async function load(siteDir) {
     '..',
     siteConfig.customDocsPath || 'docs'
   );
-  const docsData = await loadDocs({siteDir, docsDir, env});
+  const docsData = await loadDocs({siteDir, docsDir, env, siteConfig});
   await generate(
     'docsData.js',
     `export default ${JSON.stringify(docsData, null, 2)};`

lib/load/routes.js

@@ -1,30 +1,12 @@
-const {idx} = require('./utils');
-
-async function genRoutesConfig({
-  docsData = {},
-  pagesData = [],
-  env,
-  siteConfig
-}) {
+async function genRoutesConfig({docsData = {}, pagesData = []}) {
   function genDocsRoute(metadata) {
-    const {permalink, source, version, language} = metadata;
-    const defaultLanguage = idx(env, ['translation', 'defaultLanguage']);
-    let importPath = `@docs/${source}`;
-    if (language && language !== defaultLanguage.tag) {
-      importPath = `@translated_docs/${source}`;
-    } else if (version && version !== 'next') {
-      importPath = `@versioned_docs/${source}`;
-    }
-
-    const {baseUrl} = siteConfig;
-    const docsPath = `${baseUrl}${permalink}`;
-
+    const {permalink, source} = metadata;
     return `
   {
-    path: ${JSON.stringify(docsPath)},
+    path: ${JSON.stringify(permalink)},
     exact: true,
     component: Loadable({
-      loader: () => import(${JSON.stringify(importPath)}),
+      loader: () => import(${JSON.stringify(source)}),
       loading: Loading,
       render(loaded, props) {
         let Content = loaded.default;