[release] 4.2.0

* feat: ignore to compiled link, fixed #203

* feat: add noCompileLinks, fixed #203

* fix: remove test code

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+4.2.0 / 2017-07-10
+
+  * feat: ignore to compiled link, fixed #203 (#204)
+  * feat: alias option supports regexp, resolve #183
+
+4.1.14 / 2017-06-24
+
+  * feat: add context attribute, fixed #191
+  * fix: get file path
+  * Merge pull request #195 from crawt/master
+  * Filter picture
+  * Update doc for external link target (#194)
+
 4.1.13 / 2017-06-11
 
   * fix ga

dev.html

@@ -19,9 +19,7 @@
 <script>
   window.$docsify = {
     alias: {
-      '/de-de/changelog': '/changelog',
-      '/zh-cn/changelog': '/changelog',
-      '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
+      '.*?/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
     },
     auto2top: true,
     basePath: '/docs/',
@@ -33,11 +31,10 @@
     subMaxLevel: 0,
     mergeNavbar: true,
     formatUpdated: '{MM}/{DD} {HH}:{mm}',
-    routerMode: 'history',
     plugins: [
       function(hook, vm) {
         hook.beforeEach(function (html) {
-          var url = 'https://github.com/QingWei-Li/docsify/blob/master' + vm.router.getFile()
+          var url = 'https://github.com/QingWei-Li/docsify/blob/master/' + vm.route.file
           var editHtml = '[:memo: Edit Document](' + url + ')\n'
 
           return editHtml

docs/_coverpage.md

@@ -1,6 +1,6 @@
 ![logo](_media/icon.svg)
 
-# docsify <small>4.1.13</small>
+# docsify <small>4.2.0</small>
 
 > A magical documentation site generator.
 

docs/configuration.md

@@ -250,11 +250,12 @@ window.$docsify = {
 
 - Type: `Object`
 
-Set the route alias. You can freely manage routing rules.
+Set the route alias. You can freely manage routing rules. Supports RegExp.
 
 ```js
 window.$docsify = {
   alias: {
+    '/foo/(+*)': '/bar/$1', // supports regexp
     '/zh-cn/changelog': '/changelog',
     '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
   }
@@ -298,6 +299,8 @@ Note that if you are running an external script, e.g. an embedded jsfiddle demo,
 
 ## no-emoji
 
+- type: `Boolean`
+
 Disabled emoji parse.
 
 ```js
@@ -308,6 +311,8 @@ window.$docsify = {
 
 ## merge-navbar
 
+- type: `Boolean`
+
 Navbar will be merged with the sidebar on smaller screens.
 
 ```js
@@ -317,6 +322,9 @@ window.$docsify = {
 ```
 
 ## format-updated
+
+- type: `String|Function`
+
 We can display the file update date through **{docsify-updated<span>}</span>** variable. And format it by `formatUpdated`.
 See https://github.com/lukeed/tinydate#patterns
 ```js
@@ -333,7 +341,10 @@ window.$docsify = {
 
 ## external-link-target
 
-Currently it defaults to _blank, would be nice if configurable:
+- type: `String`
+- default: `_self`
+
+Target to open external links. Default `'_blank'` (new window/tab)
 
 ```js
 window.$docsify = {
@@ -342,8 +353,30 @@ window.$docsify = {
 ```
 
 ## router-mode
+
+- type: `String`
+- default: `history`
+
 ```js
 window.$docsify = {
   routerMode: 'history' // default: 'hash'
 }
 ```
+
+## noCompileLinks
+
+- type: `Array`
+
+
+Sometimes we do not want docsify to handle our links. See [#203](https://github.com/QingWei-Li/docsify/issues/203)
+
+
+```js
+window.$docsify = {
+  noCompileLinks: [
+    '/foo',
+    '/bar/.*'
+  ]
+}
+```
+

docs/de-de/configuration.md

@@ -250,11 +250,12 @@ window.$docsify = {
 
 - Typ: `Object`
 
-Verwende alternative Routen. Du kannst sie ungehindert anpassen.
+Verwende alternative Routen. Du kannst sie ungehindert anpassen. Supports RegExp.
 
 ```js
 window.$docsify = {
   alias: {
+    '/foo/(+*)': '/bar/$1', // supports regexp
     '/zh-cn/changelog': '/changelog',
     '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
   }
@@ -317,7 +318,7 @@ window.$docsify = {
 ```
 
 ## format-updated
-We can display the file update date through **{docsify-updated<span>}</span>** variable. And format it by `formatUpdated`. 
+We can display the file update date through **{docsify-updated<span>}</span>** variable. And format it by `formatUpdated`.
 See https://github.com/lukeed/tinydate#patterns
 ```js
 window.$docsify = {
@@ -340,3 +341,21 @@ window.$docsify = {
   externalLinkTarget: '_self' // default: '_blank'
 }
 ```
+
+
+## noCompileLinks
+
+- type: `Array`
+
+
+Sometimes we do not want docsify to handle our links. See [#203](https://github.com/QingWei-Li/docsify/issues/203)
+
+
+```js
+window.$docsify = {
+  noCompileLinks: [
+    '/foo',
+    '/bar/.*'
+  ]
+}
+```

docs/de-de/helpers.md

@@ -25,3 +25,27 @@ Generelle Tipps wie:
 wird wie folgt gerendert:
 
 ?> *TODO* unit test
+
+## 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
+
+```md
+[link](/demo/)
+```
+
+
+It will be compiled to `<a href="/#/demo/">link</a>` and will be loaded `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
+
+Now you can do that
+
+```md
+[link](/demo/ ":ignore")
+```
+You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set title for link.
+
+```md
+[link](/demo/ ":ignore title")
+
+<a href="/demo/" title="title">link</a>
+```

docs/helpers.md

@@ -25,3 +25,28 @@ General tips like:
 are rendered as:
 
 ?> *TODO* unit test
+
+## 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
+
+```md
+[link](/demo/)
+```
+
+
+It will be compiled to `<a href="/#/demo/">link</a>` and will be loaded `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
+
+Now you can do that
+
+```md
+[link](/demo/ ":ignore")
+```
+You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set title for link.
+
+```md
+[link](/demo/ ":ignore title")
+
+<a href="/demo/" title="title">link</a>
+```
+

docs/index.html

@@ -23,9 +23,7 @@
 <script>
   window.$docsify = {
     alias: {
-      '/de-de/changelog': '/changelog',
-      '/zh-cn/changelog': '/changelog',
-      '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
+      '.*?/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
     },
     auto2top: true,
     coverpage: true,
@@ -53,7 +51,7 @@
     plugins: [
       function(hook, vm) {
         hook.beforeEach(function (html) {
-          var url = 'https://github.com/QingWei-Li/docsify/blob/master/docs' + vm.route.file
+          var url = 'https://github.com/QingWei-Li/docsify/blob/master/docs/' + vm.route.file
           var editHtml = '[:memo: Edit Document](' + url + ')\n'
 
           return editHtml

docs/zh-cn/configuration.md

@@ -258,12 +258,13 @@ window.$docsify = {
 
 - 类型：`Object`
 
-定义路由别名，可以更自由的定义路由规则。
+定义路由别名，可以更自由的定义路由规则。 支持正则。
 
 
 ```js
 window.$docsify = {
   alias: {
+    '/foo/(+*)': '/bar/$1', // supports regexp
     '/zh-cn/changelog': '/changelog',
     '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
   }
@@ -327,7 +328,8 @@ window.$docsify = {
 ```
 
 ## format-updated
-我们可以显示文档更新日期通过 **{docsify-updated<span>}</span>** 变量. 并且格式化日期通过 `formatUpdated`. 
+
+我们可以显示文档更新日期通过 **{docsify-updated<span>}</span>** 变量. 并且格式化日期通过 `formatUpdated`.
 参考 https://github.com/lukeed/tinydate#patterns
 ```js
 window.$docsify = {
@@ -350,3 +352,21 @@ window.$docsify = {
   externalLinkTarget: '_self' // default: '_blank'
 }
 ```
+
+
+## noCompileLinks
+
+- type: `Array`
+
+
+Sometimes we do not want docsify to handle our links. See [#203](https://github.com/QingWei-Li/docsify/issues/203)
+
+
+```js
+window.$docsify = {
+  noCompileLinks: [
+    '/foo',
+    '/bar/.*'
+  ]
+}
+```

docs/zh-cn/helpers.md

@@ -24,3 +24,28 @@ docsify 扩展了一些 Markdown 语法，可以让文档更易读。
 
 ?> *TODO* 完善示例
 
+
+## 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
+
+```md
+[link](/demo/)
+```
+
+
+It will be compiled to `<a href="/#/demo/">link</a>` and will be loaded `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
+
+Now you can do that
+
+```md
+[link](/demo/ ":ignore")
+```
+You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set title for link.
+
+```md
+[link](/demo/ ":ignore title")
+
+<a href="/demo/" title="title">link</a>
+```
+

lib/docsify.js

@@ -80,7 +80,8 @@ var config = merge({
   mergeNavbar: false,
   formatUpdated: '',
   externalLinkTarget: '_blank',
-  routerModel: 'hash'
+  routerModel: 'hash',
+  noCompileLinks: []
 }, window.$docsify);
 
 var script = document.currentScript ||
@@ -2717,8 +2718,9 @@ function parseQuery (query) {
   query.split('&').forEach(function (param) {
     var parts = param.replace(/\+/g, ' ').split('=');
 
-    res[parts[0]] = decode(parts[1]);
+    res[parts[0]] = parts[1] && decode(parts[1]);
   });
+
   return res
 }
 
@@ -2726,7 +2728,9 @@ function stringifyQuery (obj) {
   var qs = [];
 
   for (var key in obj) {
-    qs.push(((encode(key)) + "=" + (encode(obj[key]))).toLowerCase());
+    qs.push(obj[key]
+      ? ((encode(key)) + "=" + (encode(obj[key]))).toLowerCase()
+      : encode(key));
   }
 
   return qs.length ? ("?" + (qs.join('&'))) : ''
@@ -2757,6 +2761,8 @@ var cleanPath = cached(function (path) {
     .replace(/([^:])\/{2,}/g, '$1/')
 });
 
+var cachedLinks = {};
+
 var Compiler = function Compiler (config, router) {
   this.config = config;
   this.router = router;
@@ -2791,6 +2797,19 @@ var Compiler = function Compiler (config, router) {
   });
 };
 
+Compiler.prototype.matchNotCompileLink = function matchNotCompileLink (link) {
+  var links = this.config.noCompileLinks;
+
+  for (var i = 0; i < links.length; i++) {
+    var n = links[i];
+    var re = cachedLinks[n] || (cachedLinks[n] = new RegExp(("^" + n + "$")));
+
+    if (re.test(link)) {
+      return link
+    }
+  }
+};
+
 Compiler.prototype._initRenderer = function _initRenderer () {
   var renderer = new marked.Renderer();
   var ref = this;
@@ -2834,11 +2853,16 @@ Compiler.prototype._initRenderer = function _initRenderer () {
   };
   renderer.link = function (href, title, text) {
     var blank = '';
-    if (!/:|(\/{2})/.test(href)) {
+
+    if (!/:|(\/{2})/.test(href) &&
+      !_self.matchNotCompileLink(href) &&
+      !/(\s?:ignore)(\s\S+)?$/.test(title)) {
       href = router.toURL(href, null, router.getCurrentPath());
     } else {
       blank = " target=\"" + linkTarget + "\"";
+      title = title && title.replace(/:ignore/g, '').trim();
     }
+
     if (title) {
       title = " title=\"" + title + "\"";
     }
@@ -3200,6 +3224,10 @@ function renderMixin (proto) {
     var this$1 = this;
     if ( opt === void 0 ) opt = {};
 
+    if (!text) {
+      return renderMain.call(this, text)
+    }
+
     callHook(this, 'beforeEach', text, function (result) {
       var html = this$1.isHTML ? result : this$1.compiler.compile(result);
       if (opt.updatedAt) {
@@ -3298,8 +3326,15 @@ function initRender (vm) {
   toggleClass(body, 'ready');
 }
 
-function getAlias (path, alias) {
-  return alias[path] ? getAlias(alias[path], alias) : path
+var cached$1 = {};
+
+function getAlias (path, alias, last) {
+  var match = Object.keys(alias).filter(function (key) {
+    var re = cached$1[key] || (cached$1[key] = new RegExp(("^" + key + "$")));
+    return re.test(path) && path !== last
+  })[0];
+
+  return match ? getAlias(path.replace(cached$1[match], alias[match]), alias, path) : path
 }
 
 function getFileName (path) {
@@ -3318,7 +3353,7 @@ History.prototype.getBasePath = function getBasePath () {
   return this.config.basePath
 };
 
-History.prototype.getFile = function getFile (path) {
+History.prototype.getFile = function getFile (path, isRelative) {
   path = path || this.getCurrentPath();
 
   var ref = this;
@@ -3330,6 +3365,10 @@ History.prototype.getFile = function getFile (path) {
   path = path === '/README.md' ? (config.homepage || path) : path;
   path = isAbsolutePath(path) ? path : getPath(base, path);
 
+  if (isRelative) {
+    path = path.replace(new RegExp(("^" + base)), '');
+  }
+
   return path
 };
 
@@ -3423,7 +3462,7 @@ var HashHistory = (function (History$$1) {
 
     return {
       path: path,
-      file: this.getFile(path),
+      file: this.getFile(path, true),
       query: parseQuery(query)
     }
   };
@@ -3536,6 +3575,12 @@ function routerMixin (proto) {
 
 var lastRoute = {};
 
+function updateRender (vm) {
+  vm.router.normalize();
+  vm.route = vm.router.parse();
+  body.setAttribute('data-page', vm.route.file);
+}
+
 function initRouter (vm) {
   var config = vm.config;
   var mode = config.routerMode || 'hash';
@@ -3548,13 +3593,11 @@ function initRouter (vm) {
   }
 
   vm.router = router;
-
-  router.normalize();
-  lastRoute = vm.route = router.parse();
+  updateRender(vm);
+  lastRoute = vm.route;
 
   router.onchange(function (_) {
-    router.normalize();
-    vm.route = router.parse();
+    updateRender(vm);
     vm._updateRender();
 
     if (lastRoute.path === vm.route.path) {
@@ -3615,17 +3658,24 @@ function fetchMixin (proto) {
     // Current page is html
     this.isHTML = /\.html$/g.test(path);
 
-    // Load main content
-    last.then(function (text, opt) {
-      this$1._renderMain(text, opt);
+    var loadSideAndNav = function () {
       if (!loadSidebar) { return cb() }
 
       var fn = function (result) { this$1._renderSidebar(result); cb(); };
 
       // Load sidebar
       loadNested(path, loadSidebar, fn, this$1, true);
+    };
+
+    // Load main content
+    last.then(function (text, opt) {
+      this$1._renderMain(text, opt);
+      loadSideAndNav();
     },
-    function (_) { return this$1._renderMain(null); });
+    function (_) {
+      this$1._renderMain(null);
+      loadSideAndNav();
+    });
 
     // Load nav
     loadNavbar &&
@@ -3750,7 +3800,7 @@ initGlobalAPI();
 /**
  * Version
  */
-Docsify.version = '4.1.13';
+Docsify.version = '4.2.0';
 
 /**
  * Run Docsify

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "docsify",
-  "version": "4.1.13",
+  "version": "4.2.0",
   "lockfileVersion": 1,
   "dependencies": {
     "abbrev": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docsify",
-  "version": "4.1.13",
+  "version": "4.2.0",
   "description": "A magical documentation generator.",
   "author": {
     "name": "qingwei-li",

packages/docsify-server-renderer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docsify-server-renderer",
-  "version": "4.1.13",
+  "version": "4.2.0",
   "description": "docsify server renderer",
   "author": {
     "name": "qingwei-li",

src/core/config.js

@@ -21,7 +21,8 @@ const config = merge({
   mergeNavbar: false,
   formatUpdated: '',
   externalLinkTarget: '_blank',
-  routerModel: 'hash'
+  routerModel: 'hash',
+  noCompileLinks: []
 }, window.$docsify)
 
 const script = document.currentScript ||

src/core/fetch/index.js

@@ -28,17 +28,24 @@ export function fetchMixin (proto) {
     // Current page is html
     this.isHTML = /\.html$/g.test(path)
 
-    // Load main content
-    last.then((text, opt) => {
-      this._renderMain(text, opt)
+    const loadSideAndNav = () => {
       if (!loadSidebar) return cb()
 
       const fn = result => { this._renderSidebar(result); cb() }
 
       // Load sidebar
       loadNested(path, loadSidebar, fn, this, true)
+    }
+
+    // Load main content
+    last.then((text, opt) => {
+      this._renderMain(text, opt)
+      loadSideAndNav()
     },
-    _ => this._renderMain(null))
+    _ => {
+      this._renderMain(null)
+      loadSideAndNav()
+    })
 
     // Load nav
     loadNavbar &&

src/core/render/compiler.js

@@ -7,6 +7,8 @@ import { emojify } from './emojify'
 import { isAbsolutePath, getPath } from '../router/util'
 import { isFn, merge, cached } from '../util/core'
 
+const cachedLinks = {}
+
 export class Compiler {
   constructor (config, router) {
     this.config = config
@@ -42,6 +44,19 @@ export class Compiler {
     })
   }
 
+  matchNotCompileLink (link) {
+    const links = this.config.noCompileLinks
+
+    for (var i = 0; i < links.length; i++) {
+      const n = links[i]
+      const re = cachedLinks[n] || (cachedLinks[n] = new RegExp(`^${n}$`))
+
+      if (re.test(link)) {
+        return link
+      }
+    }
+  }
+
   _initRenderer () {
     const renderer = new marked.Renderer()
     const { linkTarget, router, contentBase } = this
@@ -80,11 +95,16 @@ export class Compiler {
     }
     renderer.link = function (href, title, text) {
       let blank = ''
-      if (!/:|(\/{2})/.test(href)) {
+
+      if (!/:|(\/{2})/.test(href) &&
+        !_self.matchNotCompileLink(href) &&
+        !/(\s?:ignore)(\s\S+)?$/.test(title)) {
         href = router.toURL(href, null, router.getCurrentPath())
       } else {
         blank = ` target="${linkTarget}"`
+        title = title && title.replace(/:ignore/g, '').trim()
       }
+
       if (title) {
         title = ` title="${title}"`
       }

src/core/render/index.js

@@ -117,6 +117,10 @@ export function renderMixin (proto) {
   }
 
   proto._renderMain = function (text, opt = {}) {
+    if (!text) {
+      return renderMain.call(this, text)
+    }
+
     callHook(this, 'beforeEach', text, result => {
       let html = this.isHTML ? result : this.compiler.compile(result)
       if (opt.updatedAt) {

src/core/router/history/base.js

@@ -1,8 +1,15 @@
 import { getPath, isAbsolutePath } from '../util'
 import { noop } from '../../util/core'
 
-function getAlias (path, alias) {
-  return alias[path] ? getAlias(alias[path], alias) : path
+const cached = {}
+
+function getAlias (path, alias, last) {
+  const match = Object.keys(alias).filter((key) => {
+    const re = cached[key] || (cached[key] = new RegExp(`^${key}$`))
+    return re.test(path) && path !== last
+  })[0]
+
+  return match ? getAlias(path.replace(cached[match], alias[match]), alias, path) : path
 }
 
 function getFileName (path) {
@@ -22,7 +29,7 @@ export class History {
     return this.config.basePath
   }
 
-  getFile (path) {
+  getFile (path, isRelative) {
     path = path || this.getCurrentPath()
 
     const { config } = this
@@ -33,6 +40,10 @@ export class History {
     path = path === '/README.md' ? (config.homepage || path) : path
     path = isAbsolutePath(path) ? path : getPath(base, path)
 
+    if (isRelative) {
+      path = path.replace(new RegExp(`^${base}`), '')
+    }
+
     return path
   }
 

src/core/router/history/hash.js

@@ -71,7 +71,7 @@ export class HashHistory extends History {
 
     return {
       path,
-      file: this.getFile(path),
+      file: this.getFile(path, true),
       query: parseQuery(query)
     }
   }

src/core/router/index.js

@@ -1,6 +1,7 @@
 import { HashHistory } from './history/hash'
 import { HTML5History } from './history/html5'
 import { supportsPushState } from '../util/env'
+import * as dom from '../util/dom'
 
 export function routerMixin (proto) {
   proto.route = {}
@@ -8,6 +9,12 @@ export function routerMixin (proto) {
 
 let lastRoute = {}
 
+function updateRender (vm) {
+  vm.router.normalize()
+  vm.route = vm.router.parse()
+  dom.body.setAttribute('data-page', vm.route.file)
+}
+
 export function initRouter (vm) {
   const config = vm.config
   const mode = config.routerMode || 'hash'
@@ -20,13 +27,11 @@ export function initRouter (vm) {
   }
 
   vm.router = router
-
-  router.normalize()
-  lastRoute = vm.route = router.parse()
+  updateRender(vm)
+  lastRoute = vm.route
 
   router.onchange(_ => {
-    router.normalize()
-    vm.route = router.parse()
+    updateRender(vm)
     vm._updateRender()
 
     if (lastRoute.path === vm.route.path) {

src/core/router/util.js

@@ -16,8 +16,9 @@ export function parseQuery (query) {
   query.split('&').forEach(function (param) {
     const parts = param.replace(/\+/g, ' ').split('=')
 
-    res[parts[0]] = decode(parts[1])
+    res[parts[0]] = parts[1] && decode(parts[1])
   })
+
   return res
 }
 
@@ -25,7 +26,9 @@ export function stringifyQuery (obj) {
   const qs = []
 
   for (const key in obj) {
-    qs.push(`${encode(key)}=${encode(obj[key])}`.toLowerCase())
+    qs.push(obj[key]
+      ? `${encode(key)}=${encode(obj[key])}`.toLowerCase()
+      : encode(key))
   }
 
   return qs.length ? `?${qs.join('&')}` : ''