Update GitHub templates

document customising page title with sidebar

.github/ISSUE_TEMPLATE.md

@@ -1,2 +0,0 @@
-<!-- Love docsify? Please consider supporting our collective:
-👉  https://opencollective.com/docsify/donate -->

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+<!-- Please don't delete this template or we'll close your issue -->
+<!-- Please use English language -->
+<!-- Before creating an issue please make sure you are using the latest version of Docsify. -->
+<!-- Please ask questions on StackOverflow: https://stackoverflow.com/questions/ask?tags=docsify -->
+
+## Bug Report
+
+#### Steps to reproduce
+
+
+
+#### What is current behaviour
+
+
+
+#### What is the expected behaviour
+
+---
+
+- [ ] Bug does still occur when all/other plugins are disabled?
+
+<!-- Please type in your environment -->
+Environment:
+
+```
+docsify version: 
+docsify plugins: 
+browser: 
+```
+
+<!-- Love docsify? Please consider supporting our collective:
+👉  https://opencollective.com/docsify/donate -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+
+---
+<!-- Please don't delete this template or we'll close your issue -->
+<!-- Please use English language -->
+<!-- Before creating an issue please make sure you are using the latest version of Docsify. -->
+<!-- Please ask questions on StackOverflow 👉 https://stackoverflow.com/questions/ask?tags=docsify -->
+
+## Feature request
+
+#### What problem does this feature solve?
+
+
+
+#### What does the proposed API look like?
+
+
+
+#### How should this be implemented in your opinion?
+
+
+
+#### Are you willing to work on this yourself?

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,54 @@
-Please makes sure these boxes are checked before submitting your PR, thank you!
+<!-- Please use English language -->
+<!-- Please don't delete this template -->
+
+<!-- PULL REQUEST TEMPLATE -->
+<!-- (Update "[ ]" to "[x]" to check a box) -->
+
+**Summary**
+
+**What kind of change does this PR introduce?** (check at least one)
+
+- [ ] Bugfix
+- [ ] Feature
+- [ ] Code style update
+- [ ] Refactor
+- [ ] Docs
+- [ ] Build-related changes
+- [ ] Other, please describe:
+
+If changing the UI of default theme, please provide the **before/after** screenshot:
+
+**Does this PR introduce a breaking change?** (check one)
+
+- [ ] Yes
+- [ ] No
+
+If yes, please describe the impact and migration path for existing applications:
+
+**The PR fulfills these requirements:**
+
+- [ ] When resolving a specific issue, it's referenced in the PR's title (e.g. `fix #xxx[,#xxx]`, where "xxx" is the issue number)
+
+You have tested in the following browsers: (Providing a detailed version will be better.)
+
+- [ ] Chrome
+- [ ] Firefox
+- [ ] Safari
+- [ ] Edge
+- [ ] IE
+
+If adding a **new feature**, the PR's description includes:
+
+- [ ] A convincing reason for adding this feature
+- [ ] Related documents have been updated
+- [ ] Related tests have been updated
+
+To avoid wasting your time, it's best to open a **feature request issue** first and wait for approval before working on it.
+
+
+**Other information:**
+
+---
 
-* [ ] Make sure you are merging your commits to `master` branch.
-* [ ] Add some descriptions and refer relative issues for you PR.
 * [ ] DO NOT include files inside `lib` directory.
+

docs/configuration.md

@@ -150,6 +150,46 @@ window.$docsify = {
 };
 ```
 
+## relativePath
+
+- Type: `Boolean`
+- Default: `false`
+
+If **true** links are relative to the current context.
+
+For example, the directory structure is as follows:
+
+```text
+.
+└── docs
+    ├── README.md
+    ├── guide.md
+    └── zh-cn
+        ├── README.md
+        ├── guide.md
+        └── config
+            └── example.md
+```
+
+With relative path **enabled** and current URL `http://domain.com/zh-cn/README`, given links will resolve to:
+
+```text
+guide.md              => http://domain.com/zh-cn/guide
+config/example.md     => http://domain.com/zh-cn/config/example
+../README.md          => http://domain.com/README
+/README.md            => http://domain.com/README
+```
+
+```js
+window.$docsify = {
+  // Relative path enabled
+  relativePath: true,
+
+  // Relative path disabled (default value)
+  relativePath: false
+};
+```
+
 ## coverpage
 
 - Type: `Boolean|String|String[]|Object`

