diff --git a/lib/load/config.js b/lib/load/config.js
index 618189db89..1ef863e889 100644
--- a/lib/load/config.js
+++ b/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(
diff --git a/lib/load/docs/index.js b/lib/load/docs/index.js
index ea061c052d..6c4fcef18a 100644
--- a/lib/load/docs/index.js
+++ b/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';
     }
   });
 
diff --git a/lib/load/docs/metadata.js b/lib/load/docs/metadata.js
index 550303f427..82a0e1b596 100644
--- a/lib/load/docs/metadata.js
+++ b/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') {
diff --git a/lib/load/index.js b/lib/load/index.js
index 6e2d381ac7..f6c6190ae3 100644
--- a/lib/load/index.js
+++ b/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)};`
diff --git a/lib/load/routes.js b/lib/load/routes.js
index 42193e0631..d615960652 100644
--- a/lib/load/routes.js
+++ b/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;
diff --git a/test/__fixtures__/docs/permalink.md b/test/__fixtures__/docs/permalink.md
new file mode 100644
index 0000000000..3caa3d5d95
--- /dev/null
+++ b/test/__fixtures__/docs/permalink.md
@@ -0,0 +1,7 @@
+---
+id: permalink
+title: Permalink
+permalink: :baseUrl:docsUrl/:langPart:versionPartendiliey/:id
+---
+
+This has a different permalink
\ No newline at end of file
diff --git a/test/load/__fixtures__/wrong-site/siteConfig.js b/test/load/__fixtures__/wrong-site/siteConfig.js
index c84b9e4594..49d6f120be 100644
--- a/test/load/__fixtures__/wrong-site/siteConfig.js
+++ b/test/load/__fixtures__/wrong-site/siteConfig.js
@@ -1,10 +1,11 @@
-module.exports = {
-  title: 'Hello',
-  tagline: 'Hello World',
-  organizationName: 'endiliey',
-  projectName: 'hello',
-  baseUrl: '/',
-  useLessField: 'what',
-  superman: 'lol',
-  admin: 'endi'
-};
+module.exports = {
+  title: 'Hello',
+  tagline: 'Hello World',
+  organizationName: 'endiliey',
+  projectName: 'hello',
+  baseUrl: '/',
+  useLessField: 'what',
+  superman: 'lol',
+  admin: 'endi',
+  customFields: ['admin', 'superman']
+};
diff --git a/test/load/config.test.js b/test/load/config.test.js
index 817346229f..41d1ed0fc6 100644
--- a/test/load/config.test.js
+++ b/test/load/config.test.js
@@ -29,7 +29,7 @@ describe('loadConfig', () => {
     expect(() => {
       loadConfig(siteDir);
     }).toThrowErrorMatchingInlineSnapshot(
-      `"useLessField, superman, admin fields are useless in siteConfig.js"`
+      `"useLessField fields are useless in siteConfig.js"`
     );
   });
 
diff --git a/test/load/docs/__snapshots__/index.test.js.snap b/test/load/docs/__snapshots__/index.test.js.snap
index 4fc6f4a744..4bbac6aa0c 100644
--- a/test/load/docs/__snapshots__/index.test.js.snap
+++ b/test/load/docs/__snapshots__/index.test.js.snap
@@ -6,8 +6,8 @@ Object {
     "id": "foo/bar",
     "language": undefined,
     "localized_id": "foo/bar",
-    "permalink": "docs/foo/bar",
-    "source": "foo/bar.md",
+    "permalink": "/docs/foo/bar",
+    "source": "@docs/foo/bar.md",
     "title": "Bar",
     "version": undefined,
   },
@@ -15,8 +15,8 @@ Object {
     "id": "foo/baz",
     "language": undefined,
     "localized_id": "foo/baz",
-    "permalink": "docs/foo/baz",
-    "source": "foo/baz.md",
+    "permalink": "/docs/foo/baz",
+    "source": "@docs/foo/baz.md",
     "title": "baz",
     "version": undefined,
   },
@@ -24,11 +24,20 @@ Object {
     "id": "hello",
     "language": undefined,
     "localized_id": "hello",
-    "permalink": "docs/hello",
-    "source": "hello.md",
+    "permalink": "/docs/hello",
+    "source": "@docs/hello.md",
     "title": "Hello, World !",
     "version": undefined,
   },
+  "permalink": Object {
+    "id": "permalink",
+    "language": undefined,
+    "localized_id": "permalink",
+    "permalink": "/docs/endiliey/permalink",
+    "source": "@docs/permalink.md",
+    "title": "Permalink",
+    "version": undefined,
+  },
 }
 `;
 
