Feature: Add ability to get title from file's frontmatter

README.md

@@ -56,7 +56,33 @@ or, For example:
 $ book sm -r ../sailsjs-docs-gitbook/en -i 0home -u 'myApp' -c 'concepts, reference, userguides' -n "Sails.js 官方文档(中英合辑）"
 ```
 
-**Note**： `-s` or `--sortedBy` can not be given `-`, commander.js will parse it an option. But you can set it in `book.json` as follow.
+To see the command line options:
+
+```
+$ book sm --help
+
+  Usage: summary|sm [options]
+
+  Generate a `SUMMARY.md` from a folder
+
+  Options:
+
+    -h, --help                    output usage information
+    -r, --root [string]           root folder, default is `.`
+    -n, --bookname [string]       book name, default is `Your Book Name`.
+    -c, --catalog [list]          catalog folders included book files, default is `all`.
+    -i, --ignores [list]          ignore folders that be excluded, default is `[]`.
+    -u, --unchanged [list]        unchanged catalog like `request.js`, default is `[]`.
+    -o, --outputfile [string]     output file, defaut is `./SUMMARY.md`
+    -s, --sortedBy [string]       sorted by sortedBy, for example: `num-`, defaut is sorted by characters
+    -d, --disableTitleFormatting  don't convert filename/folder name to start case (for example: `JavaScript` to `Java Script`), default is `false`
+
+```
+
+**Notes**： 
+* The article title is taken from `title` property in the articles front-matter. If this property is not available, the articles filename will be used as title for the summary. 
+* The option `-s` or `--sortedBy` can not be given `-` as argument, because commander.js will parse it an option. But you can set it in `book.json` as follows.
+
 
 2> Create a `book.json` in the book`s root folder
 
@@ -70,7 +96,8 @@ for example:
     "catalog": "all",  // or [chapter1，chapter2, ...]
     "ignores": [],  //Default: '.*', '_book'...
     "unchanged": [], // for example: ['myApp'] -> `myApp` not `My App`
-    "sortedBy": "-"
+    "sortedBy": "-",
+    "disableTitleFormatting": true // default: false
 }
 ```
 

bin/summary.js

@@ -27,9 +27,10 @@ program
   .option("-u, --unchanged [list]", "unchanged catalog like `request.js`, default is `[]`.")
   .option("-o, --outputfile [string]", "output file, defaut is `./SUMMARY.md`")
   .option("-s, --sortedBy [string]", "sorted by sortedBy, for example: `num-`, defaut is sorted by characters")
+  .option("-d, --disableTitleFormatting", "don't convert filename/folder name to start case (for example: `JavaScript` to `Java Script`), default is `false`")
   .action(function(options) {
     // generate `SUMMARY.md`
-    // Fixme 
+    // Fixme
     // if (options.length >= 1) {
     //   console.log(color.red('\nError! The sub commands "%s" has been deprecated, please read the follow messages:'), cmd);
     //   program.help();

lib/bookJson.js

@@ -19,7 +19,8 @@ function BookConfig(root) {
     book.unchanged = config.unchanged || [];
     book.bookname = config.bookname || 'Your Book Name';
     book.sortedBy = config.sortedBy || '';
-
+    book.disableTitleFormatting = config.disableTitleFormatting || false;
+
     return book;
 }
 

lib/files.js

@@ -3,6 +3,7 @@ var fs = require('fs');
 var path = require('path');
 var async = require('async');
 var color = require('bash-color');
+var fm = require('front-matter');
 
 // Use a loop to read all files
 function ReadFile(filePath, filesJson, sortedBy) {
@@ -60,10 +61,25 @@ function ReadFile(filePath, filesJson, sortedBy) {
       var obj = path.parse(newpath);
 
       if (obj.ext === '.md') {
-        filesJson[obj.name] = newpath + ")\n";
+        filesJson[getFrontMatterTitle(newpath)] = newpath + ")\n";
       }
     }
   }
+
+  function getFrontMatterTitle(newpath)
+  {
+    // default to use filename
+    var title = path.parse(newpath).name;
+    var content = fs.readFileSync(newpath,'utf8');
+
+    if (!fm.test(content)) return title;  // skip if no front matter
+
+    var frontMatter = fm(content);
+    if (typeof frontMatter.attributes.title === "undefined") return title;      // skip if no 'title' attributes
+    // todo: set 'title' via config
+
+    return frontMatter.attributes.title;
+  }
 }
 
 module.exports = ReadFile;

lib/summary/index.js

@@ -20,7 +20,8 @@ var root,
     catalog,
     ignores,
     unchanged,
-    sortedBy;
+    sortedBy,
+    disableTitleFormatting;
 
 // Get options
 function init(options) {
@@ -34,6 +35,7 @@ function init(options) {
     unchanged = options.unchanged || bookConfig.unchanged;
     bookname = options.bookname || bookConfig.bookname;
     sortedBy = options.sortedBy || bookConfig.sortedBy;
+    disableTitleFormatting = options.disableTitleFormatting || bookConfig.disableTitleFormatting;
 }
 
 // Get summary
@@ -166,9 +168,8 @@ function prettyCatalogName(fileName) {
             fileName = fileName.match(folderNameReg)[1];
         }
     }
-
     // Don`t format the files like `req.options.*` using dot, unchanged or Chinese string.
-    if (_.size(fileName.split(".")) > 1 || _.includes(unchanged, fileName) || isChinese(fileName)) {
+    if (_.size(fileName.split(".")) > 1 || _.includes(unchanged, fileName) || isChinese(fileName) || disableTitleFormatting) {
         return fileName;
     }
     return _.startCase(fileName);
@@ -191,7 +192,7 @@ function isSkiped(key, skip) {
 // Write to file  encoded with utf-8
 function writeFile(fileName, data) {
     fs.writeFile(fileName, data, 'utf-8', function() {
-        console.log(color.green("Finished, generate a SUMMARY.md successfully."));
+        console.log(color.green("Finished, generated '"+fileName+"' successfully."));
     })
 }
 

package.json

@@ -34,6 +34,7 @@
     "bash-color": "0.0.3",
     "cheerio": "^0.20.0",
     "commander": "^2.9.0",
+    "front-matter": "^2.1.1",
     "fs-extra": "^0.26.2",
     "iconv-lite": "^0.4.13",
     "lodash": "^3.10.1",