docs/deploy.md

@@ -87,3 +87,45 @@ When using the HTML5 router, you need to set up redirect rules that redirect all
 ```sh
 /*    /index.html   200
 ```
+
+## AWS Amplify
+
+1. Set the routerMode in the Docsify project `index.html` to *history* mode.
+
+```html
+<script>
+    window.$docsify = {
+      loadSidebar: true,
+      routerMode: 'history'
+    }
+</script>
+```
+
+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.
+
+| Source address | Target address | Type          |
+|----------------|----------------|---------------|
+| /<*>.md        | /<*>.md        | 200 (Rewrite) |
+| /<*>           | /index.html    | 200 (Rewrite) |        
+

docs/more-pages.md

@@ -72,6 +72,16 @@ You can specify `alias` to avoid unnecessary fallback.
 
 !> You can create a `README.md` file in a subdirectory to use it as the landing page for the route.
 
+## Set Page Titles from Sidebar Selection
+
+A page's `title` tag is generated from the _selected_ sidebar item name. For better SEO, you can customize the title by specifying a string after the filename.
+
+```markdown
+<!-- docs/_sidebar.md -->
+* [Home](/)
+* [Guide](guide.md "The greatest guide in the world")
+```
+
 ## Table of Contents
 
 Once you've created `_sidebar.md`, the sidebar content is automatically generated based on the headers in the markdown files.

docs/write-a-plugin.md

@@ -79,7 +79,7 @@ window.$docsify = {
     function(hook, vm) {
       hook.beforeEach(function(html) {
         var url =
-          'https://github.com/docsifyjs/docsify/blob/master/docs' +
+          'https://github.com/docsifyjs/docsify/blob/master/docs/' +
           vm.route.file;
         var editHtml = '[📝 EDIT DOCUMENT](' + url + ')\n';
 

package-lock.json

@@ -8791,12 +8791,6 @@
         "async-limiter": "~1.0.0"
       }
     },
-    "xhr2": {
-      "version": "0.1.4",
-      "resolved": "https://registry.npmjs.org/xhr2/-/xhr2-0.1.4.tgz",
-      "integrity": "sha1-f4dliEdxbbUCYyOBL4GMras4el8=",
-      "dev": true
-    },
     "xml-name-validator": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-3.0.0.tgz",

package.json

@@ -27,7 +27,7 @@
     "dev": "run-p serve watch:*",
     "dev:ssr": "run-p serve:ssr watch:*",
     "lint": "eslint {src,packages} --fix",
-    "test": "mocha",
+    "test": "mocha test/*/**",
     "css": "stylus src/themes/*.styl -u autoprefixer-stylus",
     "watch:css": "run-p 'css -- -o themes -w'",
     "watch:js": "node build/build.js",
@@ -72,8 +72,7 @@
     "rollup-plugin-node-resolve": "^3.0.0",
     "rollup-plugin-replace": "^2.0.0",
     "rollup-plugin-uglify": "^2.0.1",
-    "stylus": "^0.54.5",
+    "stylus": "^0.54.5"
-    "xhr2": "^0.1.4"
   },
   "keywords": [
     "doc",

src/core/config.js

@@ -25,7 +25,8 @@ export default function () {
       formatUpdated: '',
       externalLinkTarget: '_blank',
       routerMode: 'hash',
-      noCompileLinks: []
+      noCompileLinks: [],
+      relativePath: false
     },
     window.$docsify
   )

src/core/router/history/base.js

@@ -3,7 +3,8 @@ import {
   isAbsolutePath,
   stringifyQuery,
   cleanPath,
-  replaceSlug
+  replaceSlug,
+  resolvePath
 } from '../util'
 import {noop, merge} from '../../util/core'
 
@@ -73,9 +74,13 @@ export class History {
     if (local) {
       const idIndex = currentRoute.indexOf('?')
       path =
-        (idIndex > 0 ? currentRoute.substr(0, idIndex) : currentRoute) + path
+        (idIndex > 0 ? currentRoute.substring(0, idIndex) : currentRoute) + path
     }
 
+    if (this.config.relativePath && path.indexOf('/') !== 0) {
+      const currentDir = currentRoute.substring(0, currentRoute.lastIndexOf('/') + 1)
+      return cleanPath(resolvePath(currentDir + path))
+    }
     return cleanPath('/' + path)
   }
 }

