feat: auto generate sidebar (#130)

* feat: auto generate sidebar

* test: generate _sidebar.md

* Apply suggestions from code review

Co-authored-by: James George <jamesgeorge998001@gmail.com>

* test: Add the sidebar file already exists test

Co-authored-by: James George <jamesgeorge998001@gmail.com>

Author: sy-records

README.md

@@ -52,7 +52,7 @@ Use `init` to generate your docs.
 ```shell
 docsify init <path> [--local false] [--theme vue]
 
-# docsify i <path> [--local false] [--theme vue]
+# docsify i <path> [-l false] [-t vue]
 ```
 
 `<path>` defaults to the current directory. Use relative paths like `./docs` (or `docs`).
@@ -75,7 +75,7 @@ Run a server on `localhost` with livereload.
 ```shell
 docsify serve <path> [--open false] [--port 3000]
 
-# docsify s <path> [--open false] [--port 3000]
+# docsify s <path> [-o false] [-p 3000]
 ```
 
 - `--open` option:
@@ -89,6 +89,22 @@ docsify serve <path> [--open false] [--port 3000]
   - Default: `3000`
   - Description: Choose a listen port, defaults to `3000`.
 
+### `generate` command
+
+Docsify's generators.
+
+```shell
+docsify generate <path> [--sidebar _sidebar.md]
+
+# docsify g <path> [-s _sidebar.md]
+```
+
+- `--sidebar` option:
+  - Shorthand: `-s`
+  - Type: string
+  - Default: `_sidebar.md`
+  - Description: Generate sidebar file, defaults to `_sidebar.md`.
+
 ## Contributing
 
 Please see the [Contributing Guidelines](./CONTRIBUTING.md)

e2e/cli.test.js.md

@@ -11,9 +11,10 @@ Generated by [AVA](https://avajs.dev).
     `Usage: docsify <init|serve> <path>␊
     ␊
     Commands:␊
-      docsify init [path]   Creates new docs                            [aliases: i]␊
-      docsify serve [path]  Run local server to preview site.           [aliases: s]␊
-      docsify start <path>  Server for SSR␊
+      docsify init [path]      Creates new docs                         [aliases: i]␊
+      docsify serve [path]     Run local server to preview site.        [aliases: s]␊
+      docsify start <path>     Server for SSR␊
+      docsify generate <path>  Docsify's generators                     [aliases: g]␊
     ␊
     Global Options␊
       --help, -h     Show help                                             [boolean]␊
@@ -35,9 +36,10 @@ Generated by [AVA](https://avajs.dev).
     `Usage: docsify <init|serve> <path>␊
     ␊
     Commands:␊
-      docsify init [path]   Creates new docs                            [aliases: i]␊
-      docsify serve [path]  Run local server to preview site.           [aliases: s]␊
-      docsify start <path>  Server for SSR␊
+      docsify init [path]      Creates new docs                         [aliases: i]␊
+      docsify serve [path]     Run local server to preview site.        [aliases: s]␊
+      docsify start <path>     Server for SSR␊
+      docsify generate <path>  Docsify's generators                     [aliases: g]␊
     ␊
     Global Options␊
       --help, -h     Show help                                             [boolean]␊
@@ -57,9 +59,10 @@ Generated by [AVA](https://avajs.dev).
     `Usage: docsify <init|serve> <path>␊
     ␊
     Commands:␊
-      docsify init [path]   Creates new docs                            [aliases: i]␊
-      docsify serve [path]  Run local server to preview site.           [aliases: s]␊
-      docsify start <path>  Server for SSR␊
+      docsify init [path]      Creates new docs                         [aliases: i]␊
+      docsify serve [path]     Run local server to preview site.        [aliases: s]␊
+      docsify start <path>     Server for SSR␊
+      docsify generate <path>  Docsify's generators                     [aliases: g]␊
     ␊
     Global Options␊
       --help, -h     Show help                                             [boolean]␊
@@ -79,9 +82,10 @@ Generated by [AVA](https://avajs.dev).
     `Usage: docsify <init|serve> <path>␊
     ␊
     Commands:␊
-      docsify init [path]   Creates new docs                            [aliases: i]␊
-      docsify serve [path]  Run local server to preview site.           [aliases: s]␊
-      docsify start <path>  Server for SSR␊
+      docsify init [path]      Creates new docs                         [aliases: i]␊
+      docsify serve [path]     Run local server to preview site.        [aliases: s]␊
+      docsify start <path>     Server for SSR␊
+      docsify generate <path>  Docsify's generators                     [aliases: g]␊
     ␊
     Global Options␊
       --help, -h     Show help                                             [boolean]␊

e2e/cli.test.js.snap

@@ -0,0 +1,31 @@
+const test = require('ava')
+const fs = require('fs')
+const path = require('path')
+
+const {run} = require('../helpers/test-utils.js')
+
+const genPath = path.join(__dirname, 'generate-cmd')
+const docsPath = path.join(genPath, 'docs')
+
+test.before('create temp directory', () => {
+  // Cleanup if the directory already exists
+  if (fs.existsSync(genPath)) {
+    fs.rmdirSync(genPath, {recursive: true})
+  }
+
+  fs.mkdirSync(genPath)
+})
+
+test.after('cleanup', () => {
+  fs.rmdirSync(genPath, {recursive: true})
+})
+
+test('generate _sidebar.md', t => {
+  run(['init', 'docs'], {cwd: genPath})
+  run(['generate', 'docs'], {cwd: genPath})
+  // Check for existence
+  t.true(fs.existsSync(path.join(docsPath, '_sidebar.md')))
+
+  const {stderr} = run(['generate', 'docs'], {cwd: genPath})
+  t.is(stderr, 'The sidebar file \'_sidebar.md\' already exists.')
+})

e2e/commands/generate.test.js

@@ -109,6 +109,23 @@ require('yargs')
       }),
     handler: argv => run.start(argv.path, argv.config, argv.port)
   })