@@ -38,8 +47,8 @@ Object {
     "id": "en-foo/bar",
     "language": "en",
     "localized_id": "en-foo/bar",
-    "permalink": "docs/en/foo/bar",
-    "source": "foo/bar.md",
+    "permalink": "/docs/en/foo/bar",
+    "source": "@docs/foo/bar.md",
     "title": "Bar",
     "version": undefined,
   },
@@ -47,8 +56,8 @@ Object {
     "id": "en-foo/baz",
     "language": "en",
     "localized_id": "en-foo/baz",
-    "permalink": "docs/en/foo/baz",
-    "source": "foo/baz.md",
+    "permalink": "/docs/en/foo/baz",
+    "source": "@docs/foo/baz.md",
     "title": "baz",
     "version": undefined,
   },
@@ -56,17 +65,26 @@ Object {
     "id": "en-hello",
     "language": "en",
     "localized_id": "en-hello",
-    "permalink": "docs/en/hello",
-    "source": "hello.md",
+    "permalink": "/docs/en/hello",
+    "source": "@docs/hello.md",
     "title": "Hello, World !",
     "version": undefined,
   },
+  "en-permalink": Object {
+    "id": "en-permalink",
+    "language": "en",
+    "localized_id": "en-permalink",
+    "permalink": "/docs/en/endiliey/permalink",
+    "source": "@docs/permalink.md",
+    "title": "Permalink",
+    "version": undefined,
+  },
   "ko-foo/bar": Object {
     "id": "ko-foo/bar",
     "language": "ko",
     "localized_id": "ko-foo/bar",
-    "permalink": "docs/ko/foo/bar",
-    "source": "ko/foo/bar.md",
+    "permalink": "/docs/ko/foo/bar",
+    "source": "@translated_docs/ko/foo/bar.md",
     "title": "Bar",
     "version": undefined,
   },
@@ -74,8 +92,8 @@ Object {
     "id": "ko-foo/baz",
     "language": "ko",
     "localized_id": "ko-foo/baz",
-    "permalink": "docs/ko/foo/baz",
-    "source": "ko/foo/baz.md",
+    "permalink": "/docs/ko/foo/baz",
+    "source": "@translated_docs/ko/foo/baz.md",
     "title": "baz",
     "version": undefined,
   },
@@ -83,8 +101,8 @@ Object {
     "id": "ko-hello",
     "language": "ko",
     "localized_id": "ko-hello",
-    "permalink": "docs/ko/hello",
-    "source": "ko/hello.md",
+    "permalink": "/docs/ko/hello",
+    "source": "@translated_docs/ko/hello.md",
     "title": "Hello, World !",
     "version": undefined,
   },
@@ -97,8 +115,8 @@ Object {
     "id": "en-foo/bar",
     "language": "en",
     "localized_id": "en-foo/bar",
-    "permalink": "docs/en/next/foo/bar",
-    "source": "foo/bar.md",
+    "permalink": "/docs/en/next/foo/bar",
+    "source": "@docs/foo/bar.md",
     "title": "Bar",
     "version": "next",
   },
