Extract description from page's front matter

Fixes #1079 and #795

lib/page/html.js

@@ -14,6 +14,9 @@ function HTMLPipeline(htmlString, opts) {
     _.bindAll(this);
 
     this.opts = _.defaults(opts || {}, {
+        // Called once the description has been found
+        onDescription: function(description) { },
+
         // Calcul new href for a relative link
         onRelativeLink: _.identity,
 
@@ -178,11 +181,21 @@ HTMLPipeline.prototype.applyAnnotations = function() {
     });
 };
 
+// Extract page description from html
+// This can totally be improved
+HTMLPipeline.prototype.extractDescription = function() {
+    var $p = this.$('p').first();
+    var description = $p.text().trim().slice(0, 155);
+
+    this.opts.onDescription(description);
+};
+
 // Write content to the pipeline
 HTMLPipeline.prototype.output = function() {
     var that = this;
 
     return Promise()
+    .then(this.extractDescription)
     .then(this.transformImages)
     .then(this.transformHeadings)
     .then(this.transformCodeBlocks)

lib/page/index.js

@@ -1,6 +1,7 @@
 var _ = require('lodash');
 var path = require('path');
 var direction = require('direction');
+var fm = require('front-matter');
 
 var error = require('../utils/error');
 var pathUtil = require('../utils/path');
@@ -25,6 +26,9 @@ function Page(book, filename) {
     // Current content
     this.content = '';
 
+    // Short description for the page
+    this.description = '';
+
     // Relative path to the page
     this.path = filename;
 
@@ -120,6 +124,7 @@ Page.prototype.getContext = function() {
             },
             page: {
                 title: article? article.title : null,
+                description: this.description,
                 next: next? next.getContext() : null,
                 previous: prev? prev.getContext() : null,
                 level: article? article.level : null,
@@ -156,6 +161,17 @@ Page.prototype.toHTML = function(output) {
 
     return this.read()
 
+    // Parse yaml front matter
+    .then(function() {
+        var parsed = fm(that.content);
+
+        // Extend page with the fontmatter attribute
+        that.description = parsed.attributes.description || '';
+
+        // Keep only the body
+        that.update(parsed.body);
+    })
+
     .then(function() {
         return hook('page:before');
     })
@@ -205,6 +221,12 @@ Page.prototype.toHTML = function(output) {
                 });
             },
 
+            // Extract description from page's content if no frontmatter
+            onDescription: function(description) {
+                if (that.description) return;
+                that.description = description;
+            },
+
             // Convert glossary entries to annotations
             annotations: that.book.glossary.annotations()
         };

package.json

@@ -50,7 +50,8 @@
         "cpr": "1.0.0",
         "direction": "0.1.5",
         "moment": "2.11.2",
-        "i18n-t": "1.0.0"
+        "i18n-t": "1.0.0",
+        "front-matter": "2.0.6"
     },
     "devDependencies": {
         "eslint": "1.5.0",

test/page.js

@@ -8,6 +8,8 @@ describe('Page', function() {
         return mock.setupDefaultBook({
             'README.md': ' # Hello World\n\nThis is a description',
             'heading.md': '# Hello\n\n## World',
+            'description.md': '# This is a title\n\nThis is the short description.\n\nNot this one.',
+            'frontmatter.md': '---\ndescription: Hello World\n---\n\n# This is a title\n\nThis is not the description',
 
             'links.md': '[link](hello.md) [link 2](variables/page/next.md) [readme](README.md)',
             'links/relative.md': '[link](../hello.md) [link 2](/variables/page/next.md) [readme](../README.md)',
@@ -128,6 +130,28 @@ describe('Page', function() {
         });
     });
 
+    describe('Description', function() {
+        it('should extratc page description from content', function() {
+            var page = book.addPage('description.md');
+
+            return page.toHTML(output)
+            .then(function() {
+                page.description.should.equal('This is the short description.');
+            });
+        });
+    });
+
+    describe('Font-Matter', function() {
+        it('should extratc page description from front matter', function() {
+            var page = book.addPage('frontmatter.md');
+
+            return page.toHTML(output)
+            .then(function() {
+                page.description.should.equal('Hello World');
+            });
+        });
+    });
+
     describe('Code Blocks', function() {
         var page;