src/core/router/util.js

@@ -53,6 +53,20 @@ export const cleanPath = cached(path => {
   return path.replace(/^\/+/, '/').replace(/([^:])\/{2,}/g, '$1/')
 })
 
+export const resolvePath = cached(path => {
+  const segments = path.replace(/^\//, '').split('/')
+  let resolved = []
+  for (let i = 0, len = segments.length; i < len; i++) {
+    const segment = segments[i]
+    if (segment === '..') {
+      resolved.pop()
+    } else if (segment !== '.') {
+      resolved.push(segment)
+    }
+  }
+  return '/' + resolved.join('/')
+})
+
 export function getPath(...args) {
   return cleanPath(args.join('/'))
 }

src/plugins/gitalk.js

@@ -7,10 +7,16 @@ function install(hook) {
     const main = dom.getNode('#main')
     div.style = `width: ${main.clientWidth}px; margin: 0 auto 20px;`
     dom.appendTo(dom.find('.content'), div)
-    const script = dom.create('script')
+  })
-    const content = `gitalk.render('gitalk-container')`
+
-    script.textContent = content
+  hook.doneEach(_ => {
-    dom.appendTo(dom.body, script)
+    const el = document.getElementById('gitalk-container')
+    while (el.hasChildNodes()) {
+      el.removeChild(el.firstChild)
+    }
+
+    // eslint-disable-next-line
+    gitalk.render('gitalk-container')
   })
 }
 

src/themes/basic/_layout.styl

@@ -323,6 +323,9 @@ body.sticky
 
 .markdown-section iframe
   border 1px solid #eee
+  /* fix horizontal overflow on iOS Safari */
+  width 1px
+  min-width 100%
 
 .markdown-section table
   border-collapse collapse

test/_helper.js

@@ -1,45 +1,10 @@
 // load ES6 modules in Node.js on the fly
 require = require('esm')(module/*, options*/)
 
+const path = require('path')
 const {expect} = require('chai')
 
 const {JSDOM} = require('jsdom')
