diff --git a/docs/configuration.md b/docs/configuration.md index 6f0c4e47..8365a93d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -30,10 +30,132 @@ The config can also be defined as a function, in which case the first argument i ``` +## alias + +- Type: `Object` + +Set the route alias. You can freely manage routing rules. Supports RegExp. + +```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 + }, +}; +``` + +## auto2top + +- Type: `Boolean` +- Default: `false` + +Scrolls to the top of the screen when the route is changed. + +```js +window.$docsify = { + auto2top: true, +}; +``` + +## autoHeader + +- Type: `Boolean` +- Default: `false` + +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 = { + loadSidebar: true, + autoHeader: true, +}; +``` + +## basePath + +- Type: `String` + +Base path of the website. You can set it to another directory or another domain name. + +```js +window.$docsify = { + basePath: '/path/', + + // 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/', +}; +``` + +## 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. + +## cornerExternalLinkTarget + +- Type: `String` +- Default: `'_blank'` + +Target to open external link at the top right corner. Default `'_blank'` (new window/tab) + +```js +window.$docsify = { + cornerExternalLinkTarget: '_self', // default: '_blank' +}; +``` + +## coverpage + +- Type: `Boolean|String|String[]|Object` +- Default: `false` + +Activate the [cover feature](cover.md). If true, it will load from `_coverpage.md`. + +```js +window.$docsify = { + 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', + }, +}; +``` + +## crossOriginLinks + +- Type: `Array` + +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 = { + crossOriginLinks: ['https://example.com/cross-origin-link'], +}; +``` + ## el - Type: `String` -- Default: `#app` +- Default: `'#app'` 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). @@ -43,31 +165,133 @@ window.$docsify = { }; ``` -## repo +## executeScript -- Type: `String` +- Type: `Boolean` - Default: `null` -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. +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 = { - repo: 'docsifyjs/docsify', - // or - repo: 'https://github.com/docsifyjs/docsify/', + executeScript: true, }; ``` -## maxLevel +```markdown +## This is test -- Type: `Number` -- Default: `6` + +``` -Maximum Table of content level. +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. + +## ext + +- Type: `String` +- Default: `'.md'` + +Request file extension. ```js window.$docsify = { - maxLevel: 4, + ext: '.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. + +```js +window.$docsify = { + externalLinkRel: '', // default: 'noopener' +}; +``` + +## externalLinkTarget + +- Type: `String` +- Default: `'_blank'` + +Target to open external links inside the markdown. Default `'_blank'` (new window/tab) + +```js +window.$docsify = { + externalLinkTarget: '_self', // default: '_blank' +}; +``` + +## 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. + +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 = { + fallbackLanguages: ['fr', 'de'], +}; +``` + +## 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 + +```js +window.$docsify = { + formatUpdated: '{MM}/{DD} {HH}:{mm}', + + formatUpdated: function (time) { + // ... + + return time; + }, +}; +``` + +## hideSidebar + +- Type : `Boolean` +- Default: `true` + +This option will completely hide your sidebar and won't render any content on the side. + +```js +window.$docsify = { + hideSidebar: true, +}; +``` + +## homepage + +- Type: `String` +- Default: `'README.md'` + +`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 = { + // Change to /home.md + homepage: 'home.md', + + // Or use the readme in your repo + homepage: + 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md', }; ``` @@ -105,157 +329,6 @@ window.$docsify = { }; ``` -## hideSidebar - -- Type : `Boolean` -- Default: `true` - -This option will completely hide your sidebar and won't render any content on the side. - -```js -window.$docsify = { - hideSidebar: true, -}; -``` - -## subMaxLevel - -- Type: `Number` -- Default: `0` - -Add table of contents (TOC) in custom sidebar. - -```js -window.$docsify = { - subMaxLevel: 2, -}; -``` - -## auto2top - -- Type: `Boolean` -- Default: `false` - -Scrolls to the top of the screen when the route is changed. - -```js -window.$docsify = { - auto2top: true, -}; -``` - -## homepage - -- Type: `String` -- Default: `README.md` - -`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 = { - // Change to /home.md - homepage: 'home.md', - - // Or use the readme in your repo - homepage: - 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md', -}; -``` - -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) -``` - -For more details, see [#1131](https://github.com/docsifyjs/docsify/issues/1131). - -## basePath - -- Type: `String` - -Base path of the website. You can set it to another directory or another domain name. - -```js -window.$docsify = { - basePath: '/path/', - - // 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/', -}; -``` - -## relativePath - -- Type: `Boolean` -- Default: `false` - -If **true**, links are relative to the current context. - -For example, the directory structure is as follows: - -```text -. -└── docs - ├── README.md - ├── guide.md - └── zh-cn - ├── README.md - ├── guide.md - └── config - └── example.md -``` - -With relative path **enabled** and current URL `http://domain.com/zh-cn/README`, given links will resolve to: - -```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 = { - // Relative path enabled - relativePath: true, - - // Relative path disabled (default value) - relativePath: false, -}; -``` - -## coverpage - -- Type: `Boolean|String|String[]|Object` -- Default: `false` - -Activate the [cover feature](cover.md). If true, it will load from `_coverpage.md`. - -```js -window.$docsify = { - 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', - }, -}; -``` - ## logo - Type: `String` @@ -268,45 +341,6 @@ window.$docsify = { }; ``` -## name - -- Type: `String` - -Website name as it appears in the sidebar. - -```js -window.$docsify = { - name: 'docsify', -}; -``` - -The name field can also contain custom HTML for easier customization: - -```js -window.$docsify = { - name: 'docsify', -}; -``` - -## nameLink - -- Type: `String` -- Default: `window.location.pathname` - -The URL that the website `name` links to. - -```js -window.$docsify = { - nameLink: '/', - - // For each route - nameLink: { - '/zh-cn/': '#/zh-cn/', - '/': '#/', - }, -}; -``` - ## markdown - Type: `Function` @@ -333,71 +367,71 @@ window.$docsify = { }; ``` -## themeColor +## maxLevel + +- Type: `Number` +- Default: `6` + +Maximum Table of content level. + +```js +window.$docsify = { + maxLevel: 4, +}; +``` + +## mergeNavbar + +- Type: `Boolean` +- Default: `false` + +Navbar will be merged with the sidebar on smaller screens. + +```js +window.$docsify = { + mergeNavbar: true, +}; +``` + +## name - 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. +Website name as it appears in the sidebar. ```js window.$docsify = { - themeColor: '#3F51B5', + name: 'docsify', }; ``` -## alias - -- Type: `Object` - -Set the route alias. You can freely manage routing rules. Supports RegExp. +The name field can also contain custom HTML for easier customization: ```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 + name: 'docsify', +}; +``` + +## nameLink + +- Type: `String` +- Default: `'window.location.pathname'` + +The URL that the website `name` links to. + +```js +window.$docsify = { + nameLink: '/', + + // For each route + nameLink: { + '/zh-cn/': '#/zh-cn/', + '/': '#/', }, }; ``` -## autoHeader - -- Type: `Boolean` - -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 = { - loadSidebar: true, - autoHeader: true, -}; -``` - -## 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. - -```js -window.$docsify = { - executeScript: true, -}; -``` - -```markdown -## This is test - - -``` - -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. - ## nativeEmoji - Type: `Boolean` @@ -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,181 +536,18 @@ To disable emoji parsing of individual shorthand codes, replace `:` characters w -## mergeNavbar - -- Type: `Boolean` - -Navbar will be merged with the sidebar on smaller screens. - -```js -window.$docsify = { - mergeNavbar: true, -}; -``` - -## 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 - -```js -window.$docsify = { - formatUpdated: '{MM}/{DD} {HH}:{mm}', - - formatUpdated: function (time) { - // ... - - return time; - }, -}; -``` - -## externalLinkTarget - -- Type: `String` -- Default: `_blank` - -Target to open external links inside the markdown. Default `'_blank'` (new window/tab) - -```js -window.$docsify = { - externalLinkTarget: '_self', // default: '_blank' -}; -``` - -## cornerExternalLinkTarget - -- Type:`String` -- Default:`_blank` - -Target to open external link at the top right corner. Default `'_blank'` (new window/tab) - -```js -window.$docsify = { - cornerExternalLinkTarget: '_self', // default: '_blank' -}; -``` - -## 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. - -```js -window.$docsify = { - externalLinkRel: '', // default: 'noopener' -}; -``` - -## routerMode - -- Type: `String` -- Default: `hash` - -```js -window.$docsify = { - routerMode: 'history', // default: 'hash' -}; -``` - -## crossOriginLinks - -- Type: `Array` - -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 = { - crossOriginLinks: ['https://example.com/cross-origin-link'], -}; -``` - -## 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/.*'], -}; -``` - -## onlyCover - -- Type: `Boolean` - -Only coverpage is loaded when visiting the home page. - -```js -window.$docsify = { - onlyCover: false, -}; -``` - -## requestHeaders - -- Type: `Object` - -Set the request resource headers. - -```js -window.$docsify = { - requestHeaders: { - 'x-token': 'xxx', - }, -}; -``` - -Such as setting the cache - -```js -window.$docsify = { - requestHeaders: { - 'cache-control': 'max-age=600', - }, -}; -``` - -## ext - -- Type: `String` - -Request file extension. - -```js -window.$docsify = { - ext: '.md', -}; -``` - -## 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. - -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 = { - fallbackLanguages: ['fr', 'de'], -}; -``` - ## notFoundPage - Type: `Boolean` | `String` | `Object` +- Default: `false` + +Display default "404 - Not found" message: + +```js +window.$docsify = { + notFoundPage: false, +}; +``` Load the `_404.md` file: @@ -695,6 +578,143 @@ window.$docsify = { > Note: The options for fallbackLanguages don't work with the `notFoundPage` options. +## onlyCover + +- Type: `Boolean` +- Default: `false` + +Only coverpage is loaded when visiting the home page. + +```js +window.$docsify = { + onlyCover: false, +}; +``` + +## relativePath + +- Type: `Boolean` +- Default: `false` + +If **true**, links are relative to the current context. + +For example, the directory structure is as follows: + +```text +. +└── docs + ├── README.md + ├── guide.md + └── zh-cn + ├── README.md + ├── guide.md + └── config + └── example.md +``` + +With relative path **enabled** and current URL `http://domain.com/zh-cn/README`, given links will resolve to: + +```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 = { + // Relative path enabled + relativePath: true, + + // Relative path disabled (default value) + relativePath: false, +}; +``` + +## repo + +- Type: `String` + +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 = { + repo: 'docsifyjs/docsify', + // or + repo: 'https://github.com/docsifyjs/docsify/', +}; +``` + +## requestHeaders + +- Type: `Object` + +Set the request resource headers. + +```js +window.$docsify = { + requestHeaders: { + 'x-token': 'xxx', + }, +}; +``` + +Such as setting the cache + +```js +window.$docsify = { + requestHeaders: { + 'cache-control': 'max-age=600', + }, +}; +``` + +## routerMode + +- Type: `String` +- Default: `'hash'` + +```js +window.$docsify = { + routerMode: 'history', // default: 'hash' +}; +``` + +## subMaxLevel + +- Type: `Number` +- Default: `0` + +Add table of contents (TOC) in custom sidebar. + +```js +window.$docsify = { + subMaxLevel: 2, +}; +``` + +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) +``` + +For more details, see [#1131](https://github.com/docsifyjs/docsify/issues/1131). + +## themeColor + +- 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 = { + themeColor: '#3F51B5', +}; +``` + ## 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 5830656a..23573676 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, - 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', - noCompileLinks: [], - crossOriginLinks: [], - relativePath: false, - topMargin: 0, + basePath: '', catchPluginErrors: true, + cornerExternalLinkTarget: '_blank', + coverpage: '', + crossOriginLinks: [], + el: '#app', + executeScript: null, + ext: '.md', + externalLinkRel: 'noopener', + externalLinkTarget: '_blank', + formatUpdated: '', + ga: '', + homepage: 'README.md', + loadNavbar: null, + loadSidebar: null, + maxLevel: 6, + mergeNavbar: false, + name: '', + nameLink: window.location.pathname, + nativeEmoji: false, + noCompileLinks: [], + noEmoji: false, + notFoundPage: true, + relativePath: false, + repo: '', + routerMode: 'hash', + subMaxLevel: 0, + themeColor: '', + topMargin: 0, }, typeof window.$docsify === 'function' ? window.$docsify(vm)