@@ -27,6 +31,7 @@
## Links
+- [`develop` branch preview](https://docsifyjs.netlify.com/)
- [Documentation](https://docsify.js.org)
- [CLI](https://github.com/docsifyjs/docsify-cli)
- CDN: [UNPKG](https://unpkg.com/docsify/) | [jsDelivr](https://cdn.jsdelivr.net/npm/docsify/) | [cdnjs](https://cdnjs.com/libraries/docsify)
@@ -36,11 +41,11 @@
## Features
- No statically built html files
-- Simple and lightweight (~21kB gzipped)
+- Simple and lightweight
- Smart full-text search plugin
- Multiple themes
- Useful plugin API
-- Compatible with IE10+
+- Compatible with IE11
- Support SSR ([example](https://github.com/docsifyjs/docsify-ssr-demo))
- Support embedded files
@@ -54,7 +59,7 @@ Look at [this tutorial](https://docsify.js.org/#/quickstart)
These projects are using docsify to generate their sites. Pull requests welcome :blush:
-Move to [awesome-docsify](https://github.com/docsifyjs/awesome-docsify)
+Move to [awesome-docsify](https://github.com/docsifyjs/awesome-docsify#showcase)
## Similar projects
@@ -65,9 +70,21 @@ Move to [awesome-docsify](https://github.com/docsifyjs/awesome-docsify)
## Contributing
+### Online one-click setup for Contributing
+
+You can use Gitpod(A free online VS Code-like IDE) for contributing. With single click it'll launch a workspace and automatically:
+
+- clone the docsify repo.
+- install the dependencies.
+- start `npm run dev`.
+
+So that you can start straight away.
+
+[](https://gitpod.io/#https://github.com/docsifyjs/docsify)
+
- Fork it!
- Create your feature branch: `git checkout -b my-new-feature`
-- Commit your changes: `git commit -am 'Add some feature'`
+- Commit your changes: `git add . && git commit -m 'Add some feature'`
- Push to the branch: `git push origin my-new-feature`
- Submit a pull request
@@ -107,4 +124,8 @@ This project exists thanks to all the people who contribute. [[Contribute](CONTR
[MIT](LICENSE)
-[](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fdocsifyjs%2Fdocsify?ref=badge_large)
+## Special Thanks
+
+_Vercel_ has given us a Pro account.
+
+
diff --git a/babel.config.js b/babel.config.js
new file mode 100644
index 000000000..f037a1a2a
--- /dev/null
+++ b/babel.config.js
@@ -0,0 +1,12 @@
+module.exports = {
+ presets: [
+ [
+ '@babel/preset-env',
+ {
+ targets: {
+ node: 'current',
+ },
+ },
+ ],
+ ],
+};
diff --git a/build/build.js b/build/build.js
index b9068b91d..0de786828 100644
--- a/build/build.js
+++ b/build/build.js
@@ -2,59 +2,85 @@ const rollup = require('rollup')
const buble = require('rollup-plugin-buble')
const commonjs = require('rollup-plugin-commonjs')
const nodeResolve = require('rollup-plugin-node-resolve')
-const uglify = require('rollup-plugin-uglify')
+const { uglify } = require('rollup-plugin-uglify')
const replace = require('rollup-plugin-replace')
const isProd = process.env.NODE_ENV === 'production'
const version = process.env.VERSION || require('../package.json').version
const chokidar = require('chokidar')
const path = require('path')
-const build = function (opts) {
- rollup
+/**
+ * @param {{
+ * input: string,
+ * output?: string,
+ * globalName?: string,
+ * plugins?: Array
+ * }} opts
+ */
+async function build(opts) {
+ await rollup
.rollup({
input: opts.input,
plugins: (opts.plugins || []).concat([
- buble(),
+ buble({
+ transforms: {
+ dangerousForOf: true
+ }}),
commonjs(),
nodeResolve(),
replace({
__VERSION__: version,
'process.env.SSR': false
})
- ])
+ ]),
+ onwarn: function (message) {
+ if (message.code === 'UNRESOLVED_IMPORT') {
+ throw new Error(
+ `Could not resolve module ` +
+ message.source +
+ `. Try running 'npm install' or using rollup's 'external' option if this is an external dependency. ` +
+ `Module ${message.source} is imported in ${message.importer}`
+ )
+ }
+ }
})
.then(function (bundle) {
var dest = 'lib/' + (opts.output || opts.input)
console.log(dest)
- bundle.write({
+ return bundle.write({
format: 'iife',
+ output: opts.globalName ? {name: opts.globalName} : {},
file: dest,
strict: false
})
})
- .catch(function (err) {
- console.error(err)
- })
}
-const buildCore = function () {
- build({
+
+async function buildCore() {
+ const promises = []
+
+ promises.push(build({
input: 'src/core/index.js',
- output: 'docsify.js'
- })
+ output: 'docsify.js',
+ }))
if (isProd) {
- build({
+ promises.push(build({
input: 'src/core/index.js',
output: 'docsify.min.js',
plugins: [uglify()]
- })
+ }))
}
+
+ await Promise.all(promises)
}
-const buildAllPlugin = function () {
+
+async function buildAllPlugin() {
var plugins = [
{name: 'search', input: 'search/index.js'},
{name: 'ga', input: 'ga.js'},
+ {name: 'matomo', input: 'matomo.js'},
{name: 'emoji', input: 'emoji.js'},
{name: 'external-script', input: 'external-script.js'},
{name: 'front-matter', input: 'front-matter/index.js'},
@@ -63,8 +89,8 @@ const buildAllPlugin = function () {
{name: 'gitalk', input: 'gitalk.js'}
]
- plugins.forEach(item => {
- build({
+ const promises = plugins.map(item => {
+ return build({
input: 'src/plugins/' + item.input,
output: 'plugins/' + item.name + '.js'
})
@@ -72,47 +98,59 @@ const buildAllPlugin = function () {
if (isProd) {
plugins.forEach(item => {
- build({
+ promises.push(build({
input: 'src/plugins/' + item.input,
output: 'plugins/' + item.name + '.min.js',
plugins: [uglify()]
- })
+ }))
})
}
+
+ await Promise.all(promises)
}
-if (!isProd) {
- chokidar
- .watch(['src/core', 'src/plugins'], {
- atomic: true,
- awaitWriteFinish: {
- stabilityThreshold: 1000,
- pollInterval: 100
- }
- })
- .on('change', p => {
- console.log('[watch] ', p)
- const dirs = p.split(path.sep)
- if (dirs[1] === 'core') {
- buildCore()
- } else if (dirs[2]) {
- const name = path.basename(dirs[2], '.js')
- const input = `src/plugins/${name}${
- /\.js/.test(dirs[2]) ? '' : '/index'
- }.js`
+async function main() {
+ if (!isProd) {
+ chokidar
+ .watch(['src/core', 'src/plugins'], {
+ atomic: true,
+ awaitWriteFinish: {
+ stabilityThreshold: 1000,
+ pollInterval: 100
+ }
+ })
+ .on('change', p => {
+ console.log('[watch] ', p)
+ const dirs = p.split(path.sep)
+ if (dirs[1] === 'core') {
+ buildCore()
+ } else if (dirs[2]) {
+ const name = path.basename(dirs[2], '.js')
+ const input = `src/plugins/${name}${
+ /\.js/.test(dirs[2]) ? '' : '/index'
+ }.js`
- build({
- input,
- output: 'plugins/' + name + '.js'
- })
- }
- })
- .on('ready', () => {
- console.log('[start]')
- buildCore()
+ build({
+ input,
+ output: 'plugins/' + name + '.js'
+ })
+ }
+ })
+ .on('ready', () => {
+ console.log('[start]')
+ buildCore()
+ buildAllPlugin()
+ })
+ } else {
+ await Promise.all([
+ buildCore(),
buildAllPlugin()
- })
-} else {
- buildCore()
- buildAllPlugin()
+ ])
+ }
}
+
+main().catch((e) => {
+ console.error(e)
+ process.exit(1)
+})
+
diff --git a/build/css.js b/build/css.js
new file mode 100644
index 000000000..2214f3fe4
--- /dev/null
+++ b/build/css.js
@@ -0,0 +1,47 @@
+const fs = require('fs')
+const path = require('path')
+const {spawn} = require('child_process')
+
+const args = process.argv.slice(2)
+fs.readdir(path.join(__dirname, '../src/themes'), (err, files) => {
+ if (err) {
+ console.error('err', err)
+ process.exit(1)
+ }
+ files.map(async (file) => {
+ if (/\.styl/g.test(file)) {
+ var stylusCMD;
+ const stylusBin = ['node_modules', 'stylus', 'bin', 'stylus'].join(path.sep)
+ var cmdargs = [
+ stylusBin,
+ `src/themes/${file}`,
+ '-u',
+ 'autoprefixer-stylus'
+ ]
+ cmdargs = cmdargs.concat(args)
+
+ stylusCMD = spawn('node', cmdargs, { shell: true })
+
+ stylusCMD.stdout.on('data', (data) => {
+ console.log(`[Stylus Build ] stdout: ${data}`);
+ });
+
+ stylusCMD.stderr.on('data', (data) => {
+ console.error(`[Stylus Build ] stderr: ${data}`);
+ });
+
+ stylusCMD.on('close', (code) => {
+ const message = `[Stylus Build ] child process exited with code ${code}`
+
+ if (code !== 0) {
+ console.error(message);
+ process.exit(code)
+ }
+ console.log(message);
+ });
+ } else {
+ return
+ }
+
+ })
+})
diff --git a/build/mincss.js b/build/mincss.js
index f6c5ec215..0c9c72280 100644
--- a/build/mincss.js
+++ b/build/mincss.js
@@ -8,5 +8,8 @@ files.forEach(file => {
file = path.resolve('lib/themes', file)
cssnano(fs.readFileSync(file)).then(result => {
fs.writeFileSync(file, result.css)
+ }).catch(e => {
+ console.error(e)
+ process.exit(1)
})
})
diff --git a/build/release.sh b/build/release.sh
old mode 100644
new mode 100755
index da15a38a6..d27275215
--- a/build/release.sh
+++ b/build/release.sh
@@ -12,7 +12,9 @@ echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
echo "Releasing $VERSION ..."
- npm run test
+ # Removing test script as non - availibity of tests. Will Add it once tests are completed
+
+ # npm run test
# build
VERSION=$VERSION npm run build
@@ -29,7 +31,6 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
# commit
git add -A
- git add -f lib/ -A
git commit -m "[build] $VERSION $RELEASE_TAG"
npm --no-git-tag-version version $VERSION --message "[release] $VERSION $RELEASE_TAG"
diff --git a/build/ssr.js b/build/ssr.js
index 16b93cac4..01fdd0518 100644
--- a/build/ssr.js
+++ b/build/ssr.js
@@ -24,11 +24,12 @@ rollup
var dest = 'packages/docsify-server-renderer/build.js'
console.log(dest)
- bundle.write({
+ return bundle.write({
format: 'cjs',
file: dest
})
})
.catch(function (err) {
console.error(err)
+ process.exit(1)
})
diff --git a/docs/README.md b/docs/README.md
index d27f1ae20..8a7c962ca 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,17 +11,17 @@ See the [Quick start](quickstart.md) guide for more details.
## Features
- No statically built html files
-- Simple and lightweight (~21kB gzipped)
+- Simple and lightweight
- Smart full-text search plugin
- Multiple themes
- Useful plugin API
- Emoji support
-- Compatible with IE10+
+- Compatible with IE11
- Support server-side rendering ([example](https://github.com/docsifyjs/docsify-ssr-demo))
## Examples
-Check out the [Showcase](https://github.com/docsifyjs/docsify/#showcase) to see docsify in use.
+Check out the [Showcase](https://github.com/docsifyjs/awesome-docsify#showcase) to see docsify in use.
## Donate
@@ -30,3 +30,9 @@ Please consider donating if you think docsify is helpful to you or that my work
## Community
Users and the development team are usually in the [Gitter chat room](https://gitter.im/docsifyjs/Lobby).
+
+## Special Thanks
+
+_Vercel_ has given us a Pro account.
+
+
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
index 7b7c327ea..ab31e601d 100644
--- a/docs/_coverpage.md
+++ b/docs/_coverpage.md
@@ -1,10 +1,10 @@
-# docsify 4.8.6
+# docsify 4.12.0
> A magical documentation site generator.
-- Simple and lightweight (~21kB gzipped)
+- Simple and lightweight
- No statically built html files
- Multiple themes
diff --git a/docs/_media/example-with-yaml.md b/docs/_media/example-with-yaml.md
new file mode 100644
index 000000000..081bedde2
--- /dev/null
+++ b/docs/_media/example-with-yaml.md
@@ -0,0 +1,6 @@
+---
+author: John Smith
+date: 2020-1-1
+---
+
+> This is from the `example.md`
diff --git a/docs/_media/example.js b/docs/_media/example.js
new file mode 100644
index 000000000..8cad2d730
--- /dev/null
+++ b/docs/_media/example.js
@@ -0,0 +1,16 @@
+import fetch from 'fetch'
+
+const URL = 'https://example.com/'
+const PORT = 8080
+
+/// [demo]
+const result = fetch(`${URL}:${PORT}`)
+ .then(function (response) {
+ return response.json()
+ })
+ .then(function (myJson) {
+ console.log(JSON.stringify(myJson))
+ })
+/// [demo]
+
+result.then(console.log).catch(console.error)
diff --git a/docs/_media/vercel_logo.svg b/docs/_media/vercel_logo.svg
new file mode 100644
index 000000000..50a17b35e
--- /dev/null
+++ b/docs/_media/vercel_logo.svg
@@ -0,0 +1 @@
+
diff --git a/docs/_navbar.md b/docs/_navbar.md
index 47a2356a9..0248daea6 100644
--- a/docs/_navbar.md
+++ b/docs/_navbar.md
@@ -2,5 +2,5 @@
- [:uk: English](/)
- [:cn: 中文](/zh-cn/)
- [:de: Deutsch](/de-de/)
- - [:es: Spanish](/es/)
- - [:ru: Russian](/ru/)
+ - [:es: Español](/es/)
+ - [:ru: Русский](/ru-ru/)
diff --git a/docs/cdn.md b/docs/cdn.md
index eba77a845..05fff3c28 100644
--- a/docs/cdn.md
+++ b/docs/cdn.md
@@ -1,15 +1,15 @@
# CDN
-Recommended: [unpkg](//unpkg.com), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [unpkg.com/docsify/](//unpkg.com/docsify/).
+Recommended: [jsDelivr](//cdn.jsdelivr.net), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [cdn.jsdelivr.net/npm/docsify/](//cdn.jsdelivr.net/npm/docsify/).
## Latest version
```html
-
+
-
+
```
Alternatively, use [compressed files](#compressed-file).
@@ -18,33 +18,33 @@ Alternatively, use [compressed files](#compressed-file).
```html
-
+
-
+
```
## Compressed file
```html
-
+
-
+
```
```html
-
+
-
+
```
## Other CDN
-- http://www.bootcdn.cn/docsify
+- https://www.bootcdn.cn/docsify/
- https://cdn.jsdelivr.net/npm/docsify/
- https://cdnjs.com/libraries/docsify
-
+- https://unpkg.com/browse/docsify/
diff --git a/docs/configuration.md b/docs/configuration.md
index 830748f37..7b3b5fcda 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,14 +1,32 @@
# Configuration
-You can configure the `window.$docsify`.
+You can configure Docsify by defining `window.$docsify` as an object:
```html
+```
+
+The config can also be defined as a function, in which case the first argument is the Docsify `vm` instance. The function should return a config object. This can be useful for referencing `vm` in places like the markdown configuration:
+
+```html
+
```
@@ -17,11 +35,11 @@ You can configure the `window.$docsify`.
- Type: `String`
- Default: `#app`
-The DOM element to be mounted on initialization. It can be a CSS selector string or an actual HTMLElement.
+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 = {
- el: '#app'
+ el: '#app',
};
```
@@ -30,13 +48,13 @@ window.$docsify = {
- Type: `String`
- Default: `null`
-Configure the repository url or a string of `username/repo` can add the [GitHub Corner](http://tholman.com/github-corners/) widget in the top right corner of the site.
+Configure the repository url, or a string of `username/repo` can 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/'
+ repo: 'https://github.com/docsifyjs/docsify/',
};
```
@@ -49,7 +67,7 @@ Maximum Table of content level.
```js
window.$docsify = {
- maxLevel: 4
+ maxLevel: 4,
};
```
@@ -58,7 +76,7 @@ window.$docsify = {
- Type: `Boolean|String`
- Default: `false`
-Loads navbar from the Markdown file `_navbar.md` if **true**, or else from the path specified.
+Loads navbar from the Markdown file `_navbar.md` if **true**, else loads it from the path specified.
```js
window.$docsify = {
@@ -66,7 +84,7 @@ window.$docsify = {
loadNavbar: true,
// load from nav.md
- loadNavbar: 'nav.md'
+ loadNavbar: 'nav.md',
};
```
@@ -75,7 +93,7 @@ window.$docsify = {
- Type: `Boolean|String`
- Default: `false`
-Loads sidebar from the Markdown file `_sidebar.md` if **true**, or else from the path specified.
+Loads sidebar from the Markdown file `_sidebar.md` if **true**, else loads it from the path specified.
```js
window.$docsify = {
@@ -83,7 +101,20 @@ window.$docsify = {
loadSidebar: true,
// load from summary.md
- loadSidebar: 'summary.md'
+ loadSidebar: 'summary.md',
+};
+```
+
+## 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,
};
```
@@ -96,7 +127,7 @@ Add table of contents (TOC) in custom sidebar.
```js
window.$docsify = {
- subMaxLevel: 2
+ subMaxLevel: 2,
};
```
@@ -109,7 +140,7 @@ Scrolls to the top of the screen when the route is changed.
```js
window.$docsify = {
- auto2top: true
+ auto2top: true,
};
```
@@ -118,7 +149,7 @@ window.$docsify = {
- Type: `String`
- Default: `README.md`
-`README.md` in your docs folder will be treated as homepage for your website, but sometimes you may need to serve another file as your homepage.
+`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 = {
@@ -127,10 +158,20 @@ window.$docsify = {
// Or use the readme in your repo
homepage:
- 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md'
+ '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`
@@ -146,7 +187,47 @@ window.$docsify = {
// Even can load files from other repo
basePath:
- 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/'
+ '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,
};
```
@@ -164,14 +245,14 @@ window.$docsify = {
// Custom file name
coverpage: 'cover.md',
- // mutiple covers
+ // multiple covers
coverpage: ['/', '/zh-cn/'],
- // mutiple covers and custom file name
+ // multiple covers and custom file name
coverpage: {
'/': 'cover.md',
- '/zh-cn/': 'cover.md'
- }
+ '/zh-cn/': 'cover.md',
+ },
};
```
@@ -179,11 +260,11 @@ window.$docsify = {
- Type: `String`
-Website logo as it appears in the sidebar, you can resize by CSS.
+Website logo as it appears in the sidebar. You can resize it by using CSS.
```js
window.$docsify = {
- logo: '/_media/icon.svg'
+ logo: '/_media/icon.svg',
};
```
@@ -195,7 +276,15 @@ Website name as it appears in the sidebar.
```js
window.$docsify = {
- name: 'docsify'
+ name: 'docsify',
+};
+```
+
+The name field can also contain custom HTML for easier customization:
+
+```js
+window.$docsify = {
+ name: 'docsify',
};
```
@@ -204,7 +293,7 @@ window.$docsify = {
- Type: `String`
- Default: `window.location.pathname`
-The name of the link.
+The URL that the website `name` links to.
```js
window.$docsify = {
@@ -213,8 +302,8 @@ window.$docsify = {
// For each route
nameLink: {
'/zh-cn/': '/zh-cn/',
- '/': '/'
- }
+ '/': '/',
+ },
};
```
@@ -232,15 +321,15 @@ window.$docsify = {
renderer: {
link: function() {
// ...
- }
- }
+ },
+ },
},
// function
markdown: function(marked, renderer) {
// ...
return marked;
- }
+ },
};
```
@@ -252,7 +341,7 @@ Customize the theme color. Use [CSS3 variables](https://developer.mozilla.org/en
```js
window.$docsify = {
- themeColor: '#3F51B5'
+ themeColor: '#3F51B5',
};
```
@@ -269,8 +358,8 @@ window.$docsify = {
'/zh-cn/changelog': '/changelog',
'/changelog':
'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
- '/.*/_sidebar.md': '/_sidebar.md' // See #301
- }
+ '/.*/_sidebar.md': '/_sidebar.md', // See #301
+ },
};
```
@@ -278,12 +367,12 @@ window.$docsify = {
- 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. Compare [#78](https://github.com/docsifyjs/docsify/issues/78).
+If `loadSidebar` and `autoHeader` are both enabled, for each link in `_sidebar.md`, prepend a header to the page before converting it to HTML. Compare [#78](https://github.com/docsifyjs/docsify/issues/78).
```js
window.$docsify = {
loadSidebar: true,
- autoHeader: true
+ autoHeader: true,
};
```
@@ -295,7 +384,7 @@ Execute the script on the page. Only parse the first script tag([demo](themes)).
```js
window.$docsify = {
- executeScript: true
+ executeScript: true,
};
```
@@ -317,10 +406,12 @@ Disabled emoji parse.
```js
window.$docsify = {
- noEmoji: true
+ noEmoji: true,
};
```
+?> If this options is `false` but you don't want to emojify some specific colons , [Refer this](https://github.com/docsifyjs/docsify/issues/742#issuecomment-586313143)
+
## mergeNavbar
- type: `Boolean`
@@ -329,7 +420,7 @@ Navbar will be merged with the sidebar on smaller screens.
```js
window.$docsify = {
- mergeNavbar: true
+ mergeNavbar: true,
};
```
@@ -348,7 +439,7 @@ window.$docsify = {
// ...
return time;
- }
+ },
};
```
@@ -357,11 +448,37 @@ window.$docsify = {
- type: `String`
- default: `_blank`
-Target to open external links. Default `'_blank'` (new window/tab)
+Target to open external links inside the markdown. Default `'_blank'` (new window/tab)
```js
window.$docsify = {
- externalLinkTarget: '_self' // default: '_blank'
+ 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'
};
```
@@ -372,7 +489,20 @@ window.$docsify = {
```js
window.$docsify = {
- routerMode: 'history' // default: 'hash'
+ routerMode: 'history', // default: 'hash'
+};
+```
+
+## crossOriginLinks
+
+- type: `Array`
+
+When `routerMode: 'history'`, you may face the 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'],
};
```
@@ -384,7 +514,7 @@ Sometimes we do not want docsify to handle our links. See [#203](https://github.
```js
window.$docsify = {
- noCompileLinks: ['/foo', '/bar/.*']
+ noCompileLinks: ['/foo', '/bar/.*'],
};
```
@@ -396,7 +526,7 @@ Only coverpage is loaded when visiting the home page.
```js
window.$docsify = {
- onlyCover: false
+ onlyCover: false,
};
```
@@ -409,8 +539,18 @@ Set the request resource headers.
```js
window.$docsify = {
requestHeaders: {
- 'x-token': 'xxx'
- }
+ 'x-token': 'xxx',
+ },
+};
+```
+
+Such as setting the cache
+
+```js
+window.$docsify = {
+ requestHeaders: {
+ 'cache-control': 'max-age=600',
+ },
};
```
@@ -422,7 +562,7 @@ Request file extension.
```js
window.$docsify = {
- ext: '.md'
+ ext: '.md',
};
```
@@ -430,17 +570,17 @@ window.$docsify = {
- type: `Array`
-List of languages that will fallback to the default language when a page is request and didn't exists for the given local.
+List of languages that will fallback to the default language when a page is requested and it doesn't exist for the given local.
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 404 page.
+- 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']
+ fallbackLanguages: ['fr', 'de'],
};
```
@@ -452,27 +592,141 @@ Load the `_404.md` file:
```js
window.$docsify = {
- notFoundPage: true
+ notFoundPage: true,
};
```
-Load the customised path of the 404 page:
+Load the customized path of the 404 page:
```js
window.$docsify = {
- notFoundPage: 'my404.md'
+ notFoundPage: 'my404.md',
};
```
-Load the right 404 page according to the localisation:
+Load the right 404 page according to the localization:
```js
window.$docsify = {
notFoundPage: {
'/': '_404.md',
- '/de': 'de/_404.md'
- }
+ '/de': 'de/_404.md',
+ },
};
```
> Note: The options with fallbackLanguages didn't work with the `notFoundPage` options.
+
+## topMargin
+
+- type: `Number`
+- default: `0`
+
+Adds a space on top when scrolling content page to reach the selected section. This is useful in case you have a _sticky-header_ layout and you want to align anchors to the end of your header.
+
+```js
+window.$docsify = {
+ topMargin: 90, // default: 0
+};
+```
+
+## vueComponents
+
+- type: `Object`
+
+Creates and registers global [Vue components](https://vuejs.org/v2/guide/components.html). Components are specified using the component name as the key with an object containing Vue options as the value. Component `data` is unique for each instance and will not persist as users navigate the site.
+
+```js
+window.$docsify = {
+ vueComponents: {
+ 'button-counter': {
+ template: `
+
+ `,
+ data() {
+ return {
+ count: 0,
+ };
+ },
+ },
+ },
+};
+```
+
+```markdown
+
+```
+
+
+
+## vueGlobalOptions
+
+- type: `Object`
+
+Specifies [Vue options](https://vuejs.org/v2/api/#Options-Data) for use with Vue content not explicitly mounted with [vueMounts](#mounting-dom-elements), [vueComponents](#components), or a [markdown script](#markdown-script). Changes to global `data` will persist and be reflected anywhere global references are used.
+
+```js
+window.$docsify = {
+ vueGlobalOptions: {
+ data() {
+ return {
+ count: 0,
+ };
+ },
+ },
+};
+```
+
+```markdown
+
+
+ {{ count }}
+
+
+```
+
+
+
+## vueMounts
+
+- type: `Object`
+
+Specifies DOM elements to mount as [Vue instances](https://vuejs.org/v2/guide/instance.html) and their associated options. Mount elements are specified using a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) as the key with an object containing Vue options as their value. Docsify will mount the first matching element in the main content area each time a new page is loaded. Mount element `data` is unique for each instance and will not persist as users navigate the site.
+
+```js
+window.$docsify = {
+ vueMounts: {
+ '#counter': {
+ data() {
+ return {
+ count: 0,
+ };
+ },
+ },
+ },
+};
+```
+
+```markdown
+
+
+ {{ count }}
+
+
+```
+
+
diff --git a/docs/cover.md b/docs/cover.md
index 555f4ff7a..a8da3083d 100644
--- a/docs/cover.md
+++ b/docs/cover.md
@@ -14,7 +14,7 @@ Set `coverpage` to **true**, and create a `_coverpage.md`:
coverpage: true
}
-
+
```
```markdown
@@ -26,7 +26,7 @@ Set `coverpage` to **true**, and create a `_coverpage.md`:
> A magical documentation site generator.
-- Simple and lightweight (~21kB gzipped)
+- Simple and lightweight
- No statically built html files
- Multiple themes
@@ -34,8 +34,6 @@ Set `coverpage` to **true**, and create a `_coverpage.md`:
[Get Started](#docsify)
```
-!> A document site can have only one coverpage!
-
## Custom background
The background color is generated randomly by default. You can customize the background color or a background image:
diff --git a/docs/custom-navbar.md b/docs/custom-navbar.md
index 324ad8104..14b6c8b3b 100644
--- a/docs/custom-navbar.md
+++ b/docs/custom-navbar.md
@@ -30,7 +30,7 @@ Alternatively, you can create a custom markdown-based navigation file by setting
loadNavbar: true
}
-
+
```
```markdown
@@ -82,8 +82,8 @@ If you use the [emoji plugin](plugins#emoji):
// ...
}
-
-
+
+
```
you could, for example, use flag emojis in your custom navbar Markdown file:
diff --git a/docs/deploy.md b/docs/deploy.md
index fdf016716..2c96060f9 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -15,7 +15,7 @@ It is recommended that you save your files to the `./docs` subfolder of the `mas
!> You can also save files in the root directory and select `master branch`.
-You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch
+You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch)
## GitLab Pages
@@ -82,8 +82,102 @@ server {
### HTML5 router
-When using the HTML5 router, you need to set up redirect rules that redirect all requests to your `index.html`, it's pretty simple when you're using Netlify, populate a `\redirects` file in the docs directory and you're all set:
+When using the HTML5 router, you need to set up redirect rules that redirect all requests to your `index.html`, it's pretty simple when you're using Netlify, create a file named `_redirects` in the docs directory, add this snippet to the file and you're all set:
```sh
/* /index.html 200
```
+
+## ZEIT Now
+
+1. Install [Now CLI](https://zeit.co/download), `npm i -g now`
+2. Change directory to your docsify website, for example `cd docs`
+3. Deploy with a single command, `now`
+
+## AWS Amplify
+
+1. Set the routerMode in the Docsify project `index.html` to *history* mode.
+
+```html
+
+```
+
+2. Login to your [AWS Console](https://aws.amazon.com).
+3. Go to the [AWS Amplify Dashboard](https://aws.amazon.com/amplify).
+4. Choose the **Deploy** route to setup your project.
+5. When prompted, keep the build settings empty if you're serving your docs within the root directory. If you're serving your docs from a different directory, customise your amplify.yml
+
+```yml
+version: 0.1
+frontend:
+ phases:
+ build:
+ commands:
+ - echo "Nothing to build"
+ artifacts:
+ baseDirectory: /docs
+ files:
+ - '**/*'
+ cache:
+ paths: []
+
+```
+
+6. Add the following Redirect rules in their displayed order. Note that the second record is a PNG image where you can change it with any image format you are using.
+
+| Source address | Target address | Type |
+|----------------|----------------|---------------|
+| /<*>.md | /<*>.md | 200 (Rewrite) |
+| /<*>.png | /<*>.png | 200 (Rewrite) |
+| /<*> | /index.html | 200 (Rewrite) |
+
+
+## Docker
+
+- Create docsify files
+
+ You need prepare the initial files instead of making in container.
+ See the [Quickstart](https://docsify.js.org/#/quickstart) section for instructions on how to create these files manually or using [docsify-cli](https://github.com/docsifyjs/docsify-cli).
+
+ ```sh
+ index.html
+ README.md
+ ```
+
+- Create dockerfile
+
+ ```Dockerfile
+ FROM node:latest
+ LABEL description="A demo Dockerfile for build Docsify."
+ WORKDIR /docs
+ RUN npm install -g docsify-cli@latest
+ EXPOSE 3000/tcp
+ ENTRYPOINT docsify serve .
+
+ ```
+
+ So, current directory structure should be this:
+
+ ```sh
+ index.html
+ README.md
+ Dockerfile
+ ```
+
+- Build docker image
+
+ ```sh
+ docker build -f Dockerfile -t docsify/demo .
+ ```
+
+- Run docker image
+
+ ```sh
+ docker run -itp 3000:3000 --name=docsify -v $(pwd):/docs docsify/demo
+ ```
+
diff --git a/docs/embed-files.md b/docs/embed-files.md
index a935dd374..26a0072ea 100644
--- a/docs/embed-files.md
+++ b/docs/embed-files.md
@@ -1,15 +1,16 @@
# Embed files
With docsify 4.6 it is now possible to embed any type of file.
+
You can embed these files as video, audio, iframes, or code blocks, and even Markdown files can even be embedded directly into the document.
-For example, here embedded a Markdown file. You only need to do this:
+For example, here is an embedded Markdown file. You only need to do this:
```markdown
[filename](_media/example.md ':include')
```
-Then the content of `example.md` will be displayed directly here
+Then the content of `example.md` will be displayed directly here;
[filename](_media/example.md ':include')
@@ -17,11 +18,13 @@ You can check the original content for [example.md](_media/example.md ':ignore')
Normally, this will compiled into a link, but in docsify, if you add `:include` it will be embedded.
+External links can be used too - just replace the target. If you want to use a gist URL, see [Embed a gist](#embed-a-gist) section.
+
## Embedded file type
-Currently, file extension are automatically recognized and embedded in different ways.
+Currently, file extensions are automatically recognized and embedded in different ways.
-This is a supported embedding type:
+These types are supported:
* **iframe** `.html`, `.htm`
* **markdown** `.markdown`, `.md`
@@ -29,16 +32,43 @@ This is a supported embedding type:
* **video** `.mp4`, `.ogg`
* **code** other file extension
-Of course, you can force the specified. For example, you want to Markdown file as code block embedded.
+Of course, you can force the specified type. For example, a Markdown file can be embedded as a code block by setting `:type=code`.
```markdown
[filename](_media/example.md ':include :type=code')
```
-You will get it
+You will get:
[filename](_media/example.md ':include :type=code')
+## Markdown with YAML Front Matter
+
+When using Markdown, YAML front matter will be stripped from the rendered content. The attributes cannot be used in this case.
+
+```markdown
+[filename](_media/example-with-yaml.md ':include')
+```
+
+You will get just the content
+
+[filename](_media/example-with-yaml.md ':include')
+
+## Embedded code fragments
+
+Sometimes you don't want to embed a whole file. Maybe because you need just a few lines but you want to compile and test the file in CI.
+
+```markdown
+[filename](_media/example.js ':include :type=code :fragment=demo')
+```
+
+In your code file you need to surround the fragment between `/// [demo]` lines (before and after the fragment).
+Alternatively you can use `### [demo]`.
+
+Example:
+
+[filename](_media/example.js ':include :type=code :fragment=demo')
+
## Tag attribute
If you embed the file as `iframe`, `audio` and `video`, then you may need to set the attributes of these tags.
@@ -64,3 +94,78 @@ Embedding any type of source code file, you can specify the highlighted language
[](_media/example.html ':include :type=code text')
?> How to set highlight? You can see [here](language-highlight.md).
+
+## Embed a gist
+
+You can embed a gist as markdown content or as a code block - this is based on the approach at the start of [Embed Files](#embed-files) section, but uses a raw gist URL as the target.
+
+?> **No** plugin or app config change is needed here to make this work. In fact, the "Embed" `script` tag that is copied from a gist will _not_ load even if you make plugin or config changes to allow an external script.
+
+### Identify the gist's metadata
+
+Start by viewing a gist on `gist.github.com`. For the purposes of this guide, we use this gist:
+
+- https://gist.github.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15
+
+Identify the following items from the gist:
+
+Field | Example | Description
+--- | --- | ---
+**Username** | `anikethsaha` | The gist's owner.
+**Gist ID** | `c2bece08f27c4277001f123898d16a7c` | Identifier for the gist. This is fixed for the gist's lifetime.
+**Filename** | `content.md` | Select a name of a file in the gist. This needed even on a single-file gist for embedding to work.
+
+You will need those to build the _raw gist URL_ for the target file. This has the following format:
+
+- `https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME`
+
+Here are two examples based on the sample gist:
+
+- https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md
+- https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js
+
+?> Alternatively, you can get a raw URL directly clicking the _Raw_ button on a gist file. But, if you use that approach, just be sure to **remove** the revision number between `raw/` and the filename so that the URL matches the pattern above instead. Otherwise your embedded gist will **not** show the latest content when the gist is updated.
+
+Continue with one of the sections below to embed the gist on a Docsify page.
+
+### Render markdown content from a gist
+
+This is a great way to embed content **seamlessly** in your docs, without sending someone to an external link. This approach is well-suited to reusing a gist of say installation instructions across doc sites of multiple repos. This approach works equally well with a gist owned by your account or by another user.
+
+Here is the format:
+
+```markdown
+[LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include')
+```
+
+For example:
+
+```markdown
+[gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include')
+```
+
+Which renders as:
+
+[gist: content.md](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md ':include')
+
+The `LABEL` can be any text you want. It acts as a _fallback_ message if the link is broken - so it is useful to repeat the filename here in case you need to fix a broken link. It also makes an embedded element easy to read at a glance.
+
+### Render a codeblock from a gist
+
+The format is the same as the previous section, but with `:type=code` added to the alt text. As with the [Embedded file type](#embedded-file-type) section, the syntax highlighting will be **inferred** from the extension (e.g. `.js` or `.py`), so you can leave the `type` set as `code`.
+
+Here is the format:
+
+```markdown
+[LABEL](https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME ':include :type=code')
+```
+
+For example:
+
+```markdown
+[gist: script.js](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js ':include :type=code')
+```
+
+Which renders as:
+
+[gist: script.js](https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js ':include :type=code')
diff --git a/docs/helpers.md b/docs/helpers.md
index b047d3673..46ff81d32 100644
--- a/docs/helpers.md
+++ b/docs/helpers.md
@@ -2,7 +2,9 @@
docsify extends Markdown syntax to make your documents more readable.
-## important content
+> Note: For the special code syntax cases, you'd better put them within a code backticks to avoid any conflicting from configurations or emojis.
+
+## Important content
Important content like:
@@ -63,6 +65,14 @@ You will get `link`html. Do not worry, you can still set ti
[link](/demo ':disabled')
```
+## Cross-Origin link
+
+Only when you both set the `routerMode: 'history'` and `externalLinkTarget: '_self'`, you need add this configuration for those Cross-Origin links.
+
+```md
+[example.com](https://example.com/ ':crossorgin')
+```
+
## Github Task Lists
```md
@@ -81,9 +91,12 @@ You will get `link`html. Do not worry, you can still set ti
- [ ] bim
- [ ] lim
-## Image resizing
+## Image
+
+### Resizing
```md
+
@@ -96,10 +109,22 @@ You will get `link`html. Do not worry, you can still set ti
+### Customise class
+
+```md
+
+```
+
+### Customise ID
+
+```md
+
+```
+
## Customise ID for headings
```md
-### 你好，世界！ :id=hello-world
+### Hello, world! :id=hello-world
```
## Markdown in html tag
diff --git a/docs/index.html b/docs/index.html
index e07c79e98..4ff52e8ee 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,99 +1,234 @@
+
+
+ docsify
+
+
+
+
+
+
+
+
+
+
+
-
+ #carbonads {
+ box-shadow: none !important;
+ width: auto !important;
+ }
+
+
-
-
- 
- 
+
+ 
+ 
+ 
+ 
diff --git a/babel.config.js b/babel.config.js
new file mode 100644
index 000000000..f037a1a2a
--- /dev/null
+++ b/babel.config.js
@@ -0,0 +1,12 @@
+module.exports = {
+ presets: [
+ [
+ '@babel/preset-env',
+ {
+ targets: {
+ node: 'current',
+ },
+ },
+ ],
+ ],
+};
diff --git a/build/build.js b/build/build.js
index b9068b91d..0de786828 100644
--- a/build/build.js
+++ b/build/build.js
@@ -2,59 +2,85 @@ const rollup = require('rollup')
const buble = require('rollup-plugin-buble')
const commonjs = require('rollup-plugin-commonjs')
const nodeResolve = require('rollup-plugin-node-resolve')
-const uglify = require('rollup-plugin-uglify')
+const { uglify } = require('rollup-plugin-uglify')
const replace = require('rollup-plugin-replace')
const isProd = process.env.NODE_ENV === 'production'
const version = process.env.VERSION || require('../package.json').version
const chokidar = require('chokidar')
const path = require('path')
-const build = function (opts) {
- rollup
+/**
+ * @param {{
+ * input: string,
+ * output?: string,
+ * globalName?: string,
+ * plugins?: Array
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
index 7b7c327ea..ab31e601d 100644
--- a/docs/_coverpage.md
+++ b/docs/_coverpage.md
@@ -1,10 +1,10 @@
-# docsify 4.8.6
+# docsify 4.12.0
> A magical documentation site generator.
-- Simple and lightweight (~21kB gzipped)
+- Simple and lightweight
- No statically built html files
- Multiple themes
diff --git a/docs/_media/example-with-yaml.md b/docs/_media/example-with-yaml.md
new file mode 100644
index 000000000..081bedde2
--- /dev/null
+++ b/docs/_media/example-with-yaml.md
@@ -0,0 +1,6 @@
+---
+author: John Smith
+date: 2020-1-1
+---
+
+> This is from the `example.md`
diff --git a/docs/_media/example.js b/docs/_media/example.js
new file mode 100644
index 000000000..8cad2d730
--- /dev/null
+++ b/docs/_media/example.js
@@ -0,0 +1,16 @@
+import fetch from 'fetch'
+
+const URL = 'https://example.com/'
+const PORT = 8080
+
+/// [demo]
+const result = fetch(`${URL}:${PORT}`)
+ .then(function (response) {
+ return response.json()
+ })
+ .then(function (myJson) {
+ console.log(JSON.stringify(myJson))
+ })
+/// [demo]
+
+result.then(console.log).catch(console.error)
diff --git a/docs/_media/vercel_logo.svg b/docs/_media/vercel_logo.svg
new file mode 100644
index 000000000..50a17b35e
--- /dev/null
+++ b/docs/_media/vercel_logo.svg
@@ -0,0 +1 @@
+
diff --git a/docs/_navbar.md b/docs/_navbar.md
index 47a2356a9..0248daea6 100644
--- a/docs/_navbar.md
+++ b/docs/_navbar.md
@@ -2,5 +2,5 @@
- [:uk: English](/)
- [:cn: 中文](/zh-cn/)
- [:de: Deutsch](/de-de/)
- - [:es: Spanish](/es/)
- - [:ru: Russian](/ru/)
+ - [:es: Español](/es/)
+ - [:ru: Русский](/ru-ru/)
diff --git a/docs/cdn.md b/docs/cdn.md
index eba77a845..05fff3c28 100644
--- a/docs/cdn.md
+++ b/docs/cdn.md
@@ -1,15 +1,15 @@
# CDN
-Recommended: [unpkg](//unpkg.com), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [unpkg.com/docsify/](//unpkg.com/docsify/).
+Recommended: [jsDelivr](//cdn.jsdelivr.net), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [cdn.jsdelivr.net/npm/docsify/](//cdn.jsdelivr.net/npm/docsify/).
## Latest version
```html
-
+
-
+
```
Alternatively, use [compressed files](#compressed-file).
@@ -18,33 +18,33 @@ Alternatively, use [compressed files](#compressed-file).
```html
-
+
-
+
```
## Compressed file
```html
-
+
-
+
```
```html
-
+
-
+
```
## Other CDN
-- http://www.bootcdn.cn/docsify
+- https://www.bootcdn.cn/docsify/
- https://cdn.jsdelivr.net/npm/docsify/
- https://cdnjs.com/libraries/docsify
-
+- https://unpkg.com/browse/docsify/
diff --git a/docs/configuration.md b/docs/configuration.md
index 830748f37..7b3b5fcda 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,14 +1,32 @@
# Configuration
-You can configure the `window.$docsify`.
+You can configure Docsify by defining `window.$docsify` as an object:
```html
+```
+
+The config can also be defined as a function, in which case the first argument is the Docsify `vm` instance. The function should return a config object. This can be useful for referencing `vm` in places like the markdown configuration:
+
+```html
+
```
@@ -17,11 +35,11 @@ You can configure the `window.$docsify`.
- Type: `String`
- Default: `#app`
-The DOM element to be mounted on initialization. It can be a CSS selector string or an actual HTMLElement.
+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 = {
- el: '#app'
+ el: '#app',
};
```
@@ -30,13 +48,13 @@ window.$docsify = {
- Type: `String`
- Default: `null`
-Configure the repository url or a string of `username/repo` can add the [GitHub Corner](http://tholman.com/github-corners/) widget in the top right corner of the site.
+Configure the repository url, or a string of `username/repo` can 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/'
+ repo: 'https://github.com/docsifyjs/docsify/',
};
```
@@ -49,7 +67,7 @@ Maximum Table of content level.
```js
window.$docsify = {
- maxLevel: 4
+ maxLevel: 4,
};
```
@@ -58,7 +76,7 @@ window.$docsify = {
- Type: `Boolean|String`
- Default: `false`
-Loads navbar from the Markdown file `_navbar.md` if **true**, or else from the path specified.
+Loads navbar from the Markdown file `_navbar.md` if **true**, else loads it from the path specified.
```js
window.$docsify = {
@@ -66,7 +84,7 @@ window.$docsify = {
loadNavbar: true,
// load from nav.md
- loadNavbar: 'nav.md'
+ loadNavbar: 'nav.md',
};
```
@@ -75,7 +93,7 @@ window.$docsify = {
- Type: `Boolean|String`
- Default: `false`
-Loads sidebar from the Markdown file `_sidebar.md` if **true**, or else from the path specified.
+Loads sidebar from the Markdown file `_sidebar.md` if **true**, else loads it from the path specified.
```js
window.$docsify = {
@@ -83,7 +101,20 @@ window.$docsify = {
loadSidebar: true,
// load from summary.md
- loadSidebar: 'summary.md'
+ loadSidebar: 'summary.md',
+};
+```
+
+## 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,
};
```
@@ -96,7 +127,7 @@ Add table of contents (TOC) in custom sidebar.
```js
window.$docsify = {
- subMaxLevel: 2
+ subMaxLevel: 2,
};
```
@@ -109,7 +140,7 @@ Scrolls to the top of the screen when the route is changed.
```js
window.$docsify = {
- auto2top: true
+ auto2top: true,
};
```
@@ -118,7 +149,7 @@ window.$docsify = {
- Type: `String`
- Default: `README.md`
-`README.md` in your docs folder will be treated as homepage for your website, but sometimes you may need to serve another file as your homepage.
+`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 = {
@@ -127,10 +158,20 @@ window.$docsify = {
// Or use the readme in your repo
homepage:
- 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md'
+ '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`
@@ -146,7 +187,47 @@ window.$docsify = {
// Even can load files from other repo
basePath:
- 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/'
+ '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,
};
```
@@ -164,14 +245,14 @@ window.$docsify = {
// Custom file name
coverpage: 'cover.md',
- // mutiple covers
+ // multiple covers
coverpage: ['/', '/zh-cn/'],
- // mutiple covers and custom file name
+ // multiple covers and custom file name
coverpage: {
'/': 'cover.md',
- '/zh-cn/': 'cover.md'
- }
+ '/zh-cn/': 'cover.md',
+ },
};
```
@@ -179,11 +260,11 @@ window.$docsify = {
- Type: `String`
-Website logo as it appears in the sidebar, you can resize by CSS.
+Website logo as it appears in the sidebar. You can resize it by using CSS.
```js
window.$docsify = {
- logo: '/_media/icon.svg'
+ logo: '/_media/icon.svg',
};
```
@@ -195,7 +276,15 @@ Website name as it appears in the sidebar.
```js
window.$docsify = {
- name: 'docsify'
+ name: 'docsify',
+};
+```
+
+The name field can also contain custom HTML for easier customization:
+
+```js
+window.$docsify = {
+ name: 'docsify',
};
```
@@ -204,7 +293,7 @@ window.$docsify = {
- Type: `String`
- Default: `window.location.pathname`
-The name of the link.
+The URL that the website `name` links to.
```js
window.$docsify = {
@@ -213,8 +302,8 @@ window.$docsify = {
// For each route
nameLink: {
'/zh-cn/': '/zh-cn/',
- '/': '/'
- }
+ '/': '/',
+ },
};
```
@@ -232,15 +321,15 @@ window.$docsify = {
renderer: {
link: function() {
// ...
- }
- }
+ },
+ },
},
// function
markdown: function(marked, renderer) {
// ...
return marked;
- }
+ },
};
```
@@ -252,7 +341,7 @@ Customize the theme color. Use [CSS3 variables](https://developer.mozilla.org/en
```js
window.$docsify = {
- themeColor: '#3F51B5'
+ themeColor: '#3F51B5',
};
```
@@ -269,8 +358,8 @@ window.$docsify = {
'/zh-cn/changelog': '/changelog',
'/changelog':
'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
- '/.*/_sidebar.md': '/_sidebar.md' // See #301
- }
+ '/.*/_sidebar.md': '/_sidebar.md', // See #301
+ },
};
```
@@ -278,12 +367,12 @@ window.$docsify = {
- 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. Compare [#78](https://github.com/docsifyjs/docsify/issues/78).
+If `loadSidebar` and `autoHeader` are both enabled, for each link in `_sidebar.md`, prepend a header to the page before converting it to HTML. Compare [#78](https://github.com/docsifyjs/docsify/issues/78).
```js
window.$docsify = {
loadSidebar: true,
- autoHeader: true
+ autoHeader: true,
};
```
@@ -295,7 +384,7 @@ Execute the script on the page. Only parse the first script tag([demo](themes)).
```js
window.$docsify = {
- executeScript: true
+ executeScript: true,
};
```
@@ -317,10 +406,12 @@ Disabled emoji parse.
```js
window.$docsify = {
- noEmoji: true
+ noEmoji: true,
};
```
+?> If this options is `false` but you don't want to emojify some specific colons , [Refer this](https://github.com/docsifyjs/docsify/issues/742#issuecomment-586313143)
+
## mergeNavbar
- type: `Boolean`
@@ -329,7 +420,7 @@ Navbar will be merged with the sidebar on smaller screens.
```js
window.$docsify = {
- mergeNavbar: true
+ mergeNavbar: true,
};
```
@@ -348,7 +439,7 @@ window.$docsify = {
// ...
return time;
- }
+ },
};
```
@@ -357,11 +448,37 @@ window.$docsify = {
- type: `String`
- default: `_blank`
-Target to open external links. Default `'_blank'` (new window/tab)
+Target to open external links inside the markdown. Default `'_blank'` (new window/tab)
```js
window.$docsify = {
- externalLinkTarget: '_self' // default: '_blank'
+ 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'
};
```
@@ -372,7 +489,20 @@ window.$docsify = {
```js
window.$docsify = {
- routerMode: 'history' // default: 'hash'
+ routerMode: 'history', // default: 'hash'
+};
+```
+
+## crossOriginLinks
+
+- type: `Array`
+
+When `routerMode: 'history'`, you may face the 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'],
};
```
@@ -384,7 +514,7 @@ Sometimes we do not want docsify to handle our links. See [#203](https://github.
```js
window.$docsify = {
- noCompileLinks: ['/foo', '/bar/.*']
+ noCompileLinks: ['/foo', '/bar/.*'],
};
```
@@ -396,7 +526,7 @@ Only coverpage is loaded when visiting the home page.
```js
window.$docsify = {
- onlyCover: false
+ onlyCover: false,
};
```
@@ -409,8 +539,18 @@ Set the request resource headers.
```js
window.$docsify = {
requestHeaders: {
- 'x-token': 'xxx'
- }
+ 'x-token': 'xxx',
+ },
+};
+```
+
+Such as setting the cache
+
+```js
+window.$docsify = {
+ requestHeaders: {
+ 'cache-control': 'max-age=600',
+ },
};
```
@@ -422,7 +562,7 @@ Request file extension.
```js
window.$docsify = {
- ext: '.md'
+ ext: '.md',
};
```
@@ -430,17 +570,17 @@ window.$docsify = {
- type: `Array