180 markbind docs preview

docs/common/header.md

@@ -1,3 +1,12 @@
 <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/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>  
 </navbar>

docs/common/userGuideSections.md

@@ -0,0 +1,7 @@
+## Sections
+- <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 Deployment</a>
+- <a href="{{baseUrl}}/userGuide/includingContents.html">Including Contents</a>
+- <a href="{{baseUrl}}/userGuide/siteConfiguration.html">Site Configuration</a>

docs/developerGuide.md

@@ -0,0 +1,154 @@
+<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
+
+<include src="./common/header.md" />
+
+<div class="website-content">
+
+## 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).
+
+## Development Process
+
+### Development
+
+1. Fork and clone the repo.
+
+   We recommend that during your local development, clone both core library and the CLI repo to your system. And change the `require` statement for the core library in CLI to your local core library path.
+
+   For example, in `index.js` of `markbind-cli`, change `const MarkBind = require('markbind');` to `const MarkBind = require('../path/to/markbind');`. In this way, your changes to the core library will be reflected in your CLI program immediately.
+
+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 CLI repo, run
+
+	```
+	$ npm link
+	```
+
+  to bind the local markbind CLI program to the cloned development version.
+
+4. Now you can start making changes.
+
+### 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 a specific file, go to the root directory of the cloned repo and run
+```
+$ ./node_modules/.bin/eslint path/to/specificfile.js
+```
+To lint all files, run
+```
+$ ./node_modules/.bin/eslint .
+```
+
+You can add the `--fix` flag to correct any fixable style errors.
+```
+$ ./node_modules/.bin/eslint . --fix
+```
+
+#### 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.
+
+### 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.
+
+</div>

docs/index.md

@@ -14,7 +14,7 @@ MarkBind is a website generator that can generate a website from markdown docume
 
 MarkBind supports all MarkDown and GFMD syntax. Here is an example:
 
-<table> 
+<table>
 <tr>
   <td>
 
@@ -46,7 +46,7 @@ MarkBind supports all MarkDown and GFMD syntax. Here is an example:
 
 The example paragraph below has a tooltip, a pop-over, and a modal. Hover/click on the underlined words to see each.
 
-<tip-box> 
+<tip-box>
 
 In <tooltip content="Computer Science">CS</tooltip>, a binary tree is a <trigger for="pop:index-tree">tree data structure</trigger> in which each node has at most two children, which are referred to as the _left child_ and the _right child_. <trigger trigger="click" for="modal:index-primitive">Primitive data types</trigger> on the other hand ...
 
@@ -57,7 +57,7 @@ In <tooltip content="Computer Science">CS</tooltip>, a binary tree is a <trigger
 %%<sub>[source:wikipedia]</sub>%%
 
   </div>
-</popover> 
+</popover>
 
 <modal large title="Some examples of primitive data types" id="modal:index-primitive">
   <include src="pages/primitiveDataTypes.md" />
@@ -69,7 +69,7 @@ In <tooltip content="Computer Science">CS</tooltip>, a binary tree is a <trigger
 
 In addition to the ability to show **bold** and _italic_ text provided by normal Markdown, MarkBind can ==highlight== text or show text in %%grey color%% easily.
 
-<table> 
+<table>
 <tr>
   <td>
 
@@ -85,7 +85,7 @@ _itatic text_
   <td>&nbsp;→&nbsp;</td>
   <td><br>
 
-<tip-box> 
+<tip-box>
 
 **bold text**<br>
 _itatic text_<br>
@@ -103,7 +103,7 @@ _itatic text_<br>
 
 In the example below, there is a expandable panel that can reveal more content.
 
-<tip-box> 
+<tip-box>
 
 A binary tree is a tree data structure in which each node has at most two children, which are referred to as the left child and the right child. Primitive data types on the other hand ...
 
@@ -115,20 +115,20 @@ A binary tree is a tree data structure in which each node has at most two childr
 
 In the example below, there are expandable panels that are nested within each other.
 
-<tip-box> 
+<tip-box>
 
 <panel type="info" header=":muscle: Exercises" no-close >
-  
+
   <panel type="danger" header=":exclamation: [Compulsory] Ex 1" no-close >
-  
+
 Details of exercise 1
   </panel>  
   <panel type="warning" header="[Recommended] Ex 2" no-close >
-  
+
 Details of exercise 2
   </panel>  
   <panel type="success" header="[Optional] Ex 23" no-close >
-  
+
 Details of exercise 3
   </panel>
 </panel>
