diff --git a/docs/configuration.md b/docs/configuration.md
index 6f0c4e475..8365a93d6 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -30,280 +30,314 @@ The config can also be defined as a function, in which case the first argument i
```
-## 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
+
+
```
-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`
+
+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}** 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: 'docsify',
+ // 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: 'docsify',
};
```
-```markdown
-## This is test
+## nameLink
-
-```
+- 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 `:` HTM
+## noCompileLinks
+
+- Type: `Array`
+
+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
-## 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}** 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`
+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`
-
-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 }}
-
-## 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.
diff --git a/src/core/config.js b/src/core/config.js
index 5830656a9..235736764 100644
--- a/src/core/config.js
+++ b/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)