@@ -106,8 +124,8 @@ Object {
     "id": "en-foo/baz",
     "language": "en",
     "localized_id": "en-foo/baz",
-    "permalink": "docs/en/next/foo/baz",
-    "source": "foo/baz.md",
+    "permalink": "/docs/en/next/foo/baz",
+    "source": "@docs/foo/baz.md",
     "title": "baz",
     "version": "next",
   },
@@ -115,17 +133,26 @@ Object {
     "id": "en-hello",
     "language": "en",
     "localized_id": "en-hello",
-    "permalink": "docs/en/next/hello",
-    "source": "hello.md",
+    "permalink": "/docs/en/next/hello",
+    "source": "@docs/hello.md",
     "title": "Hello, World !",
     "version": "next",
   },
+  "en-permalink": Object {
+    "id": "en-permalink",
+    "language": "en",
+    "localized_id": "en-permalink",
+    "permalink": "/docs/en/next/endiliey/permalink",
+    "source": "@docs/permalink.md",
+    "title": "Permalink",
+    "version": "next",
+  },
   "en-version-1.0.0-foo/bar": Object {
     "id": "en-version-1.0.0-foo/bar",
     "language": "en",
     "localized_id": "en-version-1.0.0-foo/bar",
-    "permalink": "docs/en/1.0.0/foo/bar",
-    "source": "version-1.0.0/foo/bar.md",
+    "permalink": "/docs/en/1.0.0/foo/bar",
+    "source": "@versioned_docs/version-1.0.0/foo/bar.md",
     "title": "Bar",
     "version": "1.0.0",
   },
@@ -133,8 +160,8 @@ Object {
     "id": "en-version-1.0.0-foo/baz",
     "language": "en",
     "localized_id": "en-version-1.0.0-foo/baz",
-    "permalink": "docs/en/1.0.0/foo/baz",
-    "source": "version-1.0.0/foo/baz.md",
+    "permalink": "/docs/en/1.0.0/foo/baz",
+    "source": "@versioned_docs/version-1.0.0/foo/baz.md",
     "title": "Baz",
     "version": "1.0.0",
   },
@@ -142,8 +169,8 @@ Object {
     "id": "en-version-1.0.0-hello",
     "language": "en",
     "localized_id": "en-version-1.0.0-hello",
-    "permalink": "docs/en/1.0.0/hello",
-    "source": "version-1.0.0/hello.md",
+    "permalink": "/docs/en/1.0.0/hello",
+    "source": "@versioned_docs/version-1.0.0/hello.md",
     "title": "Hello, World !",
     "version": "1.0.0",
   },
@@ -151,8 +178,8 @@ Object {
     "id": "en-version-1.0.1-foo/bar",
     "language": "en",
     "localized_id": "en-version-1.0.1-foo/bar",
-    "permalink": "docs/en/foo/bar",
-    "source": "version-1.0.1/foo/bar.md",
+    "permalink": "/docs/en/foo/bar",
+    "source": "@versioned_docs/version-1.0.1/foo/bar.md",
     "title": "Bar",
     "version": "1.0.1",
   },
@@ -160,8 +187,8 @@ Object {
     "id": "en-version-1.0.1-foo/baz",
     "language": "en",
     "localized_id": "en-version-1.0.1-foo/baz",
-    "permalink": "docs/en/foo/baz",
-    "source": "version-1.0.1/foo/baz.md",
+    "permalink": "/docs/en/foo/baz",
+    "source": "@versioned_docs/version-1.0.1/foo/baz.md",
     "title": "Baz",
     "version": "1.0.1",
   },
@@ -169,8 +196,8 @@ Object {
     "id": "en-version-1.0.1-hello",
     "language": "en",
     "localized_id": "en-version-1.0.1-hello",
-    "permalink": "docs/en/hello",
-    "source": "version-1.0.1/hello.md",
+    "permalink": "/docs/en/hello",
+    "source": "@versioned_docs/version-1.0.1/hello.md",
     "title": "Hello, World !",
     "version": "1.0.1",
   },
