From 51617adba67ee733669f251fc8af8b45a84677f0 Mon Sep 17 00:00:00 2001 From: John Hildenbiddle Date: Fri, 18 Mar 2022 10:52:29 -0500 Subject: [PATCH] docs: Update configuration options (#1773) --- docs/configuration.md | 557 +++++++++++++++++++++--------------------- src/core/config.js | 47 ++-- 2 files changed, 308 insertions(+), 296 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 6f0c4e475b..8365a93d65 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 5830656a93..2357367641 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)