Danielbrzn add frontmatter

.travis.yml

@@ -3,7 +3,9 @@ node_js:
   - '8'
 before_install:
   - chmod +x ./test/test_site/test.sh
+install:
+  - npm install
 cache:
   directories:
     - node_modules
-sudo: false
+sudo: false

asset/js/setup.js

@@ -10,30 +10,32 @@ function setup() {
 }
 
 function setupWithSearch(siteData) {
-  const routeArray = jQuery.map(siteData.pages, object => object.src);
-  const titleArray = jQuery.map(siteData.pages, object => object.title);
   const { typeahead } = VueStrap.components;
   const vm = new Vue({
     el: '#app',
     components: {
       typeahead,
     },
     data() {
+      const helpers = {
+        value() { return [this.title].concat(this.keywords).join(' '); },
+        indexOf(query) { return this.value().indexOf(query); },
+        toLowerCase() { return this.value().toLowerCase(); },
+      };
       return {
-        searchData: titleArray,
+        searchData: siteData.pages.map(page => Object.assign({}, page, helpers)),
+        titleTemplate: '{{ item.title }}<br><sub>{{ item.keywords }}</sub>',
       };
     },
     methods: {
       searchCallback(match) {
-        const index = titleArray.indexOf(match);
-        const route = routeArray[index];
-        window.location.pathname = route.replace('.md', '.html');
+        window.location.pathname = match.src.replace('.md', '.html');
       },
     },
   });
   VueStrap.installEvents(vm);
 }
 
-jQuery.getJSON('../../site.json')
+jQuery.getJSON('../../siteData.json')
   .then(siteData => setupWithSearch(siteData))
   .catch(() => setup());

docs/userGuide/contentAuthoring.md

@@ -179,6 +179,39 @@ Being able to include different markdown file into the current context is anothe
 
 For detailed guide on using `<include>` tag for including contents, read the doc [here](includingContents.html).
 
+### Front Matter
+
+Front matter allows you to specify page parameters such as the title and keywords of the page. These parameters will be used to build a site data file (`siteData.json`) that will contain the index used for the search function.
+You can specify front matter at the beginning of your page by using the `<frontmatter>` tag as follows:
+
+```
+<frontmatter>
+  title: Binary Search Tree
+  keywords: bst, avl, red-black
+</frontmatter>
+```
+
+Note: A title that is defined in `site.json` for a particular page will take precedence over a title defined in the front matter.
+
+Front matter can also be included from a separate file, just like how content can be included. This makes it easy to simply define all your required front matter in one file, and use it everywhere.
+
+`matterDefinition.md`
+```
+<seg id="bst">
+  <frontmatter>
+    title: Binary Search Tree
+    keywords: bst, avl, red-black
+  </frontmatter>
+</seg>
+```
+
+`index.md`
+```
+<include src="matterDefinition.md#bst" />
+```
+
+This will result in `index.md` having the title `Binary Search Tree` and the specified keywords in order for it to be looked up through the search bar.
+
 <include src="../common/userGuideSections.md" />
 
 </div>

docs/userGuide/siteConfiguration.md

@@ -12,10 +12,14 @@ Let's examine a typical `site.json` file:
 ```
 {
   "baseUrl": "",
+  "titlePrefix": "",
   "pages": [
     {
       "src": "index.md",
       "title": "Hello World"
+    },
+    {
+      "glob": "**/index.md"
     }
   ],
   "ignore": [
@@ -33,7 +37,8 @@ Let's examine a typical `site.json` file:
 | Variable | Description |
 |----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | **baseUrl** | The url base when you deploy the website. For example, if you are using Github Pages to host your deployed website, and the resulted page is `https://markbind.github.io/site-demo-cs2103`, then your `baseUrl` would be `/site-demo-cs2103` (relative to your domain, default is ` ` (empty)). Later you could use this variable to help you create top-level navigation link in the document. **You may need to change the `baseUrl` when deploy to different repo.** |
-| **pages** | An array of the pages config tells MarkBind all the source files that needs to be rendered. The `src` is the page to be rendered; `title` is the page title for the generated web page. |
+| **titlePrefix** | The prefix for all page titles. This prefix will be prepended to all rendered pages. |
+| **pages** | An array of the pages config tells MarkBind all the source files that needs to be rendered. The `src` is the page to be rendered; `title` is the page title for the generated web page. Titles specified in this array will take priority over titles specified within the front matter of individual pages. In addition, globs can be used to define pages that will be rendered. Front matter for the pages will be automatically indexed. However, if front matter or `title` is not specified, the page will have a default title that consists only of the `titlePrefix`. |
 | **ignore** | Files to be ignored when building the website. By default, MarkBind will copy all the assets into the output folder. The ignore pattern follows the pattern used in [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format). You may want to ignore all markdown source files by adding the entry `*.md`, as well as the Git working directory `.git/*`. |
 | **deploy** | Settings for the auto Github page deployment. Please refer this [doc](ghpagesDeployment.html) for more details. |
 

lib/Page.js

