docs: Update configuration options (#1773)

docs/configuration.md

@@ -30,280 +30,314 @@ The config can also be defined as a function, in which case the first argument i
 </script>
 ```
 
-## el
+## alias
 
-- Type: `String`
-- Default: `#app`
+- Type: `Object`
 
-The DOM element to be mounted on initialization. It can be a CSS selector string or an actual [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement).
+Set the route alias. You can freely manage routing rules. Supports RegExp.
 
 ```js
 window.$docsify = {
-  el: '#app',
+  alias: {
+    '/foo/(.*)': '/bar/$1', // supports regexp
+    '/zh-cn/changelog': '/changelog',
+    '/changelog':
+      'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
+    '/.*/_sidebar.md': '/_sidebar.md', // See #301
+  },
 };
 ```
 
-## repo
+## auto2top
 
-- Type: `String`
-- Default: `null`
+- Type: `Boolean`
+- Default: `false`
 
-Configure the repository url, or a string of `username/repo`, to add the [GitHub Corner](http://tholman.com/github-corners/) widget in the top right corner of the site.
+Scrolls to the top of the screen when the route is changed.
 
 ```js
 window.$docsify = {
-  repo: 'docsifyjs/docsify',
-  // or
-  repo: 'https://github.com/docsifyjs/docsify/',
+  auto2top: true,
 };
 ```
 
-## maxLevel
+## autoHeader
 
-- Type: `Number`
-- Default: `6`
+- Type: `Boolean`
+- Default: `false`
 
-Maximum Table of content level.
+If `loadSidebar` and `autoHeader` are both enabled, for each link in `_sidebar.md`, prepend a header to the page before converting it to HTML. See [#78](https://github.com/docsifyjs/docsify/issues/78).
 
 ```js
 window.$docsify = {
-  maxLevel: 4,
+  loadSidebar: true,
+  autoHeader: true,
 };
 ```
 
-## loadNavbar
+## basePath
 
-- Type: `Boolean|String`
-- Default: `false`
+- Type: `String`
 
-Loads navbar from the Markdown file `_navbar.md` if **true**, else loads it from the path specified.
+Base path of the website. You can set it to another directory or another domain name.
 
 ```js
 window.$docsify = {
-  // load from _navbar.md
-  loadNavbar: true,
+  basePath: '/path/',
 
-  // load from nav.md
-  loadNavbar: 'nav.md',
+  // Load the files from another site
+  basePath: 'https://docsify.js.org/',
+
+  // Even can load files from other repo
+  basePath:
+    'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/',
 };
 ```
 
-## loadSidebar
+## catchPluginErrors
 
-- Type: `Boolean|String`
-- Default: `false`
+- Type: `Boolean`
+- Default: `true`
 
-Loads sidebar from the Markdown file `_sidebar.md` if **true**, else loads it from the path specified.
+Determines if Docsify should handle uncaught _synchronous_ plugin errors automatically. This can prevent plugin errors from affecting docsify's ability to properly render live site content.
+
+## cornerExternalLinkTarget
+
+- Type: `String`
+- Default: `'_blank'`
+
+Target to open external link at the top right corner. Default `'_blank'` (new window/tab)
 
 ```js
 window.$docsify = {
-  // load from _sidebar.md
-  loadSidebar: true,
-
-  // load from summary.md
-  loadSidebar: 'summary.md',
+  cornerExternalLinkTarget: '_self', // default: '_blank'
 };
 ```
 
-## hideSidebar
+## coverpage
 
-- Type : `Boolean`
-- Default: `true`
+- Type: `Boolean|String|String[]|Object`
+- Default: `false`
 
-This option will completely hide your sidebar and won't render any content on the side.
+Activate the [cover feature](cover.md). If true, it will load from `_coverpage.md`.
 
 ```js
 window.$docsify = {
-  hideSidebar: true,
+  coverpage: true,
+
+  // Custom file name
+  coverpage: 'cover.md',
+
+  // multiple covers
+  coverpage: ['/', '/zh-cn/'],
+
+  // multiple covers and custom file name
+  coverpage: {
+    '/': 'cover.md',
+    '/zh-cn/': 'cover.md',
+  },
 };
 ```
 
-## subMaxLevel
+## crossOriginLinks
 
-- Type: `Number`
-- Default: `0`
+- Type: `Array`
 
-Add table of contents (TOC) in custom sidebar.
+When `routerMode: 'history'`, you may face cross-origin issues. See [#1379](https://github.com/docsifyjs/docsify/issues/1379).
+In Markdown content, there is a simple way to solve it: see extends Markdown syntax `Cross-Origin link` in [helpers](helpers.md).
 
 ```js
 window.$docsify = {
-  subMaxLevel: 2,
+  crossOriginLinks: ['https://example.com/cross-origin-link'],
 };
 ```
 
-## auto2top
+## el
 
-- Type: `Boolean`
-- Default: `false`
+- Type: `String`
+- Default: `'#app'`
 
-Scrolls to the top of the screen when the route is changed.
+The DOM element to be mounted on initialization. It can be a CSS selector string or an actual [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement).
 
 ```js
 window.$docsify = {
-  auto2top: true,
+  el: '#app',
 };
 ```
 
-## homepage
+## executeScript
 
-- Type: `String`
-- Default: `README.md`
+- Type: `Boolean`
+- Default: `null`
 
-`README.md` in your docs folder will be treated as the homepage for your website, but sometimes you may need to serve another file as your homepage.
+Execute the script on the page. Only parses the first script tag ([demo](themes)). If Vue is detected, this is `true` by default.
 
 ```js
 window.$docsify = {
-  // Change to /home.md
-  homepage: 'home.md',
-
-  // Or use the readme in your repo
-  homepage:
-    'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
+  executeScript: true,
 };
 ```
 
-If you have a link to the homepage in the sidebar and want it to be shown as active when accessing the root url, make sure to update your sidebar accordingly:
-
 ```markdown
-- Sidebar
-  - [Home](/)
-  - [Another page](another.md)
+## This is test
+
+<script>
+  console.log(2333)
+</script>
 ```
 
-For more details, see [#1131](https://github.com/docsifyjs/docsify/issues/1131).
+Note that if you are running an external script, e.g. an embedded jsfiddle demo, make sure to include the [external-script](plugins.md?id=external-script) plugin.
 
-## basePath
+## ext
 
 - Type: `String`
+- Default: `'.md'`
 
-Base path of the website. You can set it to another directory or another domain name.
+Request file extension.
 
 ```js
 window.$docsify = {
-  basePath: '/path/',
+  ext: '.md',
+};
+```
 
-  // Load the files from another site
-  basePath: 'https://docsify.js.org/',
+## externalLinkRel
 
-  // Even can load files from other repo
-  basePath:
-    'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/',
+- Type: `String`
+- Default: `'noopener'`
+
+Default `'noopener'` (no opener) prevents the newly opened external page (when [externalLinkTarget](#externallinktarget) is `'_blank'`) from having the ability to control our page. No `rel` is set when it's not `'_blank'`. See [this post](https://mathiasbynens.github.io/rel-noopener/) for more information about why you may want to use this option.
+
+```js
+window.$docsify = {
+  externalLinkRel: '', // default: 'noopener'
 };
 ```
 
-## relativePath
-
-- Type: `Boolean`
-- Default: `false`
+## externalLinkTarget
 
-If **true**, links are relative to the current context.
+- Type: `String`
+- Default: `'_blank'`
 
-For example, the directory structure is as follows:
+Target to open external links inside the markdown. Default `'_blank'` (new window/tab)
 
-```text
-.
-└── docs
-    ├── README.md
-    ├── guide.md
-    └── zh-cn
-        ├── README.md
-        ├── guide.md
-        └── config
-            └── example.md
+```js
+window.$docsify = {
+  externalLinkTarget: '_self', // default: '_blank'
+};
 ```
 
-With relative path **enabled** and current URL `http://domain.com/zh-cn/README`, given links will resolve to:
+## fallbackLanguages
 
-```text
-guide.md              => http://domain.com/zh-cn/guide
-config/example.md     => http://domain.com/zh-cn/config/example
-../README.md          => http://domain.com/README
-/README.md            => http://domain.com/README
-```
+- Type: `Array<string>`
+
+List of languages that will fallback to the default language when a page is requested and it doesn't exist for the given locale.
+
+Example:
+
+- try to fetch the page of `/de/overview`. If this page exists, it'll be displayed.
+- then try to fetch the default page `/overview` (depending on the default language). If this page exists, it'll be displayed.
+- then display the 404 page.
 
 ```js
 window.$docsify = {
-  // Relative path enabled
-  relativePath: true,
-
-  // Relative path disabled (default value)
-  relativePath: false,
+  fallbackLanguages: ['fr', 'de'],
 };
 ```
 
-## coverpage
+## formatUpdated
 
-- Type: `Boolean|String|String[]|Object`
-- Default: `false`
+- Type: `String|Function`
 
-Activate the [cover feature](cover.md). If true, it will load from `_coverpage.md`.
+We can display the file update date through **{docsify-updated<span>}</span>** variable. And format it by `formatUpdated`.
+See https://github.com/lukeed/tinydate#patterns
 
 ```js
 window.$docsify = {
-  coverpage: true,
-
-  // Custom file name
-  coverpage: 'cover.md',
+  formatUpdated: '{MM}/{DD} {HH}:{mm}',
 
-  // multiple covers
-  coverpage: ['/', '/zh-cn/'],
+  formatUpdated: function (time) {
+    // ...
 
-  // multiple covers and custom file name
-  coverpage: {
-    '/': 'cover.md',
-    '/zh-cn/': 'cover.md',
+    return time;
   },
 };
 ```
 
-## logo
+## hideSidebar
 
-- Type: `String`
+- Type : `Boolean`
+- Default: `true`
 
-Website logo as it appears in the sidebar. You can resize it using CSS.
+This option will completely hide your sidebar and won't render any content on the side.
 
 ```js
 window.$docsify = {
-  logo: '/_media/icon.svg',
+  hideSidebar: true,
 };
 ```
 
-## name
+## homepage
 
 - Type: `String`
+- Default: `'README.md'`
 
-Website name as it appears in the sidebar.
+`README.md` in your docs folder will be treated as the homepage for your website, but sometimes you may need to serve another file as your homepage.
 
 ```js
 window.$docsify = {
-  name: 'docsify',
+  // Change to /home.md
+  homepage: 'home.md',
+
+  // Or use the readme in your repo
+  homepage:
+    'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
 };
 ```
 
-The name field can also contain custom HTML for easier customization:
+## loadNavbar
+
+- Type: `Boolean|String`
+- Default: `false`
+
+Loads navbar from the Markdown file `_navbar.md` if **true**, else loads it from the path specified.
 
 ```js
 window.$docsify = {
-  name: '<span>docsify</span>',
+  // load from _navbar.md
+  loadNavbar: true,
+
+  // load from nav.md
+  loadNavbar: 'nav.md',
 };
 ```
 
-## nameLink
+## loadSidebar
+
+- Type: `Boolean|String`
+- Default: `false`
+
+Loads sidebar from the Markdown file `_sidebar.md` if **true**, else loads it from the path specified.
+
+```js
+window.$docsify = {
+  // load from _sidebar.md
+  loadSidebar: true,
+
+  // load from summary.md
+  loadSidebar: 'summary.md',
+};
+```
+
+## logo
 
 - Type: `String`
-- Default: `window.location.pathname`
 
-The URL that the website `name` links to.
+Website logo as it appears in the sidebar. You can resize it using CSS.
 
 ```js
 window.$docsify = {
-  nameLink: '/',
-
-  // For each route
-  nameLink: {
-    '/zh-cn/': '#/zh-cn/',
-    '/': '#/',
-  },
+  logo: '/_media/icon.svg',
 };
 ```
 
@@ -333,70 +367,70 @@ window.$docsify = {
 };
 ```
 
-## themeColor
+## maxLevel
 
-- Type: `String`
+- Type: `Number`
+- Default: `6`
 
-Customize the theme color. Use [CSS3 variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) feature and polyfill in older browsers.
+Maximum Table of content level.
 
 ```js
 window.$docsify = {
-  themeColor: '#3F51B5',
+  maxLevel: 4,
 };
 ```
 
-## alias
+## mergeNavbar
 
-- Type: `Object`
+- Type: `Boolean`
+- Default: `false`
 
-Set the route alias. You can freely manage routing rules. Supports RegExp.
+Navbar will be merged with the sidebar on smaller screens.
 
 ```js
 window.$docsify = {
-  alias: {
-    '/foo/(.*)': '/bar/$1', // supports regexp
-    '/zh-cn/changelog': '/changelog',
-    '/changelog':
-      'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
-    '/.*/_sidebar.md': '/_sidebar.md', // See #301
-  },
+  mergeNavbar: true,
 };
 ```
 
-## autoHeader
+## name
 
-- Type: `Boolean`
+- Type: `String`
 
-If `loadSidebar` and `autoHeader` are both enabled, for each link in `_sidebar.md`, prepend a header to the page before converting it to HTML. See [#78](https://github.com/docsifyjs/docsify/issues/78).
+Website name as it appears in the sidebar.
 
 ```js
 window.$docsify = {
-  loadSidebar: true,
-  autoHeader: true,
+  name: 'docsify',
 };
 ```
 
-## executeScript
-
-- Type: `Boolean`
-
-Execute the script on the page. Only parse the first script tag ([demo](themes)). If Vue is present, it is turned on by default.
+The name field can also contain custom HTML for easier customization:
 
 ```js
 window.$docsify = {
-  executeScript: true,
+  name: '<span>docsify</span>',
 };
 ```
 
-```markdown
-## This is test
+## nameLink
 
-<script>
-  console.log(2333)
-</script>
-```
+- Type: `String`
+- Default: `'window.location.pathname'`
 
-Note that if you are running an external script, e.g. an embedded jsfiddle demo, make sure to include the [external-script](plugins.md?id=external-script) plugin.
+The URL that the website `name` links to.
+
+```js
+window.$docsify = {
+  nameLink: '/',
+
+  // For each route
+  nameLink: {
+    '/zh-cn/': '#/zh-cn/',
+    '/': '#/',
+  },
+};
+```
 
 ## nativeEmoji
 
@@ -451,6 +485,18 @@ To render shorthand codes as text, replace `:` characters with the `&colon;` HTM
 
 </output>
 
+## noCompileLinks
+
+- Type: `Array<string>`
+
+Sometimes we do not want docsify to handle our links. See [#203](https://github.com/docsifyjs/docsify/issues/203). We can skip compiling of certain links by specifying an array of strings. Each string is converted into to a regular expression (`RegExp`) and the _whole_ href of a link is matched against it.
+
+```js
+window.$docsify = {
+  noCompileLinks: ['/foo', '/bar/.*'],
+};
+```
+
 ## noEmoji
 
 - Type: `Boolean`
@@ -490,121 +536,112 @@ To disable emoji parsing of individual shorthand codes, replace `:` characters w
 
 </output>
 
-## mergeNavbar
+## notFoundPage
 
-- Type: `Boolean`
+- Type: `Boolean` | `String` | `Object`
+- Default: `false`
 
-Navbar will be merged with the sidebar on smaller screens.
+Display default "404 - Not found" message:
 
 ```js
 window.$docsify = {
-  mergeNavbar: true,
+  notFoundPage: false,
 };
 ```
 
-## formatUpdated
-
-- Type: `String|Function`
-
-We can display the file update date through **{docsify-updated<span>}</span>** variable. And format it by `formatUpdated`.
-See https://github.com/lukeed/tinydate#patterns
+Load the `_404.md` file:
 
 ```js
 window.$docsify = {
-  formatUpdated: '{MM}/{DD} {HH}:{mm}',
-
-  formatUpdated: function (time) {
-    // ...
-
-    return time;
-  },
+  notFoundPage: true,
 };
 ```
 
-## externalLinkTarget
-
-- Type: `String`
-- Default: `_blank`
-
-Target to open external links inside the markdown. Default `'_blank'` (new window/tab)
+Load the customized path of the 404 page:
 
 ```js
 window.$docsify = {
-  externalLinkTarget: '_self', // default: '_blank'
+  notFoundPage: 'my404.md',
 };
 ```
 
-## cornerExternalLinkTarget
-
-- Type:`String`
-- Default:`_blank`
-
-Target to open external link at the top right corner. Default `'_blank'` (new window/tab)
+Load the right 404 page according to the localization:
 
 ```js
 window.$docsify = {
-  cornerExternalLinkTarget: '_self', // default: '_blank'
+  notFoundPage: {
+    '/': '_404.md',
+    '/de': 'de/_404.md',
+  },
 };
 ```
 
-## externalLinkRel
-
-- Type: `String`
-- Default: `noopener`
-
-Default `'noopener'` (no opener) prevents the newly opened external page (when [externalLinkTarget](#externallinktarget) is `'_blank'`) from having the ability to control our page. No `rel` is set when it's not `'_blank'`. See [this post](https://mathiasbynens.github.io/rel-noopener/) for more information about why you may want to use this option.
+> Note: The options for fallbackLanguages don't work with the `notFoundPage` options.
 
-```js
-window.$docsify = {
-  externalLinkRel: '', // default: 'noopener'
-};
-```
+## onlyCover
 
-## routerMode
+- Type: `Boolean`
+- Default: `false`
 
-- Type: `String`
-- Default: `hash`
+Only coverpage is loaded when visiting the home page.
 
 ```js
 window.$docsify = {
-  routerMode: 'history', // default: 'hash'
+  onlyCover: false,
 };
 ```
 
-## crossOriginLinks
+## relativePath
 
-- Type: `Array`
+- Type: `Boolean`
+- Default: `false`
 
-When `routerMode: 'history'`, you may face cross-origin issues. See [#1379](https://github.com/docsifyjs/docsify/issues/1379).
-In Markdown content, there is a simple way to solve it: see extends Markdown syntax `Cross-Origin link` in [helpers](helpers.md).
+If **true**, links are relative to the current context.
 
-```js
-window.$docsify = {
-  crossOriginLinks: ['https://example.com/cross-origin-link'],
-};
-```
+For example, the directory structure is as follows:
 
-## noCompileLinks
+```text
+.
+└── docs
+    ├── README.md
+    ├── guide.md
+    └── zh-cn
+        ├── README.md
+        ├── guide.md
+        └── config
+            └── example.md
+```
 
-- Type: `Array<string>`
+With relative path **enabled** and current URL `http://domain.com/zh-cn/README`, given links will resolve to:
 
-Sometimes we do not want docsify to handle our links. See [#203](https://github.com/docsifyjs/docsify/issues/203). We can skip compiling of certain links by specifying an array of strings. Each string is converted into to a regular expression (`RegExp`) and the _whole_ href of a link is matched against it.
+```text
+guide.md              => http://domain.com/zh-cn/guide
+config/example.md     => http://domain.com/zh-cn/config/example
+../README.md          => http://domain.com/README
+/README.md            => http://domain.com/README
+```
 
 ```js
 window.$docsify = {
-  noCompileLinks: ['/foo', '/bar/.*'],
+  // Relative path enabled
+  relativePath: true,
+
+  // Relative path disabled (default value)
+  relativePath: false,
 };
 ```
 
-## onlyCover
+## repo
 
-- Type: `Boolean`
+- Type: `String`
 
-Only coverpage is loaded when visiting the home page.
+Configure the repository url, or a string of `username/repo`, to add the [GitHub Corner](http://tholman.com/github-corners/) widget in the top right corner of the site.
 
 ```js
 window.$docsify = {
-  onlyCover: false,
+  repo: 'docsifyjs/docsify',
+  // or
+  repo: 'https://github.com/docsifyjs/docsify/',
 };
 ```
 
@@ -632,69 +669,52 @@ window.$docsify = {
 };
 ```
 
-## ext
+## routerMode
 
 - Type: `String`
-
-Request file extension.
+- Default: `'hash'`
 
 ```js
 window.$docsify = {
-  ext: '.md',
+  routerMode: 'history', // default: 'hash'
 };
 ```
 
-## fallbackLanguages
-
-- Type: `Array<string>`
-
-List of languages that will fallback to the default language when a page is requested and it doesn't exist for the given locale.
+## subMaxLevel
 
-Example:
+- Type: `Number`
+- Default: `0`
 
-- try to fetch the page of `/de/overview`. If this page exists, it'll be displayed.
-- then try to fetch the default page `/overview` (depending on the default language). If this page exists, it'll be displayed.
-- then display the 404 page.
+Add table of contents (TOC) in custom sidebar.
 
 ```js
 window.$docsify = {
-  fallbackLanguages: ['fr', 'de'],
+  subMaxLevel: 2,
 };
 ```
 
-## notFoundPage
-
-- Type: `Boolean` | `String` | `Object`
-
-Load the `_404.md` file:
+If you have a link to the homepage in the sidebar and want it to be shown as active when accessing the root url, make sure to update your sidebar accordingly:
 
-```js
-window.$docsify = {
-  notFoundPage: true,
-};
+```markdown
+- Sidebar
+  - [Home](/)
+  - [Another page](another.md)
 ```
 
-Load the customized path of the 404 page:
+For more details, see [#1131](https://github.com/docsifyjs/docsify/issues/1131).
 
-```js
-window.$docsify = {
-  notFoundPage: 'my404.md',
-};
-```
+## themeColor
 
-Load the right 404 page according to the localization:
+- Type: `String`
+
+Customize the theme color. Use [CSS3 variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) feature and polyfill in older browsers.
 
 ```js
 window.$docsify = {
-  notFoundPage: {
-    '/': '_404.md',
-    '/de': 'de/_404.md',
-  },
+  themeColor: '#3F51B5',
 };
 ```
 
-> Note: The options for fallbackLanguages don't work with the `notFoundPage` options.
-
 ## topMargin
 
 - Type: `Number`
@@ -808,10 +828,3 @@ window.$docsify = {
   {{ count }}
   <button @click="count += 1">+</button>
 </output>
-
-## catchPluginErrors
-
-- Type: `Boolean`
-- Default: `true`
-
-Determines if Docsify should handle uncaught _synchronous_ plugin errors automatically. This can prevent plugin errors from affecting docsify's ability to properly render live site content.

src/core/config.js

@@ -6,38 +6,37 @@ const currentScript = document.currentScript;
 export default function (vm) {
   const config = merge(
     {
-      el: '#app',
-      repo: '',
-      maxLevel: 6,
-      subMaxLevel: 0,
-      loadSidebar: null,
-      loadNavbar: null,
-      homepage: 'README.md',
-      coverpage: '',
-      basePath: '',
       auto2top: false,
-      name: '',
-      themeColor: '',
-      nameLink: window.location.pathname,
       autoHeader: false,
+      basePath: '',
+      catchPluginErrors: true,
+      cornerExternalLinkTarget: '_blank',
+      coverpage: '',
+      crossOriginLinks: [],
+      el: '#app',
       executeScript: null,
-      nativeEmoji: false,
-      noEmoji: false,
-      ga: '',
       ext: '.md',
-      mergeNavbar: false,
-      formatUpdated: '',
-      // This config for the links inside markdown
-      externalLinkTarget: '_blank',
-      // This config for the corner
-      cornerExternalLinkTarget: '_blank',
       externalLinkRel: 'noopener',
-      routerMode: 'hash',
+      externalLinkTarget: '_blank',
+      formatUpdated: '',
+      ga: '',
+      homepage: 'README.md',
+      loadNavbar: null,
+      loadSidebar: null,
+      maxLevel: 6,
+      mergeNavbar: false,
+      name: '',
+      nameLink: window.location.pathname,
+      nativeEmoji: false,
       noCompileLinks: [],
-      crossOriginLinks: [],
+      noEmoji: false,
+      notFoundPage: true,
       relativePath: false,
+      repo: '',
+      routerMode: 'hash',
+      subMaxLevel: 0,
+      themeColor: '',
       topMargin: 0,
-      catchPluginErrors: true,
     },
     typeof window.$docsify === 'function'
       ? window.$docsify(vm)