@@ -178,8 +205,8 @@ Object {
     "id": "ko-version-1.0.0-foo/bar",
     "language": "ko",
     "localized_id": "ko-version-1.0.0-foo/bar",
-    "permalink": "docs/ko/1.0.0/foo/bar",
-    "source": "ko/version-1.0.0/foo/bar.md",
+    "permalink": "/docs/ko/1.0.0/foo/bar",
+    "source": "@translated_docs/ko/version-1.0.0/foo/bar.md",
     "title": "Bar",
     "version": "1.0.0",
   },
@@ -187,8 +214,8 @@ Object {
     "id": "ko-version-1.0.0-foo/baz",
     "language": "ko",
     "localized_id": "ko-version-1.0.0-foo/baz",
-    "permalink": "docs/ko/1.0.0/foo/baz",
-    "source": "ko/version-1.0.0/foo/baz.md",
+    "permalink": "/docs/ko/1.0.0/foo/baz",
+    "source": "@translated_docs/ko/version-1.0.0/foo/baz.md",
     "title": "baz",
     "version": "1.0.0",
   },
@@ -196,8 +223,8 @@ Object {
     "id": "ko-version-1.0.0-hello",
     "language": "ko",
     "localized_id": "ko-version-1.0.0-hello",
-    "permalink": "docs/ko/1.0.0/hello",
-    "source": "ko/version-1.0.0/hello.md",
+    "permalink": "/docs/ko/1.0.0/hello",
+    "source": "@translated_docs/ko/version-1.0.0/hello.md",
     "title": "Hello, World !",
     "version": "1.0.0",
   },
@@ -205,8 +232,8 @@ Object {
     "id": "ko-version-1.0.1-foo/bar",
     "language": "ko",
     "localized_id": "ko-version-1.0.1-foo/bar",
-    "permalink": "docs/ko/foo/bar",
-    "source": "ko/version-1.0.1/foo/bar.md",
+    "permalink": "/docs/ko/foo/bar",
+    "source": "@translated_docs/ko/version-1.0.1/foo/bar.md",
     "title": "Bar",
     "version": "1.0.1",
   },
@@ -214,8 +241,8 @@ Object {
     "id": "ko-version-1.0.1-foo/baz",
     "language": "ko",
     "localized_id": "ko-version-1.0.1-foo/baz",
-    "permalink": "docs/ko/foo/baz",
-    "source": "ko/version-1.0.1/foo/baz.md",
+    "permalink": "/docs/ko/foo/baz",
+    "source": "@translated_docs/ko/version-1.0.1/foo/baz.md",
     "title": "baz",
     "version": "1.0.1",
   },
@@ -223,8 +250,8 @@ Object {
     "id": "ko-version-1.0.1-hello",
     "language": "ko",
     "localized_id": "ko-version-1.0.1-hello",
-    "permalink": "docs/ko/hello",
-    "source": "ko/version-1.0.1/hello.md",
+    "permalink": "/docs/ko/hello",
+    "source": "@translated_docs/ko/version-1.0.1/hello.md",
     "title": "Hello, World !",
     "version": "1.0.1",
   },
@@ -237,8 +264,8 @@ Object {
     "id": "foo/bar",
     "language": undefined,
     "localized_id": "foo/bar",
-    "permalink": "docs/next/foo/bar",
-    "source": "foo/bar.md",
+    "permalink": "/docs/next/foo/bar",
+    "source": "@docs/foo/bar.md",
     "title": "Bar",
     "version": "next",
   },
@@ -246,8 +273,8 @@ Object {
     "id": "foo/baz",
     "language": undefined,
     "localized_id": "foo/baz",
-    "permalink": "docs/next/foo/baz",
-    "source": "foo/baz.md",
+    "permalink": "/docs/next/foo/baz",
+    "source": "@docs/foo/baz.md",
     "title": "baz",
     "version": "next",
   },