@@ -6,9 +6,17 @@ const Promise = require('bluebird');
 const logger = require('./util/logger');
 const FsUtil = require('./util/fsUtil');
 const pathIsInside = require('path-is-inside');
+const cheerio = require('cheerio');
+const fm = require('fastmatter');
 
 const MarkBind = require('./markbind/lib/parser');
 
+const FRONT_MATTER_FENCE = '---';
+const TITLE_PREFIX_SEPARATOR = ' - ';
+
+cheerio.prototype.options.xmlMode = true; // Enable xml mode for self-closing tag
+cheerio.prototype.options.decodeEntities = false; // Don't escape HTML entities
+
 function Page(pageConfig) {
   this.content = pageConfig.content || '';
   this.title = pageConfig.title || '';
@@ -24,7 +32,10 @@ function Page(pageConfig) {
   this.asset = pageConfig.asset;
   this.baseUrlMap = pageConfig.baseUrlMap;
   this.userDefinedVariablesMap = pageConfig.userDefinedVariablesMap;
+  this.src = pageConfig.src;
+  this.titlePrefix = pageConfig.titlePrefix;
   this.includedFiles = {};
+  this.frontMatter = {};
 }
 
 /**
@@ -71,6 +82,56 @@ Page.prototype.collectIncludedFiles = function (dependencies) {
   });
 };
 
+/**
+ * Records the front matter into this.frontMatter
+ * @param includedPage a page with its dependencies included
+ */
+Page.prototype.collectFrontMatter = function (includedPage) {
+  const $ = cheerio.load(includedPage);
+  const frontMatter = $('frontmatter');
+  if (frontMatter.length) {
+    // Retrieves the front matter from either the first frontmatter element
+    // or from a frontmatter element that includes from another file
+    // The latter case will result in the data being wrapped in a div
+    const frontMatterData = frontMatter.find('div').length
+      ? frontMatter.find('div')[0].children[0].data
+      : frontMatter[0].children[0].data;
+    const frontMatterWrapped = `${FRONT_MATTER_FENCE}\n${frontMatterData}${FRONT_MATTER_FENCE}`;
+    // Parse front matter data
+    const parsedData = fm(frontMatterWrapped);
+    this.frontMatter = parsedData.attributes;
+    this.frontMatter.src = this.src;
+    // Title specified in site.json will override title specified in front matter
+    this.frontMatter.title = (this.title || this.frontMatter.title || '');
+    if (this.titlePrefix) {
+      this.frontMatter.title = this.frontMatter.title
+        ? this.titlePrefix + TITLE_PREFIX_SEPARATOR + this.frontMatter.title
+        : this.titlePrefix;
+    }
+  } else {
+    // Page is addressable but no front matter specified
+    const formattedTitle = this.titlePrefix
+      ? this.titlePrefix + (this.title ? TITLE_PREFIX_SEPARATOR + this.title : '')
+      : this.title;
+    this.frontMatter = {
+      src: this.src,
+      title: formattedTitle,
+    };
+  }
+  this.title = this.frontMatter.title;
+};
+
+/**
+ * Removes the front matter from an included page
+ * @param includedPage a page with its dependencies included
+ */
+Page.prototype.removeFrontMatter = function (includedPage) {
+  const $ = cheerio.load(includedPage);
+  const frontMatter = $('frontmatter');
+  frontMatter.remove();
+  return $.html();
+};
+
 Page.prototype.generate = function (builtFiles) {
   this.includedFiles = {};
   this.includedFiles[this.sourcePath] = true;
@@ -85,6 +146,10 @@ Page.prototype.generate = function (builtFiles) {
   };
   return new Promise((resolve, reject) => {
     markbinder.includeFile(this.sourcePath, fileConfig)
+      .then((result) => {
+        this.collectFrontMatter(result);
+        return this.removeFrontMatter(result);
+      })
       .then(result => markbinder.resolveBaseUrl(result, fileConfig))
       .then(result => fs.outputFileAsync(this.tempPath, result))
       .then(() => markbinder.renderFile(this.tempPath, fileConfig))
@@ -159,12 +224,18 @@ Page.prototype.resolveDependency = function (dependency, builtFiles) {
       rootPath: this.rootPath,
       cwf: file,
     })
-      .then(result => markbinder.resolveBaseUrl(result, {
-        baseUrlMap: this.baseUrlMap,
-        rootPath: this.rootPath,
-        isDynamic: true,
-        dynamicSource: source,
-      }))
+      .then(result => this.removeFrontMatter(result))
+      .then((result) => {
+        if (resultPath.includes('UserStories')) {
+          console.log(result);
+        }
+        return markbinder.resolveBaseUrl(result, {
+          baseUrlMap: this.baseUrlMap,
+          rootPath: this.rootPath,
+          isDynamic: true,
+          dynamicSource: source,
+        });
+      })
       .then(result => fs.outputFileAsync(tempPath, result))
       .then(() => markbinder.renderFile(tempPath, {
         baseUrlMap: this.baseUrlMap,