-const XMLHttpRequest = require('xhr2') // JSDOM doesn't support XMLHttpRequest
-// TODO: try to fix tests when using `<div id="app"></div>` in body
-const markup = `<!DOCTYPE html>
-<html>
-  <head></head>
-  <body></body>
-</html>`
-// TODO: this may not work if tests are mutate the DOM, instead a new instance needs to be created
-// for every test case but that will slow down the tests
-const dom = new JSDOM(markup) 
-
-global.window = dom.window
-global.document = dom.window.document
-global.navigator = dom.window.navigator
-global.location = dom.window.location
-global.XMLHttpRequest = XMLHttpRequest
-
-const {initMixin} = require('../src/core/init')
-const {routerMixin} = require('../src/core//router')
-const {renderMixin} = require('../src/core//render')
-const {fetchMixin} = require('../src/core/fetch')
-const {eventMixin} = require('../src/core//event')
-
-// mimic src/core/index.js but for Node.js
-
-function Docsify() {
-  this._init()
-}
-
-const proto = Docsify.prototype
-
-initMixin(proto)
-routerMixin(proto)
-renderMixin(proto)
-fetchMixin(proto)
-eventMixin(proto)
 
 function ready(callback) {
   const state = document.readyState
@@ -50,16 +15,64 @@ function ready(callback) {
 
   document.addEventListener('DOMContentLoaded', callback)
 }
-let docsify = null
+module.exports.init = function(fixture = 'default', config = {}, markup) {
-module.exports.init = function(callback) {
+	if (markup == null) {
+		markup = `<!DOCTYPE html>
+		<html>
+		  <head></head>
+		  <body>
+		  	<div id="app"></div>
+		  	<script>
+		  		window.$docsify = ${JSON.stringify(config, null, 2)}
+		  	</script>
+		  </body>
+		</html>`
+	}
+	const rootPath = path.join(__dirname, 'fixtures', fixture)
+		
+	const dom = new JSDOM(markup) 
+	dom.reconfigure({ url: 'file:///' + rootPath })
+
+	global.window = dom.window
+	global.document = dom.window.document
+	global.navigator = dom.window.navigator
+	global.location = dom.window.location
+	global.XMLHttpRequest = dom.window.XMLHttpRequest
+
+	// mimic src/core/index.js but for Node.js
+	function Docsify() {
+	  this._init()
+	}
+
+	const proto = Docsify.prototype
+
+	const {initMixin} = require('../src/core/init')
+	const {routerMixin} = require('../src/core//router')
+	const {renderMixin} = require('../src/core//render')
+	const {fetchMixin} = require('../src/core/fetch')
+	const {eventMixin} = require('../src/core//event')
+
+	initMixin(proto)
+	routerMixin(proto)
+	renderMixin(proto)
+	fetchMixin(proto)
+	eventMixin(proto)
+
+	const NOT_INIT_PATTERN = '<!--main-->'
+
 	return new Promise((resolve, reject) => {
-		// return cached version / TODO: see above: this might not scale, new instance of JSDOM is reqiured
+		ready(() => {
-		if (docsify != null) {
+			const docsify = new Docsify()
-			return resolve(docsify)
+			// NOTE: I was not able to get it working with a callback, but polling works usually at the first time
-		}
+			const id = setInterval(() => {
-		ready(_ => {
+				if (dom.window.document.body.innerHTML.indexOf(NOT_INIT_PATTERN) == -1) {
-			docsify = new Docsify()
+					clearInterval(id)
-			return resolve(docsify)
+					return resolve({
+						docsify: docsify,
+						dom: dom
+					})
+				}
+			}, 10)
 		})
 		
 	})

test/fixtures/default/README.md

@@ -0,0 +1,6 @@
+<!-- 
+
+create your own fixture directory
+if you need a custom README.md or sidebar
+
+-->

test/fixtures/simple/README.md

@@ -0,0 +1,18 @@
+# Heading
+
+[another page](other.md)
+
+## II 1
+
+### III 1
+
+#### IV 1
+
+##### V 1
+
+
+## II 2
+
+### III 2
+
+#### IV 2

test/fixtures/simple/other-page.md

@@ -0,0 +1,16 @@
+# Other
+
+## two 1
+
+### three 1
+
+#### four 1
+
+##### five 1 
+
+
+## two 2
+
+### three 2
+
+#### four 2

test/integration/render.js

@@ -0,0 +1,14 @@
+const path = require('path')
+
+const {expect} = require('chai')
+
+const {init, expectSameDom} = require('../_helper')
+
+describe('full docsify initialization', function() {
+	it('TODO: check generated markup', async function() {
+		const {docsify, dom} = await init('simple', {loadSidebar: true})
+  		console.log(dom.window.document.body.innerHTML)
+  		// TODO: add some expectations
+	})
+
+})

test/integration/router.js

@@ -0,0 +1,14 @@
+const path = require('path')
+
+const {expect} = require('chai')
+
+const {init, expectSameDom} = require('../_helper')
+
+describe('router', function() {
+	it('TODO: trigger to load another page', async function() {
+		const {docsify} = await init()
+  		window.location = '/?foo=bar'
+  		// TODO: add some expectations
+	})
+
+})

test/unit/base.js

@@ -0,0 +1,62 @@
+/* eslint-env node, chai, mocha */
+require = require('esm')(module/*, options*/)
+const {expect} = require('chai')
+const {History} = require('../../src/core/router/history/base')
+
+class MockHistory extends History {
+  parse(path) {
+    return {path}
+  }
+}
+
+describe('router/history/base', function () {
+  describe('relativePath true', function () {
+    var history
+
+    beforeEach(function () {
+      history = new MockHistory({relativePath: true})
+    })
+
+    it('toURL', function () {
+      // WHEN
+      const url = history.toURL('guide.md', {}, '/zh-ch/')
+
+      // THEN
+      expect(url).equal('/zh-ch/guide')
+    })
+
+    it('toURL with double dot', function () {
+      // WHEN
+      const url = history.toURL('../README.md', {}, '/zh-ch/')
+
+      // THEN
+      expect(url).equal('/README')
+    })
+
+    it('toURL child path', function () {
+      // WHEN
+      const url = history.toURL('config/example.md', {}, '/zh-ch/')
+
+      // THEN
+      expect(url).equal('/zh-ch/config/example')
+    })
+
+    it('toURL absolute path', function () {
+      // WHEN
+      const url = history.toURL('/README', {}, '/zh-ch/')
+
+      // THEN
+      expect(url).equal('/README')
+    })
+  })
+
+  it('toURL without relative path', function () {
+    const history = new MockHistory({relativePath: false})
+
+    // WHEN
+    const url = history.toURL('README', {}, '/zh-ch/')
+
+    // THEN
+    expect(url).equal('/README')
+  })
+})

test/unit/render.js

@@ -2,18 +2,18 @@ const path = require('path')
 
 const {expect} = require('chai')
 
-const {init, expectSameDom} = require('./_helper')
+const {init, expectSameDom} = require('../_helper')
 
 describe('render', function() {
 	it('important content (tips)', async function() {
-		docsify = await init()
+		const {docsify, dom} = await init()
   		const output = docsify.compiler.compile('!> **Time** is money, my friend!')
   		expect(output).equal('<p class="tip"><strong>Time</strong> is money, my friend!</p>')
 	})
 
 	describe('lists', function() {
 		it('as unordered task list', async function() {
-			docsify = await init()
+			const {docsify, dom} = await init()
 			const output = docsify.compiler.compile(`
 - [x] Task 1
 - [ ] Task 2
@@ -26,7 +26,7 @@ describe('render', function() {
 		})
 
 		it('as ordered task list', async function() {
-			docsify = await init()
+			const {docsify, dom} = await init()
 			const output = docsify.compiler.compile(`
 1. [ ] Task 1
 2. [x] Task 2`)
@@ -37,7 +37,7 @@ describe('render', function() {
 		})
 
 		it('normal unordered', async function() {
-			docsify = await init()
+			const {docsify, dom} = await init()
 			const output = docsify.compiler.compile(`
 - [linktext](link)
 - just text`)
@@ -48,7 +48,7 @@ describe('render', function() {
 		})
 
 		it('unordered with custom start', async function() {
-			docsify = await init()
+			const {docsify, dom} = await init()
 			const output = docsify.compiler.compile(`
 1. first
 2. second
@@ -67,7 +67,7 @@ text
 		})
 
 		it('nested', async function() {
-			docsify = await init()
+			const {docsify, dom} = await init()
 			const output = docsify.compiler.compile(`
 - 1
 - 2

test/unit/util.js

@@ -0,0 +1,30 @@
+/* eslint-env node, chai, mocha */
+require = require('esm')(module/*, options*/)
+const {expect} = require('chai')
+const {resolvePath} = require('../../src/core/router/util')
+
+describe('router/util', function () {
+  it('resolvePath', async function () {
+    // WHEN
+    const result = resolvePath('hello.md')
+
+    // THEN
+    expect(result).equal('/hello.md')
+  })
+
+  it('resolvePath with dot', async function () {
+    // WHEN
+    const result = resolvePath('./hello.md')
+
+    // THEN
+    expect(result).equal('/hello.md')
+  })
+
+  it('resolvePath with two dots', async function () {
+    // WHEN
+    const result = resolvePath('test/../hello.md')
+
+    // THEN
+    expect(result).equal('/hello.md')
+  })
+})