diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d7e4a7e0..2c821acf4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,8 @@ +## 1.2.0 +### Features +- custom basePath +- custom homepage + ## 1.1.7 ### Bug fixes - Optimize progress bar diff --git a/README.md b/README.md index 6dde20298..ce4d4e289 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,10 @@ index.html ``` +## CDN +- UNPKG [https://unpkg.com/docsify/](https://unpkg.com/docsify/) +- jsDelivr [http://www.jsdelivr.com/projects/docsify](http://www.jsdelivr.com/projects/docsify) + ## Showcase These open-source projects are using docsify to generate their sites. Pull requests welcome : ) diff --git a/docs/README.md b/docs/README.md index 791885beb..83f861782 100644 --- a/docs/README.md +++ b/docs/README.md @@ -102,6 +102,11 @@ Code in `404.html` ``` + +### CDN +- UNPKG [https://unpkg.com/docsify/](https://unpkg.com/docsify/) +- jsDelivr [http://www.jsdelivr.com/projects/docsify](http://www.jsdelivr.com/projects/docsify) + ### Options #### repo @@ -160,6 +165,7 @@ 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. +** you should add `.nojekyll` into docs folder, to prevent GitHub Pages from ignoring the `_sidebar.md`** ```html @@ -234,3 +240,24 @@ Scroll to the top on changing hash. ``` +#### homepage + +`README.md` will be render as homepage for your website in docs folder, but sometimes we want to specify another file as a homepage, or even use the `README.md` in your repo. we can use: + +```html + + + +``` + + +#### basePath + +If your HTML entry file and the markdown files are in different directories, we can use: + +```html + + + + +``` diff --git a/docs/zh-cn.md b/docs/zh-cn.md index 2e76fb7ef..e6cd696ff 100644 --- a/docs/zh-cn.md +++ b/docs/zh-cn.md @@ -101,9 +101,10 @@ docsify serve docs ``` -### CDN -目前可用的 CDN 有 [UNPKG](unpkg.com/docsify)，如果觉得访问较慢可以将文件放到 Pages 的目录下。 +### CDN +- UNPKG [https://unpkg.com/docsify/](https://unpkg.com/docsify/) +- jsDelivr [http://www.jsdelivr.com/projects/docsify](http://www.jsdelivr.com/projects/docsify) ### 配置参数 @@ -161,6 +162,7 @@ Sidebar 开关按钮 #### load-sidebar 读取侧边栏配置文件，如果配置，默认加载当前目录下的 `_sidebar.md`。如果文件不存在，会显示 TOC 作为侧边栏内容。如果你有二级目录，也应该放置一份配置文件。 +**如果用 `_` 开头作为文件名，你应该在文档目录下添加 `.nojekyll`，阻止 GitHub Pages 忽略下划线开头的文件。** ```html @@ -235,3 +237,24 @@ Sidebar 开关按钮 ``` +#### homepage + +默认情况下网站会将根目录下 `README.md` 作为首页渲染，但是有些时候我们想指定其他文件，甚至想直接将 repo 下的 README 作为首页。你可以这样做： + + +```html + + + +``` + +#### basePath + +指定加载文档的路径，如果你的 HTML 入口文件和文档是放在不同地方，你可以设置： + +```html + + + + +``` diff --git a/lib/docsify.js b/lib/docsify.js index cf8e092f7..998e2e18a 100644 --- a/lib/docsify.js +++ b/lib/docsify.js @@ -2518,6 +2518,8 @@ var OPTIONS = { loadSidebar: null, loadNavbar: null, router: false, + homepage: 'README.md', + basePath: '', auto2top: false }; var script = document.currentScript || [].slice.call(document.getElementsByTagName('script')).pop(); @@ -2540,8 +2542,9 @@ var cacheRoute = null; var cacheXhr = null; var mainRender = function (cb) { - var route = getRoute(); + var route = OPTIONS.basePath + getRoute(); if (cacheRoute === route) { return cb() } + var wait; var basePath = cacheRoute = route; @@ -2551,13 +2554,18 @@ var mainRender = function (cb) { basePath = basePath.match(/(\S*\/)[^\/]+$/)[1]; } + var page; + if (!route) { + page = OPTIONS.homepage || 'README.md'; + } else if (/\/$/.test(route)) { + page = route + "README.md"; + } else { + page = route + ".md"; + } + cacheXhr && cacheXhr.abort && cacheXhr.abort(); // Render markdown file - cacheXhr = load( - (!route || /\/$/.test(route)) ? (route + "README.md") : (route + ".md"), - 'GET', - renderLoading); - + cacheXhr = load(page, 'GET', renderLoading); cacheXhr.then(function (result) { renderArticle(result); if (OPTIONS.loadSidebar) { diff --git a/lib/docsify.min.js b/lib/docsify.min.js index cbeffab61..d1f0a8958 100644 --- a/lib/docsify.min.js +++ b/lib/docsify.min.js @@ -1,2 +1,2 @@ var Docsify=function(){"use strict";function e(e,t,n){void 0===t&&(t="GET");var r=new XMLHttpRequest;return r.open(t,e),r.send(),{then:function(e,t){if(void 0===t&&(t=function(){}),n){var i=setInterval(function(e){return n({step:Math.floor(5*Math.random()+1)})},500);r.addEventListener("progress",n),r.addEventListener("loadend",function(e){n(e),clearInterval(i)})}r.addEventListener("error",t),r.addEventListener("load",function(n){var r=n.target;r.status>=400?t(r):e(r.response)})},abort:function(){return 4!==r.readyState&&r.abort()}}}function t(e,t){var n=[],r={};return e.forEach(function(e){var i=e.level||1,a=i-1;i>t||(r[a]?(r[a].children=r[a].children||[],r[a].children.push(e)):n.push(e),r[i]=e)}),n}function n(e){return e.replace(/([A-Z])/g,function(e){return"-"+e.toLowerCase()})}function r(e){return null===e||void 0===e}function i(){var e=window.location;if(_===e.hash&&!r(S))return S;var t=e.hash.match(/^#\/([^#]+)/);return t=t&&2===t.length?t[1]:/^#\//.test(e.hash)?"":e.pathname,S=t,_=e.hash,t}function a(){return document.body.clientWidth<=600}function s(){function e(){for(var e=0,r=t.length;e10){var o=n[a.id];if(!o||o===i)return;return i&&i.setAttribute("class",""),o.setAttribute("class","active"),void(i=o)}}}if(!a()){for(var t=document.querySelectorAll(".anchor"),n={},r=document.querySelectorAll(".sidebar li"),i=null,s=0,o=r.length;s\n \n '):""}function g(){return'
\n \n
\n
\n
\n
'}function d(e){return e?'':""}function f(e,t){return void 0===t&&(t=""),e&&e.length?(e.forEach(function(e){t+='
  • '+e.title+"
    • ",e.children&&(t+='
    • '+f(e.children)+"
    ")}),t):""}function m(e,t){var n=document.querySelector("nav")||document.createElement("nav");e[t?"outerHTML":"innerHTML"]=d($.sidebarToggle)+h($.repo)+g(),document.body.insertBefore(n,document.body.children[0]),u("button.sidebar-toggle")}function b(e){q("article",e?C(e):"not found"),k.rendered||k(null,$),y.rendered||y(null,$),k.rendered=!1,y.rendered=!1,$.auto2top&&c()}function y(e){E.navbar&&E.navbar===e||(E.navbar=e,y.rendered=!0,e&&q("nav",C(e)),l("nav"))}function k(e){var n=!1;e?e=C(e):$.sidebar?e=f($.sidebar,"