feat(serve): --base-path serves docs from a subpath to match GitHub pages

README.md

@@ -58,9 +58,9 @@ docsify init <path> [--local false] [--theme vue]
 Run a server on `localhost` with livereload.
 
 ```shell
-docsify serve <path> [--open false] [--port 3000]
+docsify serve <path> [--open false] [--port 3000] [--base-path .]
 
-# docsify s <path> [--open false] [--port 3000]
+# docsify s <path> [--open false] [--port 3000] [--base-path .]
 ```
 
 * `--open` option:
@@ -73,6 +73,10 @@ docsify serve <path> [--open false] [--port 3000]
   * Type: number
   * Default: `3000`
   * Description: Choose a listen port, defaults to `3000`.
+* `--base-path` option:
+  * Type: string
+  * Default: `.`
+  * Description: Serves your docs under a subpath to match the behaviour of GitHub pages.
 
 ## License
 

bin/docsify

@@ -72,9 +72,16 @@ var yargs = require('yargs')
         nargs: 1,
         requiresArg: true,
         type: 'number'
+      },
+      'base-path': {
+        default: '.',
+        desc: chalk.grey(y18n.__('serve.base-path')),
+        nargs: 1,
+        requiresArg: true,
+        type: 'string'
       }
     }),
-    handler: (argv) => run.serve(argv.path, argv.open, argv.port, argv.P)
+    handler: (argv) => run.serve(argv.path, argv.open, argv.port, argv.P, argv['base-path'])
   })
   .command({
     command: 'start <path>',

docs/README.md

@@ -58,9 +58,9 @@ docsify init <path> [--local false] [--theme vue]
 Run a server on `localhost` with livereload.
 
 ```shell
-docsify serve <path> [--open false] [--port 3000]
+docsify serve <path> [--open false] [--port 3000] [--base-path .]
 
-# docsify s <path> [--open false] [--port 3000]
+# docsify s <path> [--open false] [--port 3000] [--base-path .]
 ```
 
 * `--open` option:
@@ -73,6 +73,10 @@ docsify serve <path> [--open false] [--port 3000]
   * Type: number
   * Default: `3000`
   * Description: Choose a listen port, defaults to `3000`.
+* `--base-path` option:
+  * Type: string
+  * Default: `.`
+  * Description: Serves your docs under a subpath to match the behaviour of GitHub pages.
 
 ## License
 

lib/commands/serve.js

@@ -11,9 +11,10 @@ const util = require('../util/index')
 var exists = util.exists
 var resolve = util.resolve
 
-module.exports = function (path, openInBrowser, port, livereloadPort) {
+module.exports = function (path, openInBrowser, port, livereloadPort, basePath) {
   path = resolve(path || '.')
   var indexFile = resolve(path, 'index.html')
+  const subPath = normalizePath(basePath)
 
   if (!exists(indexFile)) {
     const msg = '\nNo docs found, please run ' + chalk.green('docsify init') + ' first.\n'
@@ -25,19 +26,28 @@ module.exports = function (path, openInBrowser, port, livereloadPort) {
   server.use(livereload({
     port: livereloadPort
   }))
-  server.use(serveStatic(path))
+  server.use(subPath, serveStatic(path))
   server.listen(port)
   lrserver.createServer({
     extraExts: ['md'],
     exclusions: ['node_modules/'],
     port: livereloadPort
   }).watch(path)
 
+  const url = `http://localhost:${port}${subPath}`
   if (openInBrowser) {
-    opn(`http://localhost:${port}`)
+    opn(url)
   }
 
   const msg = '\nServing ' + chalk.green(`${path}`) + ' now.\n' +
-              'Listening at ' + chalk.green(`http://localhost:${port}`) + '\n'
+              'Listening at ' + chalk.green(url) + '\n'
   console.log(msg)
 }
+
+function normalizePath (basePath) {
+  if (basePath === '.' || basePath === '') {
+    return ''
+  }
+
+  return basePath[0] === '/' ? basePath : '/' + basePath
+}

tools/locales/de.json

@@ -18,6 +18,7 @@
     "serve.open": "Dokumentation im Standardbrowser öffnen. Um explizit --open auf false zu setzen, kannst du --no-open verwenden.",
     "serve.port": "Listen port.",
     "livereload.port": "livereload Listen port.",
+    "serve.base-path": "Erzeugt Dokumentation in einem Unterpfad, analog zur GitHub Pages Pfadstruktur.",
     "usage": "Anwendung",
     "version": "Zeige Versionsnummer an"
 }

tools/locales/en.json

@@ -18,6 +18,7 @@
     "serve.open": "Open docs in default browser. To explicitly set --open to false you may use --no-open.",
     "serve.port": "Listen port.",
     "livereload.port": "livereload Listen port.",
+    "serve.base-path": "Serves your docs under a subpath to match the behaviour of GitHub pages.",
     "usage": "Usage",
     "version": "Show version number"
 }

tools/locales/zh.json

@@ -18,6 +18,7 @@
     "serve.open": "自动打开浏览器",
     "serve.port": "设置端口",
     "livereload.port": "设置livereload端口",
+    "serve.base-path": "Serves your docs under a subpath to match the behaviour of GitHub pages.",
     "usage": "例子",
     "version": "当前版本号"
 }