Merge branch '180-markbind-docs' into 180-markbind-docs-preview

docs/common/devGuideSections.md

@@ -0,0 +1,6 @@
+## Sections
+- <a href="{{baseUrl}}/developerGuide/settingUp.html">Setting up for Development</a>
+- <a href="{{baseUrl}}/developerGuide/includeAndRender.html">Command: include and render</a>
+- <a href="{{baseUrl}}/developerGuide/testing.html">Testing</a>
+- <a href="{{baseUrl}}/developerGuide/publishing.html">Publishing to npm</a>
+

docs/common/header.md

@@ -1,15 +1,19 @@
 <navbar placement="top" type="inverse">
   <a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand"><img src="{{baseUrl}}/images/logo-darkbackground.png" height="20" /></a>  
   <dropdown text="User Guide">
-    <li><a href="{{baseUrl}}/userGuide.html">Home</a></li>
-    <li><a href="{{baseUrl}}/sections/userQuickStart.html">Quick Start</a></li>
-    <li><a href="{{baseUrl}}/sections/includeAndRender.html">Command: include and render</a></li>
-    <li><a href="{{baseUrl}}/sections/contentAuthoring.html">Content Authoring</a></li>
-    <li><a href="{{baseUrl}}/sections/developingASite.html">Developing a Site</a></li>
-    <li><a href="{{baseUrl}}/sections/ghpagesDeployment.html">Github Pages Deploment</a></li>
-    <li><a href="{{baseUrl}}/sections/includingContents.html">Including Contents</a></li>
-    <li><a href="{{baseUrl}}/sections/siteConfiguration.html">Site Configuration</a></li>
+    <li><a href="{{baseUrl}}/userGuide/index.html">Home</a></li>
+    <li><a href="{{baseUrl}}/userGuide/userQuickStart.html">Quick Start</a></li>
+    <li><a href="{{baseUrl}}/userGuide/contentAuthoring.html">Content Authoring</a></li>
+    <li><a href="{{baseUrl}}/userGuide/developingASite.html">Developing a Site</a></li>
+    <li><a href="{{baseUrl}}/userGuide/ghpagesDeployment.html">Github Pages Deployment</a></li>
+    <li><a href="{{baseUrl}}/userGuide/includingContents.html">Including Contents</a></li>
+    <li><a href="{{baseUrl}}/userGuide/siteConfiguration.html">Site Configuration</a></li>
   </dropdown>
-  <li><a href="{{baseUrl}}/developerGuide.html">Developer Guide</a></li>
+  <dropdown text="Developer Guide">
+  <li><a href="{{baseUrl}}/developerGuide/index.html">Home</a></li>
+  <li><a href="{{baseUrl}}/developerGuide/settingUp.html">Setting up for Development</a></li>
+  <li><a href="{{baseUrl}}/developerGuide/includeAndRender.html">Command: include and render</a></li>
+  <li><a href="{{baseUrl}}/developerGuide/testing.html">Testing</a></li>
+  <li><a href="{{baseUrl}}/developerGuide/publishing.html">Publishing to npm</a></li>
   </dropdown>  
 </navbar>

docs/common/userGuideSections.md

@@ -1,8 +1,7 @@
 ## Sections
-- <a href="{{baseUrl}}/sections/userQuickStart.html">Quick Start</a>
-- <a href="{{baseUrl}}/sections/includeAndRender.html">Command: include and render</a>
-- <a href="{{baseUrl}}/sections/contentAuthoring.html">Content Authoring</a>
-- <a href="{{baseUrl}}/sections/developingASite.html">Developing a Site</a>
-- <a href="{{baseUrl}}/sections/ghpagesDeployment.html">Github Pages Deploment</a>
-- <a href="{{baseUrl}}/sections/includingContents.html">Including Contents</a>
-- <a href="{{baseUrl}}/sections/siteConfiguration.html">Site Configuration</a>
+- <a href="{{baseUrl}}/userGuide/userQuickStart.html">Quick Start</a>
+- <a href="{{baseUrl}}/userGuide/contentAuthoring.html">Content Authoring</a>
+- <a href="{{baseUrl}}/userGuide/developingASite.html">Developing a Site</a>
+- <a href="{{baseUrl}}/userGuide/ghpagesDeployment.html">Github Pages Deploment</a>
+- <a href="{{baseUrl}}/userGuide/includingContents.html">Including Contents</a>
+- <a href="{{baseUrl}}/userGuide/siteConfiguration.html">Site Configuration</a>