@@ -255,11 +282,20 @@ Object {
     "id": "hello",
     "language": undefined,
     "localized_id": "hello",
-    "permalink": "docs/next/hello",
-    "source": "hello.md",
+    "permalink": "/docs/next/hello",
+    "source": "@docs/hello.md",
     "title": "Hello, World !",
     "version": "next",
   },
+  "permalink": Object {
+    "id": "permalink",
+    "language": undefined,
+    "localized_id": "permalink",
+    "permalink": "/docs/next/endiliey/permalink",
+    "source": "@docs/permalink.md",
+    "title": "Permalink",
+    "version": "next",
+  },
   "version-1.0.0-foo/bar": Object {
     "category": "Test",
     "id": "version-1.0.0-foo/bar",
@@ -268,9 +304,9 @@ Object {
     "next": "version-1.0.0-foo/baz",
     "next_id": "version-1.0.0-foo/baz",
     "next_title": "Baz",
-    "permalink": "docs/1.0.0/foo/bar",
+    "permalink": "/docs/1.0.0/foo/bar",
     "sidebar": "version-1.0.0-docs",
-    "source": "version-1.0.0/foo/bar.md",
+    "source": "@versioned_docs/version-1.0.0/foo/bar.md",
     "title": "Bar",
     "version": "1.0.0",
   },
@@ -282,12 +318,12 @@ Object {
     "next": "version-1.0.0-hello",
     "next_id": "version-1.0.0-hello",
     "next_title": "Hello, World !",
-    "permalink": "docs/1.0.0/foo/baz",
+    "permalink": "/docs/1.0.0/foo/baz",
     "previous": "version-1.0.0-foo/bar",
     "previous_id": "version-1.0.0-foo/bar",
     "previous_title": "Bar",
     "sidebar": "version-1.0.0-docs",
-    "source": "version-1.0.0/foo/baz.md",
+    "source": "@versioned_docs/version-1.0.0/foo/baz.md",
     "title": "Baz",
     "version": "1.0.0",
   },
@@ -296,12 +332,12 @@ Object {
     "id": "version-1.0.0-hello",
     "language": undefined,
     "localized_id": "version-1.0.0-hello",
-    "permalink": "docs/1.0.0/hello",
+    "permalink": "/docs/1.0.0/hello",
     "previous": "version-1.0.0-foo/baz",
     "previous_id": "version-1.0.0-foo/baz",
     "previous_title": "Baz",
     "sidebar": "version-1.0.0-docs",
-    "source": "version-1.0.0/hello.md",
+    "source": "@versioned_docs/version-1.0.0/hello.md",
     "title": "Hello, World !",
     "version": "1.0.0",
   },
@@ -313,9 +349,9 @@ Object {
     "next": "version-1.0.1-foo/baz",
     "next_id": "version-1.0.1-foo/baz",
     "next_title": "Baz",
-    "permalink": "docs/foo/bar",
+    "permalink": "/docs/foo/bar",
     "sidebar": "version-1.0.1-docs",
-    "source": "version-1.0.1/foo/bar.md",
+    "source": "@versioned_docs/version-1.0.1/foo/bar.md",
     "title": "Bar",
     "version": "1.0.1",
   },
@@ -327,12 +363,12 @@ Object {
     "next": "version-1.0.1-hello",
     "next_id": "version-1.0.1-hello",
     "next_title": "Hello, World !",
-    "permalink": "docs/foo/baz",
+    "permalink": "/docs/foo/baz",
     "previous": "version-1.0.1-foo/bar",
     "previous_id": "version-1.0.1-foo/bar",
     "previous_title": "Bar",
     "sidebar": "version-1.0.1-docs",
-    "source": "version-1.0.1/foo/baz.md",
+    "source": "@versioned_docs/version-1.0.1/foo/baz.md",
     "title": "Baz",
     "version": "1.0.1",
   },
@@ -341,12 +377,12 @@ Object {
     "id": "version-1.0.1-hello",
     "language": undefined,
     "localized_id": "version-1.0.1-hello",
-    "permalink": "docs/hello",
+    "permalink": "/docs/hello",
     "previous": "version-1.0.1-foo/baz",
     "previous_id": "version-1.0.1-foo/baz",
     "previous_title": "Baz",
     "sidebar": "version-1.0.1-docs",
-    "source": "version-1.0.1/hello.md",
+    "source": "@versioned_docs/version-1.0.1/hello.md",
     "title": "Hello, World !",
     "version": "1.0.1",
   },
diff --git a/test/load/docs/index.test.js b/test/load/docs/index.test.js
index 6b813794b8..a2fb6e47a7 100644
--- a/test/load/docs/index.test.js
+++ b/test/load/docs/index.test.js
@@ -4,29 +4,29 @@ import loadSetup from '../../loadSetup';
 describe('loadDocs', () => {
   test('simple website', async () => {
     const props = await loadSetup('simple');
-    const {siteDir, docsDir, env} = props;
-    const docsData = await loadDocs({siteDir, docsDir, env});
+    const {siteDir, docsDir, env, siteConfig} = props;
+    const docsData = await loadDocs({siteDir, docsDir, env, siteConfig});
     expect(docsData).toMatchSnapshot();
   });
 
   test('versioned website', async () => {
     const props = await loadSetup('versioned');
-    const {siteDir, docsDir, env} = props;
-    const docsData = await loadDocs({siteDir, docsDir, env});
+    const {siteDir, docsDir, env, siteConfig} = props;
+    const docsData = await loadDocs({siteDir, docsDir, env, siteConfig});
     expect(docsData).toMatchSnapshot();
   });
 
   test('versioned & translated website', async () => {
     const props = await loadSetup('transversioned');
-    const {siteDir, docsDir, env} = props;
-    const docsData = await loadDocs({siteDir, docsDir, env});
+    const {siteDir, docsDir, env, siteConfig} = props;
+    const docsData = await loadDocs({siteDir, docsDir, env, siteConfig});
     expect(docsData).toMatchSnapshot();
   });
 
   test('translated website', async () => {
     const props = await loadSetup('translated');
-    const {siteDir, docsDir, env} = props;
-    const docsData = await loadDocs({siteDir, docsDir, env});
+    const {siteDir, docsDir, env, siteConfig} = props;
+    const docsData = await loadDocs({siteDir, docsDir, env, siteConfig});
     expect(docsData).toMatchSnapshot();
   });
 });
diff --git a/test/load/docs/metadata.test.js b/test/load/docs/metadata.test.js
index b1aff83a69..1791bac108 100644
--- a/test/load/docs/metadata.test.js
+++ b/test/load/docs/metadata.test.js
@@ -5,17 +5,17 @@ import loadSetup from '../../loadSetup';
 describe('processMetadata', () => {
   test('normal docs', async () => {
     const props = await loadSetup('simple');
-    const {docsDir, env} = props;
+    const {docsDir, env, siteConfig} = props;
     const sourceA = path.join('foo', 'bar.md');
     const sourceB = path.join('hello.md');
-    const dataA = await processMetadata(sourceA, docsDir, env, {});
-    const dataB = await processMetadata(sourceB, docsDir, env, {});
+    const dataA = await processMetadata(sourceA, docsDir, env, {}, siteConfig);
+    const dataB = await processMetadata(sourceB, docsDir, env, {}, siteConfig);
     expect(dataA).toEqual({
       id: 'foo/bar',
       language: undefined,
       localized_id: 'foo/bar',
-      permalink: 'docs/foo/bar',
-      source: 'foo/bar.md',
+      permalink: '/docs/foo/bar',
+      source: '@docs/foo/bar.md',
       title: 'Bar',
       version: undefined
     });
@@ -23,27 +23,43 @@ describe('processMetadata', () => {
       id: 'hello',
       language: undefined,
       localized_id: 'hello',
-      permalink: 'docs/hello',
-      source: 'hello.md',
+      permalink: '/docs/hello',
+      source: '@docs/hello.md',
       title: 'Hello, World !',
       version: undefined
     });
   });
 
+  test('docs with custom permalink', async () => {
+    const props = await loadSetup('simple');
+    const {docsDir, env, siteConfig} = props;
+    const source = path.join('permalink.md');
+    const data = await processMetadata(source, docsDir, env, {}, siteConfig);
+    expect(data).toEqual({
+      id: 'permalink',
+      language: undefined,
+      localized_id: 'permalink',
+      permalink: '/docs/endiliey/permalink',
+      source: '@docs/permalink.md',
+      title: 'Permalink',
+      version: undefined
+    });
+  });
+
   test('versioned docs (without translation)', async () => {
     const props = await loadSetup('versioned');
-    const {siteDir, docsDir, env} = props;
+    const {siteDir, env, siteConfig} = props;
     const refDir = path.join(siteDir, 'versioned_docs');
     const sourceA = path.join('version-1.0.0', 'foo', 'bar.md');
     const sourceB = path.join('version-1.0.0', 'hello.md');
-    const dataA = await processMetadata(sourceA, refDir, env, {});
-    const dataB = await processMetadata(sourceB, refDir, env, {});
+    const dataA = await processMetadata(sourceA, refDir, env, {}, siteConfig);
+    const dataB = await processMetadata(sourceB, refDir, env, {}, siteConfig);
     expect(dataA).toEqual({
       id: 'version-1.0.0-foo/bar',
       language: undefined,
       localized_id: 'version-1.0.0-foo/bar',
-      permalink: 'docs/1.0.0/foo/bar',
-      source: 'version-1.0.0/foo/bar.md',
+      permalink: '/docs/1.0.0/foo/bar',
+      source: '@versioned_docs/version-1.0.0/foo/bar.md',
       title: 'Bar',
       version: '1.0.0'
     });
@@ -51,8 +67,8 @@ describe('processMetadata', () => {
       id: 'version-1.0.0-hello',
       language: undefined,
       localized_id: 'version-1.0.0-hello',
-      permalink: 'docs/1.0.0/hello',
-      source: 'version-1.0.0/hello.md',
+      permalink: '/docs/1.0.0/hello',
+      source: '@versioned_docs/version-1.0.0/hello.md',
       title: 'Hello, World !',
       version: '1.0.0'
     });
@@ -60,22 +76,22 @@ describe('processMetadata', () => {
 
   test('translated versioned docs', async () => {
     const props = await loadSetup('transversioned');
-    const {siteDir, docsDir, env} = props;
+    const {siteDir, env, siteConfig} = props;
     const refDir = path.join(siteDir, 'translated_docs');
     const sourceA = path.join('ko', 'version-1.0.0', 'foo', 'bar.md');
     const sourceB = path.join('ko', 'version-1.0.0', 'hello.md');
     const sourceC = path.join('ko', 'version-1.0.1', 'foo', 'bar.md');
     const sourceD = path.join('ko', 'version-1.0.1', 'hello.md');
-    const dataA = await processMetadata(sourceA, refDir, env, {});
-    const dataB = await processMetadata(sourceB, refDir, env, {});
-    const dataC = await processMetadata(sourceC, refDir, env, {});
-    const dataD = await processMetadata(sourceD, refDir, env, {});
+    const dataA = await processMetadata(sourceA, refDir, env, {}, siteConfig);
+    const dataB = await processMetadata(sourceB, refDir, env, {}, siteConfig);
+    const dataC = await processMetadata(sourceC, refDir, env, {}, siteConfig);
+    const dataD = await processMetadata(sourceD, refDir, env, {}, siteConfig);
     expect(dataA).toEqual({
       id: 'ko-version-1.0.0-foo/bar',
       language: 'ko',
       localized_id: 'ko-version-1.0.0-foo/bar',
-      permalink: 'docs/ko/1.0.0/foo/bar',
-      source: 'ko/version-1.0.0/foo/bar.md',
+      permalink: '/docs/ko/1.0.0/foo/bar',
+      source: '@translated_docs/ko/version-1.0.0/foo/bar.md',
       title: 'Bar',
       version: '1.0.0'
     });
@@ -83,8 +99,8 @@ describe('processMetadata', () => {
       id: 'ko-version-1.0.0-hello',
       language: 'ko',
       localized_id: 'ko-version-1.0.0-hello',
-      permalink: 'docs/ko/1.0.0/hello',
-      source: 'ko/version-1.0.0/hello.md',
+      permalink: '/docs/ko/1.0.0/hello',
+      source: '@translated_docs/ko/version-1.0.0/hello.md',
       title: 'Hello, World !',
       version: '1.0.0'
     });
@@ -92,8 +108,8 @@ describe('processMetadata', () => {
       id: 'ko-version-1.0.1-foo/bar',
       language: 'ko',
       localized_id: 'ko-version-1.0.1-foo/bar',
-      permalink: 'docs/ko/foo/bar',
-      source: 'ko/version-1.0.1/foo/bar.md',
+      permalink: '/docs/ko/foo/bar',
+      source: '@translated_docs/ko/version-1.0.1/foo/bar.md',
       title: 'Bar',
       version: '1.0.1'
     });
@@ -101,8 +117,8 @@ describe('processMetadata', () => {
       id: 'ko-version-1.0.1-hello',
       language: 'ko',
       localized_id: 'ko-version-1.0.1-hello',
-      permalink: 'docs/ko/hello',
-      source: 'ko/version-1.0.1/hello.md',
+      permalink: '/docs/ko/hello',
+      source: '@translated_docs/ko/version-1.0.1/hello.md',
       title: 'Hello, World !',
       version: '1.0.1'
     });
@@ -110,18 +126,18 @@ describe('processMetadata', () => {
 
   test('translated docs only', async () => {
     const props = await loadSetup('translated');
-    const {siteDir, docsDir, env} = props;
+    const {siteDir, env, siteConfig} = props;
     const refDir = path.join(siteDir, 'translated_docs');
     const sourceA = path.join('ko', 'foo', 'bar.md');
     const sourceB = path.join('ko', 'hello.md');
-    const dataA = await processMetadata(sourceA, refDir, env, {});
-    const dataB = await processMetadata(sourceB, refDir, env, {});
+    const dataA = await processMetadata(sourceA, refDir, env, {}, siteConfig);
+    const dataB = await processMetadata(sourceB, refDir, env, {}, siteConfig);
     expect(dataA).toEqual({
       id: 'ko-foo/bar',
       language: 'ko',
       localized_id: 'ko-foo/bar',
-      permalink: 'docs/ko/foo/bar',
-      source: 'ko/foo/bar.md',
+      permalink: '/docs/ko/foo/bar',
+      source: '@translated_docs/ko/foo/bar.md',
       title: 'Bar',
       version: undefined
     });
@@ -129,8 +145,8 @@ describe('processMetadata', () => {
       id: 'ko-hello',
       language: 'ko',
       localized_id: 'ko-hello',
-      permalink: 'docs/ko/hello',
-      source: 'ko/hello.md',
+      permalink: '/docs/ko/hello',
+      source: '@translated_docs/ko/hello.md',
       title: 'Hello, World !',
       version: undefined
     });
diff --git a/test/load/pages.test.js b/test/load/pages.test.js
index 171074b259..d73bdcb57b 100644
--- a/test/load/pages.test.js
+++ b/test/load/pages.test.js
@@ -4,7 +4,7 @@ import path from 'path';
 describe('loadPages', () => {
   test('valid pages', async () => {
     const pagesDir = path.join(__dirname, '__fixtures__', 'simple-pages');
-    let pagesData = await loadPages(pagesDir);
+    const pagesData = await loadPages(pagesDir);
     pagesData.sort((a, b) => a.path > b.path); // because it was unordered
     expect(pagesData).toEqual([
       {