Merge pull request #16 from garyng/master

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

Author: imfly

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",