## Links
+- [`develop` branch preview](https://docsify-preview.vercel.app/)
- [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)
- [Awesome docsify](https://github.com/docsifyjs/awesome-docsify)
-- [Community chat](https://gitter.im/docsifyjs/Lobby)
+- [Community chat](https://discord.gg/3NwKFyR)
## Features
- No statically built html files
-- Simple and lightweight (~19kB gzipped)
+- Simple and lightweight
- Smart full-text search plugin
- Multiple themes
- Useful plugin API
-- Compatible with IE10+
-- Support SSR ([example](https://github.com/docsifyjs/docsify-ssr-demo))
+- Compatible with IE11
+- Experimental SSR support ([example](https://github.com/docsifyjs/docsify-ssr-demo))
- Support embedded files
## Quick start
-Look at [this tutorial](https://docsify.js.org/#/quickstart) or [online demo](https://jsfiddle.net/7ztb8qsr/1/).
+Look at [this tutorial](https://docsify.js.org/#/quickstart)
+
+[](https://codesandbox.io/s/307qqv236)
## Showcase
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
@@ -63,9 +68,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 a 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
@@ -103,6 +120,8 @@ This project exists thanks to all the people who contribute. [[Contribute](CONTR
## License
-MIT
+[MIT](LICENSE)
+
+## Special Thanks
-[](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fdocsifyjs%2Fdocsify?ref=badge_large)
+A preview of Docsify's PR and develop branch is Powered by
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 000000000..1b9f6f908
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,23 @@
+# Security Policy
+
+If you believe you have found a security vulnerability in docsify, please report it to us asap.
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through our public GitHub issues.**
+
+Send email via :email: maintainers@docsifyjs.org to us.
+
+Please include as much of the following information as possible to help us better understand the possible issue:
+
+- Type of issue (e.g. cross-site scripting)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code
+- Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+Thank you in advance.
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 c7e8c1bf9..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) {
+ .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/emoji.js b/build/emoji.js
new file mode 100644
index 000000000..c19b8e735
--- /dev/null
+++ b/build/emoji.js
@@ -0,0 +1,109 @@
+const axios = require('axios');
+const fs = require('fs');
+const path = require('path');
+
+const filePaths = {
+ emojiMarkdown: path.resolve(process.cwd(), 'docs', 'emoji.md'),
+ emojiJS: path.resolve(
+ process.cwd(),
+ 'src',
+ 'core',
+ 'render',
+ 'emoji-data.js'
+ ),
+};
+
+async function getEmojiData() {
+ const emojiDataURL = 'https://api.github.com/emojis';
+
+ console.info(`- Fetching emoji data from ${emojiDataURL}`);
+
+ const response = await axios.get(emojiDataURL);
+ const baseURL = Object.values(response.data)
+ .find(url => /unicode\//)
+ .split('unicode/')[0];
+ const data = { ...response.data };
+
+ // Remove base URL from emoji URLs
+ Object.entries(data).forEach(
+ ([key, value]) => (data[key] = value.replace(baseURL, ''))
+ );
+
+ console.info(`- Retrieved ${Object.keys(data).length} emoji entries`);
+
+ return {
+ baseURL,
+ data,
+ };
+}
+
+function writeEmojiPage(emojiData) {
+ const isExistingPage = fs.existsSync(filePaths.emojiMarkdown);
+ const emojiPage =
+ (isExistingPage && fs.readFileSync(filePaths.emojiMarkdown, 'utf8')) ||
+ `\n\n`;
+ const emojiRegEx = /(\n)([\s\S]*)(\n)/;
+ const emojiMatch = emojiPage.match(emojiRegEx);
+ const emojiMarkdownStart = emojiMatch[1].trim();
+ const emojiMarkdown = emojiMatch[2].trim();
+ const emojiMarkdownEnd = emojiMatch[3].trim();
+ const newEmojiMarkdown = Object.keys(emojiData.data)
+ .reduce(
+ (preVal, curVal) =>
+ (preVal += `:${curVal}: ` + '`' + `:${curVal}:` + '`' + '\n\n'),
+ ''
+ )
+ .trim();
+
+ if (emojiMarkdown !== newEmojiMarkdown) {
+ const newEmojiPage = emojiPage.replace(
+ emojiMatch[0],
+ `${emojiMarkdownStart}\n\n${newEmojiMarkdown}\n\n${emojiMarkdownEnd}`
+ );
+
+ fs.writeFileSync(filePaths.emojiMarkdown, newEmojiPage);
+
+ console.info(
+ `- ${!isExistingPage ? 'Created' : 'Updated'}: ${filePaths.emojiMarkdown}`
+ );
+ } else {
+ console.info(`- No changes: ${filePaths.emojiMarkdown}`);
+ }
+}
+
+function writeEmojiJS(emojiData) {
+ const isExistingPage = fs.existsSync(filePaths.emojiJS);
+ const emojiJS = isExistingPage && fs.readFileSync(filePaths.emojiJS, 'utf8');
+ const newEmojiJS = [
+ '/* eslint-disable */\n',
+ '// =============================================================================',
+ '// DO NOT EDIT: This file is auto-generated by an /build/emoji.js',
+ '// =============================================================================\n',
+ `export default ${JSON.stringify(emojiData, {}, 2)}`,
+ ].join('\n');
+
+ if (!emojiJS || emojiJS !== newEmojiJS) {
+ fs.writeFileSync(filePaths.emojiJS, newEmojiJS);
+
+ console.info(
+ `- ${!isExistingPage ? 'Created' : 'Updated'}: ${filePaths.emojiJS}`
+ );
+ } else {
+ console.info(`- No changes: ${filePaths.emojiJS}`);
+ }
+}
+
+(async () => {
+ console.info('Build emoji');
+
+ try {
+ const emojiData = await getEmojiData();
+
+ if (emojiData) {
+ writeEmojiPage(emojiData);
+ writeEmojiJS(emojiData);
+ }
+ } catch (err) {
+ console.warn(`- Error: ${err.message}`);
+ }
+})();
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 3a7721d97..63770a4e6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,26 +2,26 @@
> A magical documentation site generator.
-## What is it
+## What it is
-docsify generates your documentation website on the fly. Unlike GitBook, it does not generate static html files. Instead, it smartly loads and parses your Markdown files and displays them as website. All you need to do is create an `index.html` to start and [deploy it on GitHub Pages](deploy.md).
+Docsify generates your documentation website on the fly. Unlike GitBook, it does not generate static html files. Instead, it smartly loads and parses your Markdown files and displays them as a website. To start using it, all you need to do is create an `index.html` and [deploy it on GitHub Pages](deploy.md).
-See the [Quick start](quickstart.md) for more details.
+See the [Quick start](quickstart.md) guide for more details.
## Features
- No statically built html files
-- Simple and lightweight (~19kB gzipped)
+- Simple and lightweight
- Smart full-text search plugin
- Multiple themes
- Useful plugin API
- Emoji support
-- Compatible with IE10+
-- Support SSR ([example](https://github.com/docsifyjs/docsify-ssr-demo))
+- 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 docsify in use.
+Check out the [Showcase](https://github.com/docsifyjs/awesome-docsify#showcase) to see docsify in use.
## Donate
@@ -29,4 +29,4 @@ Please consider donating if you think docsify is helpful to you or that my work
## Community
-Users and development team are in the [Gitter](https://gitter.im/docsifyjs/Lobby).
+Users and the development team are usually in the [Discord server](https://discord.gg/3NwKFyR).
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
index 75264ef42..a67b986f0 100644
--- a/docs/_coverpage.md
+++ b/docs/_coverpage.md
@@ -1,12 +1,12 @@
-# docsify 4.7.0
+# docsify 4.13.1
> A magical documentation site generator.
-* Simple and lightweight (~19kB gzipped)
-* No statically built html files
-* Multiple themes
+- Simple and lightweight
+- No statically built html files
+- Multiple themes
[GitHub](https://github.com/docsifyjs/docsify/)
[Getting Started](#docsify)
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/powered-by-vercel.svg b/docs/_media/powered-by-vercel.svg
new file mode 100644
index 000000000..877828684
--- /dev/null
+++ b/docs/_media/powered-by-vercel.svg
@@ -0,0 +1,6 @@
+
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..229e1d1a2 100644
--- a/docs/_navbar.md
+++ b/docs/_navbar.md
@@ -1,6 +1,6 @@
- Translations
- [:uk: English](/)
- - [:cn: ไธญๆ](/zh-cn/)
+ - [:cn: ็ฎไฝไธญๆ](/zh-cn/)
- [:de: Deutsch](/de-de/)
- - [:es: Spanish](/es/)
- - [:ru: Russian](/ru/)
+ - [:es: Espaรฑol](/es/)
+ - [:ru: ะ ัััะบะธะน](/ru-ru/)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 8dc8c9eed..479881e60 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,28 +1,29 @@
-* Getting started
+- Getting started
- * [Quick start](quickstart.md)
- * [Writing more pages](more-pages.md)
- * [Custom navbar](custom-navbar.md)
- * [Cover page](cover.md)
+ - [Quick start](quickstart.md)
+ - [Writing more pages](more-pages.md)
+ - [Custom navbar](custom-navbar.md)
+ - [Cover page](cover.md)
-* Customization
+- Customization
- * [Configuration](configuration.md)
- * [Themes](themes.md)
- * [List of Plugins](plugins.md)
- * [Write a Plugin](write-a-plugin.md)
- * [Markdown configuration](markdown.md)
- * [Language highlighting](language-highlight.md)
+ - [Configuration](configuration.md)
+ - [Themes](themes.md)
+ - [List of Plugins](plugins.md)
+ - [Write a Plugin](write-a-plugin.md)
+ - [Markdown configuration](markdown.md)
+ - [Language highlighting](language-highlight.md)
+ - [Emoji](emoji.md)
-* Guide
+- Guide
- * [Deploy](deploy.md)
- * [Helpers](helpers.md)
- * [Vue compatibility](vue.md)
- * [CDN](cdn.md)
- * [Offline Mode(PWA)](pwa.md)
- * [Server-Side Rendering(SSR)](ssr.md)
- * [Embed Files (new)](embed-files.md)
+ - [Deploy](deploy.md)
+ - [Helpers](helpers.md)
+ - [Vue compatibility](vue.md)
+ - [CDN](cdn.md)
+ - [Offline Mode (PWA)](pwa.md)
+ - [Server-Side Rendering (SSR)](ssr.md)
+ - [Embed Files](embed-files.md)
-* [Awesome docsify](awesome.md)
-* [Changelog](changelog.md)
+- [Awesome docsify](awesome.md)
+- [Changelog](changelog.md)
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..61c3a9b3e 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,220 +1,331 @@
# Configuration
-You can configure the `window.$docsify`.
+You can configure Docsify by defining `window.$docsify` as an object:
```html
```
-## el
+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:
-- Type: `String`
-- Default: `#app`
+```html
+
+```
-The DOM element to be mounted on initialization. It can be a CSS selector string or an actual HTMLElement.
+## alias
+
+- Type: `Object`
+
+Set the route alias. You can freely manage routing rules. Supports RegExp.
+Do note that order matters! If a route can be matched by multiple aliases, the one you declared first takes precedence.
```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` can 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**, or else 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`
+- 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`
-Loads sidebar from the Markdown file `_sidebar.md` if **true**, or else from the path specified.
+Activate the [cover feature](cover.md). If true, it will load from `_coverpage.md`.
```js
window.$docsify = {
- // load from _sidebar.md
- loadSidebar: true,
+ coverpage: true,
- // load from summary.md
- loadSidebar: 'summary.md'
+ // 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
+## el
-- Type: `Number`
-- Default: `0`
+- Type: `String`
+- Default: `'#app'`
-Add table of contents (TOC) in custom sidebar.
+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 = {
- subMaxLevel: 2
+ el: '#app',
};
```
-## auto2top
+## executeScript
- Type: `Boolean`
-- Default: `false`
+- Default: `null`
-Scrolls to the top of the screen when the route is changed.
+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 = {
- auto2top: true
+ executeScript: true,
};
```
-## homepage
+```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.
+
+## ext
- Type: `String`
-- Default: `README.md`
+- Default: `'.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.
+Request file extension.
```js
window.$docsify = {
- // Change to /home.md
- homepage: 'home.md',
+ ext: '.md',
+};
+```
- // Or use the readme in your repo
- homepage:
- 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.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'
};
```
-## basePath
+## externalLinkTarget
- Type: `String`
+- Default: `'_blank'`
-Base path of the website. You can set it to another directory or another domain name.
+Target to open external links inside the markdown. Default `'_blank'` (new window/tab)
```js
window.$docsify = {
- basePath: '/path/',
+ externalLinkTarget: '_self', // default: '_blank'
+};
+```
- // Load the files from another site
- basePath: 'https://docsify.js.org/',
+## fallbackLanguages
- // Even can load files from other repo
- basePath:
- 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/'
+- 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'],
};
```
-## 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,
+ formatUpdated: '{MM}/{DD} {HH}:{mm}',
- // Custom file name
- coverpage: 'cover.md',
+ formatUpdated: function (time) {
+ // ...
- // mutiple covers
- coverpage: ['/', '/zh-cn/'],
+ return time;
+ },
+};
+```
- // mutiple covers and custom file name
- coverpage: {
- '/': 'cover.md',
- '/zh-cn/': 'cover.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,
};
```
-## logo
+## homepage
- Type: `String`
+- Default: `'README.md'`
-Website logo as it appears in the sidebar, you can resize by CSS.
+`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 = {
- logo: '/_media/icon.svg'
+ // Change to /home.md
+ homepage: 'home.md',
+
+ // Or use the readme in your repo
+ homepage:
+ 'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};
```
-## name
+## loadNavbar
-- Type: `String`
+- Type: `Boolean|String`
+- Default: `false`
-Website name as it appears in the sidebar.
+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: `String`
-- Default: `window.location.pathname`
+- Type: `Boolean|String`
+- Default: `false`
-The name of the link.
+Loads sidebar from the Markdown file `_sidebar.md` if **true**, else loads it from the path specified.
```js
window.$docsify = {
- nameLink: '/',
+ // load from _sidebar.md
+ loadSidebar: true,
- // For each route
- nameLink: {
- '/zh-cn/': '/zh-cn/',
- '/': '/'
- }
+ // load from summary.md
+ loadSidebar: 'summary.md',
+};
+```
+
+## logo
+
+- Type: `String`
+
+Website logo as it appears in the sidebar. You can resize it using CSS.
+
+```js
+window.$docsify = {
+ logo: '/_media/icon.svg',
};
```
@@ -230,249 +341,564 @@ window.$docsify = {
markdown: {
smartypants: true,
renderer: {
- link: function() {
+ link: function () {
// ...
- }
- }
+ },
+ },
},
// function
- markdown: function(marked, renderer) {
+ markdown: function (marked, renderer) {
// ...
return marked;
- }
+ },
};
```
-## 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 old browser.
+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. Compare [#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
+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/',
+ '/': '#/',
+ },
+};
+```
-- type: `Boolean`
+## nativeEmoji
-Execute the script on the page. Only parse the first script tag([demo](themes)). If Vue is present, it is turned on by default.
+- Type: `Boolean`
+- Default: `false`
+
+Render emoji shorthand codes using GitHub-style emoji images or platform-native emoji characters.
```js
window.$docsify = {
- executeScript: true
+ nativeEmoji: true,
};
```
```markdown
-## This is test
+:smile:
+:partying_face:
+:joy:
+:+1:
+:-1:
+```
-
+GitHub-style images when `false`:
+
+
+
+Platform-native characters when `true`:
+
+
+
+To render shorthand codes as text, replace `:` characters with the `:` HTML entity.
+
+```markdown
+:100:
```
-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.
+
-- type: `Boolean`
+## noCompileLinks
-Disabled emoji parse.
+- 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 = {
- noEmoji: true
+ noCompileLinks: ['/foo', '/bar/.*'],
};
```
-## mergeNavbar
+## noEmoji
-- type: `Boolean`
+- Type: `Boolean`
+- Default: `false`
-Navbar will be merged with the sidebar on smaller screens.
+Disabled emoji parsing and render all emoji shorthand as text.
```js
window.$docsify = {
- mergeNavbar: true
+ noEmoji: true,
};
```
-## formatUpdated
+```markdown
+:100:
+```
-- type: `String|Function`
+
+
+To disable emoji parsing of individual shorthand codes, replace `:` characters with the `:` HTML entity.
+
+```markdown
+:100:
+
+:100:
+```
+
+
+
+## notFoundPage
+
+- Type: `Boolean` | `String` | `Object`
+- Default: `false`
+
+Display default "404 - Not found" message:
```js
window.$docsify = {
- formatUpdated: '{MM}/{DD} {HH}:{mm}',
+ notFoundPage: false,
+};
+```
- formatUpdated: function(time) {
- // ...
+Load the `_404.md` file:
- return time;
- }
+```js
+window.$docsify = {
+ notFoundPage: true,
};
```
-## externalLinkTarget
+Load the customized path of the 404 page:
-- type: `String`
-- default: `_blank`
+```js
+window.$docsify = {
+ notFoundPage: 'my404.md',
+};
+```
-Target to open external links. Default `'_blank'` (new window/tab)
+Load the right 404 page according to the localization:
```js
window.$docsify = {
- externalLinkTarget: '_self' // default: '_blank'
+ notFoundPage: {
+ '/': '_404.md',
+ '/de': 'de/_404.md',
+ },
};
```
-## routerMode
+> Note: The options for fallbackLanguages don't work with the `notFoundPage` options.
+
+## onlyCover
-- type: `String`
-- default: `hash`
+- Type: `Boolean`
+- Default: `false`
+
+Only coverpage is loaded when visiting the home page.
```js
window.$docsify = {
- routerMode: 'history' // default: 'hash'
+ onlyCover: false,
};
```
-## noCompileLinks
+## relativePath
-- type: `Array`
+- Type: `Boolean`
+- Default: `false`
-Sometimes we do not want docsify to handle our links. See [#203](https://github.com/docsifyjs/docsify/issues/203)
+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 = {
- 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/',
};
```
## requestHeaders
-- type: `Object`
+- Type: `Object`
Set the request resource headers.
```js
window.$docsify = {
requestHeaders: {
- 'x-token': 'xxx'
- }
+ 'x-token': 'xxx',
+ },
};
```
-## ext
+Such as setting the cache
-- type: `String`
+```js
+window.$docsify = {
+ requestHeaders: {
+ 'cache-control': 'max-age=600',
+ },
+};
+```
-Request file extension.
+## routerMode
+
+- Type: `String`
+- Default: `'hash'`
```js
window.$docsify = {
- ext: '.md'
+ routerMode: 'history', // default: 'hash'
};
```
-## fallbackLanguages
+## routes
-- type: `Array`
+- Type: `Object`
-List of languages that will fallback to the default language when a page is request and didn't exists for the given local.
+Define "virtual" routes that can provide content dynamically. A route is a map between the expected path, to either a string or a function. If the mapped value is a string, it is treated as markdown and parsed accordingly. If it is a function, it is expected to return markdown content.
-Example:
+A route function receives up to three parameters:
-- 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.
+1. `route` - the path of the route that was requested (e.g. `/bar/baz`)
+2. `matched` - the [`RegExpMatchArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match) that was matched by the route (e.g. for `/bar/(.+)`, you get `['/bar/baz', 'baz']`)
+3. `next` - this is a callback that you may call when your route function is async
+
+Do note that order matters! Routes are matched the same order you declare them in, which means that in cases where you have overlapping routes, you might want to list the more specific ones first.
```js
window.$docsify = {
- fallbackLanguages: ['fr', 'de']
+ routes: {
+ // Basic match w/ return string
+ '/foo': '# Custom Markdown',
+
+ // RegEx match w/ synchronous function
+ '/bar/(.*)': function (route, matched) {
+ return '# Custom Markdown';
+ },
+
+ // RegEx match w/ asynchronous function
+ '/baz/(.*)': function (route, matched, next) {
+ // Requires `fetch` polyfill for legacy browsers (https://github.github.io/fetch/)
+ fetch('/api/users?id=12345')
+ .then(function (response) {
+ next('# Custom Markdown');
+ })
+ .catch(function (err) {
+ // Handle error...
+ });
+ },
+ },
};
```
-## notFoundPage
+Other than strings, route functions can return a falsy value (`null` \ `undefined`) to indicate that they ignore the current request:
-- type: `Boolean` | `String` | `Object`
+```js
+window.$docsify = {
+ routes: {
+ // accepts everything other than dogs (synchronous)
+ '/pets/(.+)': function(route, matched) {
+ if (matched[0] === 'dogs') {
+ return null;
+ } else {
+ return 'I like all pets but dogs';
+ }
+ }
-Load the `_404.md` file:
+ // accepts everything other than cats (asynchronous)
+ '/pets/(.*)': function(route, matched, next) {
+ if (matched[0] === 'cats') {
+ next();
+ } else {
+ // Async task(s)...
+ next('I like all pets but cats');
+ }
+ }
+ }
+}
+```
+
+Finally, if you have a specific path that has a real markdown file (and therefore should not be matched by your route), you can opt it out by returning an explicit `false` value:
```js
window.$docsify = {
- notFoundPage: true
+ routes: {
+ // if you look up /pets/cats, docsify will skip all routes and look for "pets/cats.md"
+ '/pets/cats': function(route, matched) {
+ return false;
+ }
+
+ // but any other pet should generate dynamic content right here
+ '/pets/(.+)': function(route, matched) {
+ const pet = matched[0];
+ return `your pet is ${pet} (but not a cat)`;
+ }
+ }
+}
+```
+
+## subMaxLevel
+
+- Type: `Number`
+- Default: `0`
+
+Add table of contents (TOC) in custom sidebar.
+
+```js
+window.$docsify = {
+ subMaxLevel: 2,
};
```
-Load the customised path of the 404 page:
+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 = {
- notFoundPage: 'my404.md'
+ themeColor: '#3F51B5',
};
```
-Load the right 404 page according to the localisation:
+## topMargin
+
+- Type: `Number`
+- Default: `0`
+
+Adds a space on top when scrolling the 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 = {
- notFoundPage: {
- '/': '_404.md',
- '/de': 'de/_404.md'
- }
+ topMargin: 90, // default: 0
};
```
-> Note: The options with fallbackLanguages didn't work with the `notFoundPage` options.
+## 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 74025d1d3..bf8c3c54e 100644
--- a/docs/cover.md
+++ b/docs/cover.md
@@ -1,6 +1,6 @@
# Cover
-Activate the cover feature by setting `coverpage` to **true**, compare [coverpage configuration](configuration.md#coverpage).
+Activate the cover feature by setting `coverpage` to **true**. See [coverpage configuration](configuration.md#coverpage).
## Basic usage
@@ -14,7 +14,7 @@ Set `coverpage` to **true**, and create a `_coverpage.md`:
coverpage: true
}
-
+
```
```markdown
@@ -26,16 +26,14 @@ Set `coverpage` to **true**, and create a `_coverpage.md`:
> A magical documentation site generator.
-* Simple and lightweight (~19kB gzipped)
-* No statically built html files
-* Multiple themes
+- Simple and lightweight
+- No statically built html files
+- Multiple themes
[GitHub](https://github.com/docsifyjs/docsify/)
[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..0d05a243f 100644
--- a/docs/custom-navbar.md
+++ b/docs/custom-navbar.md
@@ -12,7 +12,7 @@ If you need custom navigation, you can create a HTML-based navigation bar.
@@ -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..9ac3ca50f 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -4,22 +4,22 @@ Similar to [GitBook](https://www.gitbook.com), you can deploy files to GitHub Pa
## GitHub Pages
-There're three places to populate your docs for your Github repository:
+There are three places to populate your docs for your GitHub repository:
- `docs/` folder
-- master branch
+- main branch
- gh-pages branch
-It is recommended that you save your files to the `./docs` subfolder of the `master` branch of your repository. Then select `master branch /docs folder` as your Github Pages source in your repositories' settings page.
+It is recommended that you save your files to the `./docs` subfolder of the `main` branch of your repository. Then select `main branch /docs folder` as your GitHub Pages source in your repository's settings page.
-
+
-!> 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 can also save files in the root directory and select `main branch`.
+You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch)
## GitLab Pages
-If you are deploying your master branch, include `.gitlab-ci.yml` with the following script:
+If you are deploying your master branch, create a `.gitlab-ci.yml` with the following script:
?> The `.public` workaround is so `cp` doesn't also copy `public/` to itself in an infinite loop.
@@ -43,9 +43,9 @@ pages:
!> You'll need to install the Firebase CLI using `npm i -g firebase-tools` after signing into the [Firebase Console](https://console.firebase.google.com) using a Google Account.
-Using Terminal determine and navigate to the directory for your Firebase Project - this could be `~/Projects/Docs` etc. From there, run `firebase init`, choosing `Hosting` from the menu (use **space** to select, **arrow keys** to change options and **enter** to confirm). Follow the setup instructions.
+Using a terminal, determine and navigate to the directory for your Firebase Project. This could be `~/Projects/Docs`, etc. From there, run `firebase init` and choose `Hosting` from the menu (use **space** to select, **arrow keys** to change options and **enter** to confirm). Follow the setup instructions.
-You should have your `firebase.json` file looking similar to this (I changed the deployment directory from `public` to `site`):
+Your `firebase.json` file should look similar to this (I changed the deployment directory from `public` to `site`):
```json
{
@@ -56,11 +56,11 @@ You should have your `firebase.json` file looking similar to this (I changed the
}
```
-Once finished, build the starting template by running `docsify init ./site` (replacing site with the deployment directory you determined when running `firebase init` - public by default). Add/edit the documentation, then run `firebase deploy` from the base project directory.
+Once finished, build the starting template by running `docsify init ./site` (replacing site with the deployment directory you determined when running `firebase init` - public by default). Add/edit the documentation, then run `firebase deploy` from the root project directory.
## VPS
-Try following nginx config.
+Use the following nginx config.
```nginx
server {
@@ -78,12 +78,106 @@ server {
1. Login to your [Netlify](https://www.netlify.com/) account.
2. In the [dashboard](https://app.netlify.com/) page, click **New site from Git**.
-3. Choose a repository where you store your docs, leave the **Build Command** area blank, fill in the Publish directory area with the directory of your `index.html`, for example it should be docs if you populated it at `docs/index.html`.
+3. Choose a repository where you store your docs, leave the **Build Command** area blank, and fill in the Publish directory area with the directory of your `index.html`. For example, it should be docs if you populated it at `docs/index.html`.
### 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. Just create a file named `_redirects` in the docs directory, add this snippet to the file, and you're all set:
```sh
/* /index.html 200
```
+
+## Vercel
+
+1. Install [Vercel CLI](https://vercel.com/download), `npm i -g vercel`
+2. Change directory to your docsify website, for example `cd docs`
+3. Deploy with a single command, `vercel`
+
+## 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 them inside the 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 .
+
+ ```
+
+ The 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..936494bcb 100644
--- a/docs/embed-files.md
+++ b/docs/embed-files.md
@@ -1,27 +1,30 @@
# 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')
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.
+Normally, this will be compiled into a link, but in docsify, if you add `:include` it will be embedded. You can use single or double quotation marks around as you like.
+
+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,20 +32,52 @@ 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.
+?> Note, for the `audio` and `video` types, docsify adds the `controls` attribute by default. When you want add more attributes, the `controls` attribute need to be added manually if need be.
+```md
+[filename](_media/example.mp4 ':include :type=video controls width=100%')
+```
+
```markdown
[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px')
```
@@ -64,3 +99,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/emoji.md b/docs/emoji.md
new file mode 100644
index 000000000..3b562fadc
--- /dev/null
+++ b/docs/emoji.md
@@ -0,0 +1,3765 @@
+# Emoji
+
+Below is a complete list of emoji shorthand codes. Docsify can be configured to render emoji using GitHub-style emoji images or native emoji characters using the [`nativeEmoji`](configuration#nativeemoji) configuration option.
+
+
diff --git a/docs/helpers.md b/docs/helpers.md
index 801683126..a6fc95ea5 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, it's better to put them within code backticks to avoid any conflict from configurations or emojis.
+
+## Important content
Important content like:
@@ -28,13 +30,13 @@ are rendered as:
## Ignore to compile link
-Some time we will put some other relative path to the link, you have to need to tell docsify you don't need to compile this link. For example
+Sometimes we will use some other relative path for the link, and we have to tell docsify that we don't need to compile this link. For example:
```md
[link](/demo/)
```
-It will be compiled to `link` and will be loaded `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
+It will be compiled to `link` and will load `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
Now you can do that
@@ -42,7 +44,7 @@ Now you can do that
[link](/demo/ ':ignore')
```
-You will get `link`html. Do not worry, you can still set title for link.
+You will get `link`html. Do not worry, you can still set the title for the link.
```md
[link](/demo/ ':ignore title')
@@ -63,7 +65,7 @@ You will get `link`html. Do not worry, you can still set ti
[link](/demo ':disabled')
```
-## Github Task Lists
+## GitHub Task Lists
```md
- [ ] foo
@@ -81,16 +83,80 @@ You will get `link`html. Do not worry, you can still set ti
- [ ] bim
- [ ] lim
-## Image resizing
+## Image
+
+### Resizing
```md
+
+
```
+
+### Customise class
+
+```md
+
+```
+
+### Customise ID
+
+```md
+
+```
+
+## Customise ID for headings
+
+```md
+### Hello, world! :id=hello-world
+```
+
+## Markdown in html tag
+
+You need to insert a space between the html and markdown content.
+This is useful for rendering markdown content in the details element.
+
+```markdown
+
+Self-assessment (Click to expand)
+
+- Abc
+- Abc
+
+
+```
+
+
+Self-assessment (Click to expand)
+
+- Abc
+- Abc
+
+
+
+Markdown content can also be wrapped in html tags.
+
+```markdown
+
-
\ No newline at end of file
+
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 000000000..b07a97ce3
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,9 @@
+FROM mcr.microsoft.com/playwright:focal
+WORKDIR /app
+COPY . .
+RUN rm package-lock.json
+RUN npm install
+RUN npx playwright install
+RUN npm run build
+ENTRYPOINT ["npm", "run"]
+CMD ["test"]
\ No newline at end of file
diff --git a/LICENSE b/LICENSE
index 37a4ac5b8..a2155380a 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
MIT License
-Copyright (c) 2016 - present cinwell.li
+Copyright (c) 2016 - present Docsify Contributors (https://github.com/docsifyjs/docsify/graphs/contributors)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index d976d3e8f..1f488dc11 100644
--- a/README.md
+++ b/README.md
@@ -10,49 +10,54 @@
- 
- 
+
+ 
- 
+ 
+ 
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 000000000..1b9f6f908
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,23 @@
+# Security Policy
+
+If you believe you have found a security vulnerability in docsify, please report it to us asap.
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through our public GitHub issues.**
+
+Send email via :email: maintainers@docsifyjs.org to us.
+
+Please include as much of the following information as possible to help us better understand the possible issue:
+
+- Type of issue (e.g. cross-site scripting)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code
+- Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+Thank you in advance.
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 c7e8c1bf9..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