docs/developerGuide/includeAndRender.md

@@ -0,0 +1,65 @@
+<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
+
+<include src="../common/header.md" />
+
+<div class="website-content">
+
+# Command: include and render
+
+MarkBind provides `include` and `render` commands to allow you include the "included" fragments in a file and render the file into a HTML document.
+
+## Usage
+Print the result to terminal.
+```
+$ markbind include example/test.md
+```
+
+Save the result to `test_out.md`. (using UNIX redirect output)
+```
+$ markbind include example/test.md > test_out.md
+```
+
+Save the result to `test_out.md`. (Using `--output` option)
+```
+$ markbind include example/test.md -o test_out.md
+```
+
+Render a file after it is `included`. (rendered to HTML content)
+```
+$ markbind render example/test_out.md -o test.html
+```
+
+## Example
+Suppose you have two files, `index.md` and `include.md`, their contents are:
+
+index.md
+```
+What the fox say?
+<include src="include.md"/>
+```
+
+include.md
+```
+Joff-tchoff-tchoffo-tchoffo-tchoff!
+Tchoff-tchoff-tchoffo-tchoffo-tchoff!
+Joff-tchoff-tchoffo-tchoffo-tchoff!
+```
+
+Next, you could run `$ markbind include index.md -o index_out.md` to check contents of `include.md` are included in the generated `index_out.md` file.
+```
+What the fox say?
+<div>
+
+Joff-tchoff-tchoffo-tchoffo-tchoff!
+Tchoff-tchoff-tchoffo-tchoffo-tchoff!
+Joff-tchoff-tchoffo-tchoffo-tchoff!
+
+</div>
+```
+(**Notice:** you may notice the included contents are wrapped by `<div>` tag. As we support writing HTML in the markdown, and including HTML in a markdown file, this is to make sure the rendered result are consistent)
+
+Now, you can render it with `$ markbind render index_out.md -o index.html`.
+
+<include src="../common/userGuideSections.md" />
+
+</div>

docs/developerGuide/index.md

