From 35d3bd1647d68c0f7c5f90e5f0d69092593be4e7 Mon Sep 17 00:00:00 2001 From: "cinwell.li" Date: Tue, 29 Nov 2016 01:07:47 +0800 Subject: [PATCH] customize sidebar and navbar via markdown file, #6 (#8) * Refactor: use iife * Feat: customize sidebar and navbar via markdown file, #6 * Add changelog --- CHANGELOG.md | 8 +- build/build.js | 5 +- docs/README.md | 57 +++++ docs/zh-cn.md | 60 +++++ lib/docsify.js | 404 +++++++++++++++++++------------- lib/docsify.min.js | 2 +- lib/themes/vue.css | 2 +- src/ajax.js | 17 -- src/{bind-event.js => event.js} | 27 ++- src/gen-toc.js | 44 ---- src/index.js | 113 ++++----- src/render.js | 78 ++++-- src/tpl.js | 51 ++++ src/util.js | 68 ++++++ themes/buble.css | 8 +- themes/vue.css | 14 +- 16 files changed, 625 insertions(+), 333 deletions(-) delete mode 100644 src/ajax.js rename src/{bind-event.js => event.js} (64%) delete mode 100644 src/gen-toc.js create mode 100644 src/tpl.js create mode 100644 src/util.js diff --git a/CHANGELOG.md b/CHANGELOG.md index c6a5869a..a21a9ac7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,13 @@ +## 0.5.0 +### Features +- Custom sidebars and navbars by markdown file + ## 0.4.2 -## Bug fixes +### Bug fixes - Correct catch ajax error ## 0.4.1 -## Bug fixes +### Bug fixes - catch ajax error ## 0.4.0 diff --git a/build/build.js b/build/build.js index b6862edf..f8a69229 100644 --- a/build/build.js +++ b/build/build.js @@ -15,11 +15,14 @@ var build = function (opts) { console.log(dest) bundle.write({ - format: 'umd', + format: 'iife', moduleName: opts.moduleName || 'Docsify', dest: dest }) }) + .catch(function (err) { + console.error(err) + }) } build({ diff --git a/docs/README.md b/docs/README.md index 5b439d33..1be47040 100644 --- a/docs/README.md +++ b/docs/README.md @@ -144,3 +144,60 @@ Custom sidebar. if it'set, the TOC will be disabeld. Bind global variables on th ``` + +#### load-sidebar + +Load sidebar markdown file. If it is configured, load the current directory `_sidebar.md` by default. If the file isn't exist, sidebar will appear TOC. + +```html + +``` + +You can specify a file: + +```html + +``` + +The contents of the file can be: + +```markdown +- [Home](/) +- [Installation](/installation) +- Essentials + - [Getting Started](/getting-started) + - [Dynamic Route Matching](/dynamic-matching) + - [Nested Routes](/nested-routes) + - [Programmatic Navigation](/navigation) + - [Named Routes](/named-routes) + - [Named Views](/named-views) + - [Redirect and Alias](/redirect-and-alias) + - [HTML5 History Mode](/history-mode) +``` + +#### load-navbar + +Load navbar markdown file. If it is configured, load the current directory `_navbar.md` by default. + +```html + +``` + +You can specify a file: + +```html + +``` + +The contents of the file can be: + +```markdown +- [en](/) +- [chinese](/zh-cn) +``` + +## FAQ + +### Why use `404.html` instead of `index.html` + +[issues/7](https://github.com/QingWei-Li/docsify/issues/7) diff --git a/docs/zh-cn.md b/docs/zh-cn.md index 7c1baa7e..a664c4e2 100644 --- a/docs/zh-cn.md +++ b/docs/zh-cn.md @@ -142,3 +142,63 @@ docsify serve docs ``` +#### load-sidebar + +读取侧边栏配置文件，如果配置，默认加载当前目录下的 `_sidebar.md`。如果文件不存在，会显示 TOC 作为侧边栏内容。如果你有二级目录，也应该放置一份配置文件。 + +```html + +``` + +你可以指定侧边栏文件名 + +```html + +``` + +`_sidebar.md` 的内容可以是这样的 + +```markdown +- [Home](/) +- [Installation](/installation) +- Essentials + - [Getting Started](/getting-started) + - [Dynamic Route Matching](/dynamic-matching) + - [Nested Routes](/nested-routes) + - [Programmatic Navigation](/navigation) + - [Named Routes](/named-routes) + - [Named Views](/named-views) + - [Redirect and Alias](/redirect-and-alias) + - [HTML5 History Mode](/history-mode) +``` + +#### load-navbar + +读取导航配置文件，如果配置，默认加载当前目录下的 `_navbar.md`。如果文件不存在，会显示 html 里定义的导航栏。 + +```html + +``` + +你可以指定导航栏文件名 + +```html + +``` + +`_navbar.md` 的内容可以是这样 + +```markdown +- [en](/) +- [中文](/zh-cn) +``` + +## FAQ + +### 为什么是 `404.html` 而不用 `index.html` + +docsify 想要实现的是用最简单的方式 **动态渲染内容**。 + +例如我有两个文档分别为 `README.md` 和 `guide.md`，如果我用 `index.html` 作为文件名，`README.md` 可以被正确的渲染因为我们已经规定它为首页文件，但是如果我们访问 `my-domain.com/guide` 想要得到的结果是 `guide.md` 的内容，它将无法工作，因为目录下并不存在一个 `guide.html` 的文件。 + +但是 GitHub Pages 服务器找不到资源， 就会回退并渲染 `404.html` 文件。😄 diff --git a/lib/docsify.js b/lib/docsify.js index 38301bf8..4057936e 100644 --- a/lib/docsify.js +++ b/lib/docsify.js @@ -1,28 +1,80 @@ -(function (global, factory) { - typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() : - typeof define === 'function' && define.amd ? define(factory) : - (global.Docsify = factory()); -}(this, (function () { 'use strict'; +var Docsify = (function () { +'use strict'; -var ajax = function (url, options) { - if ( options === void 0 ) options = {}; +/** + * Simple ajax + * @param {String} url + * @param {String} [method=get] + * @return {Promise} + */ +function load (url, method) { + if ( method === void 0 ) method = 'get'; var xhr = new XMLHttpRequest(); - xhr.open(options.method || 'get', url); + xhr.open(method, url); xhr.send(); return { - then: function (cb) { - xhr.addEventListener('load', cb); - return this - }, - catch: function (cb) { - xhr.addEventListener('error', cb); - return this + then: function (success, error) { + if ( error === void 0 ) error = function () {}; + + xhr.addEventListener('error', error); + xhr.addEventListener('load', function (ref) { + var target = ref.target; + + target.status >= 400 ? error(target) : success(target.response); + }); } } -}; +} + +/** + * gen toc tree + * @link https://github.com/killercup/grock/blob/5280ae63e16c5739e9233d9009bc235ed7d79a50/styles/solarized/assets/js/behavior.coffee#L54-L81 + * @param {Array} toc + * @param {Number} maxLevel + * @return {Array} + */ +function genTree (toc, maxLevel) { + var headlines = []; + var last = {}; + + toc.forEach(function (headline) { + var level = headline.level || 1; + var len = level - 1; + + if (level > maxLevel) { return } + if (last[len]) { + last[len].children = last[len].children || []; + last[len].children.push(headline); + } else { + headlines.push(headline); + } + last[level] = headline; + }); + + return headlines +} + +/** + * camel to kebab + * @link https://github.com/bokuweb/kebab2camel/blob/master/index.js + * @param {String} str + * @return {String} + */ +function camel2kebab (str) { + return str.replace(/([A-Z])/g, function (m) { return '-' + m.toLowerCase(); }) +} + +/** + * is nil + * @param {Object} object + * @return {Boolean} + */ +function isNil (o) { + return o === null || o === undefined +} var commonjsGlobal = typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {}; @@ -2119,96 +2171,52 @@ Prism.languages.js = Prism.languages.javascript; }); /** - * @link from https://github.com/killercup/grock/blob/5280ae63e16c5739e9233d9009bc235ed7d79a50/styles/solarized/assets/js/behavior.coffee#L54-L81 + * Render github corner + * @param {Object} data + * @return {String} */ -var tocToTree = function (toc, maxLevel) { - var headlines = []; - var last = {}; +function corner (data) { + if (!data) { return '' } + if (!/\/\//.test(data)) { data = 'https://github.com/' + data; } - toc.forEach(function (headline) { - var level = headline.level || 1; - var len = level - 1; + return ("\n \n \n \n \n \n \n ") +} - if (level > maxLevel) { return } - if (last[len]) { - last[len].children = last[len].children || []; - last[len].children.push(headline); - } else { - headlines.push(headline); - } - last[level] = headline; - }); +/** + * Render main content + * @return {[type]} [description] + */ +function main () { + return "
\n \n
\n
\n
\n
" +} - return headlines -}; - -var buildHeadlinesTree = function (tree, tpl) { +/** + * Render tree + * @param {Array} tree + * @param {String} tpl + * @return {String} + */ +function tree (toc, tpl) { if ( tpl === void 0 ) tpl = ''; - if (!tree || !tree.length) { return '' } + if (!toc || !toc.length) { return '' } - tree.forEach(function (node) { + toc.forEach(function (node) { tpl += "
  • " + (node.title) + "
    • "; if (node.children) { - tpl += "
  • "; + tpl += "
  • "; } }); return tpl -}; - -var genToc = function (toc, opts) { - var tree = Array.isArray(opts.sidebar) - ? opts.sidebar - : tocToTree(toc, opts['max-level']); - - return buildHeadlinesTree(tree, '