+  .command({
+    command: 'generate <path>',
+    aliases: 'g',
+    desc: chalk.gray(y18n.__('generate')),
+    builder: yargs =>
+      yargs.options({
+        sidebar: {
+          alias: 's',
+          default: '_sidebar.md',
+          desc: chalk.gray(y18n.__('gen.sidebar')),
+          nargs: 1,
+          requiresArg: true,
+          type: 'string'
+        }
+      }),
+    handler: argv => run.generate(argv.path, argv.sidebar)
+  })
   .help()
   .option('help', {
     alias: 'h',

lib/cli.js

@@ -0,0 +1,79 @@
+'use strict'
+
+const fs = require('fs')
+const os = require('os')
+const {cwd, exists} = require('../util')
+const chalk = require('chalk')
+const path = require('path')
+const ignoreFiles = ['_navbar', '_coverpage', '_sidebar']
+
+// eslint-disable-next-line
+module.exports = function (path = '', sidebar) {
+  const cwdPath = cwd(path || '.')
+
+  if (exists(cwdPath)) {
+    if (sidebar) {
+      const sidebarPath = cwdPath + '/' + sidebar || '_sidebar.md'
+
+      if (!exists(sidebarPath)) {
+        genSidebar(cwdPath, sidebarPath)
+        console.log(chalk.green(`Successfully generated the sidebar file '${sidebar}'.`))
+        return true
+      }
+
+      console.error(chalk.red(`The sidebar file '${sidebar}' already exists.`))
+      return false
+    }
+  }
+
+  console.error(chalk.red(`${cwdPath}`) + ' directory does not exist.')
+}
+
+function genSidebar(cwdPath, sidebarPath) {
+  let tree = ''
+  let lastPath = ''
+  let nodeName = ''
+  getDirFiles(cwdPath, function (pathname) {
+    path.relative(pathname, cwdPath)
+    pathname = pathname.replace(cwdPath + '/', '')
+    let filename = path.basename(pathname, '.md')
+    let splitPath = pathname.split(path.sep)
+
+    if (ignoreFiles.indexOf(filename) === -1) {
+      nodeName = '- [' + filename + '](' + pathname + ')' + os.EOL
+    }
+
+    if (splitPath.length > 1) {
+      if (splitPath[0] !== lastPath) {
+        lastPath = splitPath[0]
+        tree += os.EOL + '- ' + splitPath[0] + os.EOL
+      }
+
+      tree += '  ' + nodeName
+    } else {
+      if (lastPath !== '') {
+        lastPath = ''
+        tree += os.EOL
+      }
+
+      tree += nodeName
+    }
+  })
+  fs.writeFile(sidebarPath, tree, 'utf8', err => {
+    if (err) {
+      console.error(chalk.red(`Couldn't generate the sidebar file, error: ${err.message}`))
+    }
+  })
+}
+
+function getDirFiles(dir, callback) {
+  fs.readdirSync(dir).forEach(function (file) {
+    let pathname = path.join(dir, file)
+
+    if (fs.statSync(pathname).isDirectory()) {
+      getDirFiles(pathname, callback)
+    } else if (path.extname(file) === '.md') {
+      callback(pathname)
+    }
+  })
+}

lib/commands/generate.js

@@ -22,7 +22,7 @@ module.exports = function (path = '', local, theme) {
   const cwdPath = cwd(path || '.')
 
   if (exists(cwdPath)) {
-    console.log(chalk.red(`${path || '.'}`) + ' already exists.')
+    console.log(chalk.red(`${path || '.'} already exists.`))
 
     prompt({
       type: 'confirm',

lib/commands/init.js

@@ -1,5 +1,6 @@
 module.exports = {
   init: require('./commands/init'),
   serve: require('./commands/serve'),
-  start: require('./commands/start')
+  start: require('./commands/start'),
+  generate: require('./commands/generate')
 }

lib/index.js

@@ -10,6 +10,8 @@
   "serve.open": "Open docs in default browser. To explicitly set --open to false you may use --no-open.",
   "serve.port": "Listen port.",
   "serve.indexname": "Custom filename instead of index.html to serve by default",
+  "generate": "Docsify's generators",
+  "generate.sidebar": "Generate sidebar file",
   "livereload.port": "livereload Listen port.",
   "usage": "Usage",
   "version": "Show version number"

tools/locales/en.json

@@ -10,6 +10,8 @@
   "serve.open": "自动打开浏览器",
   "serve.port": "设置端口",
   "serve.indexname": "Custom filename instead of index.html to serve by default",
+  "generate": "Docsify的生成器",
+  "generate.sidebar": "生成侧边栏文件",
   "livereload.port": "设置livereload端口",
   "usage": "例子",
   "version": "当前版本号"