@@ -142,7 +142,7 @@ MarkBind has a powerful`include` mechanism that allows content fragments (i.e.,
 
 In the example below, both the modal and the expandable panel reuses the same content.
 
-<tip-box> 
+<tip-box>
 
 In CS, a binary tree is a tree data structure in which each node has at most two children, which are referred to as the _left child_ and the _right child_. <trigger trigger="click" for="modal:index-primitive2">Primitive data types</trigger> on the other hand ...
 
@@ -158,19 +158,19 @@ In CS, a binary tree is a tree data structure in which each node has at most two
 
 ## <span class="glyphicon glyphicon-bookmark" aria-hidden="true"></span> Examples
 
-Examples of websites built using MarkBind: 
+Examples of websites built using MarkBind:
 * [CS2103 Software Engineering - course website](https://www.comp.nus.edu.sg/~cs2103)
 * [CS3281 Thematic Systems Project - course website](https://nus-cs3281.github.io/website/)
 * [TE3291 Software Engineering - course website](https://nus-te3201.github.io/website/)
 * [se-edu/se-book - An online text book on Software Engineering](https://se-edu.github.io/se-book/)
 * This website (i.e., MarkBind website)
 
-## <span class="glyphicon glyphicon-book" aria-hidden="true"></span> Documentation 
+## <span class="glyphicon glyphicon-book" aria-hidden="true"></span> Documentation
 
 #### For Users
 
-* [Quick Start](https://github.com/MarkBind/markbind-cli/wiki/User-Quick-Start)
-
+* [Quick Start](./userGuide/userQuickStart.html)
+* [User Guide](./userGuide/index.html)
 
 #### For Developers
 

docs/sections/contentAuthoring.md

@@ -0,0 +1,92 @@
+<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
+
+<include src="../common/header.md" />
+
+<div class="website-content">
+
+# Content authoring
+### General writing guide
+*MarkBind* allows you to mix HTML with Markdown code. Be sure to use new line to separate Markdown from HTML elements.
+e.g.
+
+Instead of
+
+```
+<Panel>
+**Markdown** Content
+</Panel>
+```
+
+use:
+
+```
+<Panel>
+
+**Markdown** Content
+
+</Panel>
+```
+
+Use `{{baseUrl}}` for absolute path reference of images and resource files so that the path could be handled correctly when deployed. The `{{baseUrl}}` is parsed from the project root (where `site.json` located).
+
+### Supported Markdown Syntax
+
+	MarkBind support the standard Markdown syntax. Read the [guide](https://guides.github.com/features/mastering-markdown/).
+
+In addition, it supports:
+
+* [Tables](https://help.github.com/articles/organizing-information-with-tables/)(GFM)
+* [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text)(GFM)
+* [Emoji](https://www.webpagefx.com/tools/emoji-cheat-sheet/) shortcut is supported.
+
+  `:EMOJICODE:`. For example, `:smile:` will be rendered as :smile:.
+
+* [Task List](https://help.github.com/articles/basic-writing-and-formatting-syntax/#task-lists)
+* Text Hightlight using `<mark>`
+
+  `==Highlight Text==` => `<mark>Highlight Text</mark>`
+
+* Text Underline using `<ins>`
+
+  `++Underline Text++` => `<ins>Underline Text</ins>`
+
+* Dimmed Text (Text with grey background)
+
+  `%%Dimmed Text%%`
+
+* Radio Button List
+
+  ```
+  - ( ) Option 1
+  - (X) Option 2 (selected)
+  ```
+
+* Media block ([docs](https://github.com/rotorz/markdown-it-block-embed))
+
+  ```
+  @[youtube](lJIrF4YjHfQ)
+  @[powerpoint](https://onedrive.live.com/embed?cid=A5AF047C4CAD67AB&resid=A5AF047C4CAD67AB%212070&authkey=&em=2) // the embed url from powerpoint online
+  ```
+
+
+### Use Components
+
+To use an component, just type the correspond markup in your file. For example, to create a Panel, you just need to write:
+
+```
+<panel header="Click to expand" type="seamless">
+	Panel Content.
+</panel>
+```
+
+For a list of supported components, refer to the component [doc](https://markbind.github.io/vue-strap/).
+
+### Include Contents
+
+Being able to include different markdown file into the current context is another feauture of *MarkBind*. You can create a complex document from different content fragments by including them.
+
+For detailed guide on using `<include>` tag for including contents, read the doc [here]({{baseUrl}}/sections/includingContents.html).
+
+<include src="../common/userGuideSections.md" />
+
+</div>