@@ -0,0 +1,80 @@
+<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
+
+<include src="../common/header.md" />
+
+<div class="website-content">
+
+# Developer Guide
+
+## Requirement
+We expect contributors for *MarkBind* have the following knowledges:
+
+- [x] JavaScript (ES6)
+- [x] Node.js (LTS or higher)
+- [x] HTML & CSS
+- [x] Markdown
+- [x] Command-line interface application
+
+## Environment
+
+The *MarkBind* project should be developed with Node.js v8 or higher.
+
+We recommend you to use WebStorm for better development experience.
+
+Use JS ES6 features if possible for better performance. e.g. Promise instead of callback.
+
+## Project Structure
+*MarkBind* project consists of three repos:
+
+* [MarkBind](https://github.com/MarkBind/markbind):  the CLI application that accepts commands from users and uses the core library, that resolves the content include path, and the rendering of markdown contents, to parse and generate web pages.
+
+  Stack used: *Node.js*
+
+* [VueStrap library (forked version modified for MarkBind)](https://github.com/MarkBind/vue-strap): the UI components library used in *MarkBind* project. Users could use it in their contents to create complex and interactive structure.
+
+  Stack used: *Vue.js*
+
+### MarkBind
+The main repository is split into two parts:
+- Core Library
+- CLI
+
+#### MarkBind Core Library
+The core library parses the given markdown file, process all the content include, and render all markdown code into HTML so that it can be displayed in browser.
+
+All the core logic resides inside the `lib/parser.js` file. It exposed two important APIs: **include** and **render**.
+
+*Include* and *render* will first parse the given file as a DOM tree, then recursively visit every node to check if it needs special handling.
+
+In the include stage, it will check if the nodes will include new contents (for example, if it is an "include" tag (`<include>`), then load the file/content to be included into the current working context. For the new content included, the include step will be run through recursively until all the content to be included are resolved and loaded.
+
+Render is similar to the include process, but it will render the content recursively to ensure all markdown are converted to HTML.
+
+MarkBind uses [Markdown-It](https://github.com/markdown-it/markdown-it) to do the markdown parsing and rendering. There are also several customized Markdown-it plugins used in MarkBind, which is located inside the `lib/markdown-it/` directory.
+
+#### MarkBind CLI
+The CLI application handles the site generation logic. It contains the command handling logic, as well as the site and page models.
+
+The site generation logic is as followed:
+
+1. Read the project's `site.json` file to collect all pages that will be generated.
+2. Create a site model, where the site's root path is where `site.json` is located. The site model knows all the pages it contains, as well as the static resources. Static resources, such as stylesheets and JavaScript libraries, will be scanned and filtered, and then copy to the generated site folder (`_site/`).
+3. The site model will create different page models, and each page model will generate a HTML page file to designated file location by calling MarkBind core library's include and render API.
+
+The generated page is rendered using [EJS](https://github.com/mde/ejs) and [nunjucks](https://mozilla.github.io/nunjucks/), and the page template could be found at `lib/template/page.ejs`.
+
+Static assets of MarkBind, such as libraries and stylesheets, are located at `asset/` folder. They will be copied to the generated site  and used in the generated pages. For each version update of VueStrap, copied the built library file to overwrite the `asset/js/vue-strap.min.js`.
+
+The CLI program is built using [commander.js](https://github.com/tj/commander.js/).
+
+The auto deployment library used is [gh-pages](https://github.com/tschaub/gh-pages).
+
+### VueStrap
+
+The VueStrap library is [Bootstrap](getbootstrap.com/components/) components rewriting in [Vue.js](vuejs.org). We forked it from the original repo, and changed it based on our needs for educational websites.
+
+You can find more information at the [VueStrap repo](https://github.com/MarkBind/vue-strap).
+
+<include src="../common/devGuideSections.md" />
+
+</div>

docs/developerGuide/publishing.md

@@ -0,0 +1,29 @@
+<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
+
+<include src="../common/header.md" />
+
+<div class="website-content">
+
+# Publishing a new version
+
+When you are ready to release a new version, run
+
+```
+$ npm version [<newversion>]
+```
+
+to create a new version, where the `newversion` argument should be a valid semver string (one of patch, minor, major, prepatch, preminor, premajor, prerelease).
+
+After that, run
+
+```
+$ npm publish
+```
+
+to publish it to the NPM repository.
+
+**NOTICE**: when you made changes to markbind core library and wish to use them in the next release of CLI program, don't forget to update the new version of the core library in the `package.json` of the CLI project.
+
+<include src="../common/devGuideSections.md" />
+
+</div>

docs/developerGuide/settingUp.md

@@ -0,0 +1,31 @@
+<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
+
+<include src="../common/header.md" />
+
+<div class="website-content">
+
+# Setting up for Development
+
+1. Fork and clone the [repo](https://github.com/MarkBind/markbind).
+
+2. In the folder of your cloned repos, run
+
+    ```
+    $ npm install
+    ```
+
+    to install the project dependencies.
+
+3. To make sure you are using the cloned CLI program in your own terminal/console, in the cloned repo, run
+
+	```
+	$ npm link
+	```
+
+    to bind the local markbind CLI program to the cloned development version.
+
+4. Now you can start making changes.
+
+<include src="../common/devGuideSections.md" />
+
+</div>

docs/developerGuide/testing.md

@@ -0,0 +1,76 @@
+<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
+
+<include src="../common/header.md" />
+
+<div class="website-content">
+
+# Testing
+
+Our test script does the following:
+
+1. Lints the code for any code and style errors using ESLint
+1. Builds a test site found in `test/test_site`
+1. Compares the HTML files generated with the HTML files in `test/test_site/expected`
+
+## Running tests
+
+To execute the tests, simply run:
+
+For Unix:
+```
+$ npm run test
+```
+
+For Windows users:
+```
+$ npm run testwin
+```
+
+## Updating Tests
+
+When adding new features, updating existing features or fixing bugs, we will have to update our expected site to reflect the changes.
+
+### Changes to existing features
+
+Simply update the expected HTML files in `test/test_site/expected` to reflect the changes.
+
+### New features
+
+Add new site content into the `test/test_site` folder which accounts for the new feature. Ensure that the new content is included in the test site so that your feature will be tested when `markbind build` is run on the test site.
+Additionally, remember to update the expected HTML files in `test/test_site/expected`.
+
+## Using ESLint
+
+Our projects follow a [coding standard](https://github.com/oss-generic/process/blob/master/docs/CodingStandards.adoc). Using a linter will help check and fix some of the code style errors in your code. It will save time for both you and your code reviewer. The linting tool we use is [ESLint](https://eslint.org/). Here is [gist](https://gist.github.com/nicholaschuayunzhi/bfe53dbb5f1a0f02d545d55956f9ab7e) with explanation the eslint rules chosen in markbind-cli.
+
+### Installation
+
+Install developer dependencies (ESLint, related plugins) in your cloned markbind and markbind-cli repositories.
+```
+$ npm install --only=dev
+```
+### Lint your code
+
+Before making a commit/pull request, we highly recommend to lint your code.
+
+To lint all files, run
+```
+$ npm run lint
+```
+
+You can add the `--fix` flag to correct any fixable style errors.
+```
+$ npm run lint --fix
+```
+
+To lint a specific file, go to the root directory of the cloned repo and run
+```
+$ ./node_modules/.bin/eslint path/to/specificfile.js
+```
+
+### Integration with Editors
+ESLint has [integrations with popular editors](https://eslint.org/docs/user-guide/integrations). They offer features such as fix errors on save which will make developement more convenient.
+
+<include src="../common/devGuideSections.md" />
+
+</div>

docs/index.md

@@ -8,7 +8,7 @@
 
 MarkBind is a website generator that can generate a website from markdown documents. While there are other markdown-to-html website generators around %%(e.g., Jekyll, GitBook, MkDocs)%%, MarkBind is particularly suitable for creating course Websites. **The main aim of MarkBind is to provide a way to easily create content-heavy websites that allow _<tooltip content="i.e., the reader can go deeper or get more content as desired">self-directed consumption</tooltip>_**, as opposed to one-size-fits-all static content.  
 
-## :clipboard: Features
+## <span class="glyphicon glyphicon-th-list" aria-hidden="true"></span> Features
 
 #### ✓ Support for Markdown and <tooltip content="GitHub-Flavored Markdown">GFMD</tooltip>
 
@@ -156,7 +156,7 @@ In CS, a binary tree is a tree data structure in which each node has at most two
 
 </tip-box>
 
-## :bookmark: Examples
+## <span class="glyphicon glyphicon-bookmark" aria-hidden="true"></span> Examples
 
 Examples of websites built using MarkBind:
 * [CS2103 Software Engineering - course website](https://www.comp.nus.edu.sg/~cs2103)
@@ -165,19 +165,18 @@ Examples of websites built using MarkBind:
 * [se-edu/se-book - An online text book on Software Engineering](https://se-edu.github.io/se-book/)
 * This website (i.e., MarkBind website)
 
-## :book: Documentation
+## <span class="glyphicon glyphicon-book" aria-hidden="true"></span> Documentation
 
 #### For Users
 
-* [Quick Start]({{baseUrl}}/sections/userQuickStart.html)
-* [User Guide]({{baseUrl}}/userGuide.html)
-
+* [Quick Start](./userGuide/userQuickStart.html)
+* [User Guide](./userGuide/index.html)
 
 #### For Developers
 
-* [Developer Guide]({{baseUrl}}/developerGuide.html)
+* [Developer Guide](./developerGuide/index.html)
 
-## :mortar_board: About us
+## <span class="glyphicon glyphicon-home" aria-hidden="true"></span> About us
 
 MarkBind is a project based in the [National University of Singapore, School of Computing](http://www.comp.nus.edu.sg/), and is funded by a grant from [NUS Center for Development of Teaching and Learning](http://www.cdtl.nus.edu.sg/).
 
@@ -188,6 +187,8 @@ MarkBind is a project based in the [National University of Singapore, School of
 * [**Jiang Sheng**](https://github.com/Gisonrg): _Founding Member_ and _Team Lead_ for Aug 2016 - Jul 2017
 * [**Rachael Sim Hwee Ling**](https://github.com/rachx): _Project Member_ since Jan 2018
 
-:envelope: You can email us at `seer` at `comp.nus.edu.sg`
+<span class="glyphicon glyphicon-send" aria-hidden="true"></span> You can **email us** at `seer` at `comp.nus.edu.sg`
+
+<span class="glyphicon glyphicon-console" aria-hidden="true"></span> Interested in **contributing to MarkBind**? Visit the [MarkBind project on GitHub](https://github.com/MarkBind/markbind).
 
 </div>