+
+# 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.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?
+
+```
+(**Notice:** you may notice the included contents are wrapped by `
` 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`.
+
+
+
+
+
+# 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 (``), 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).
+
+
+
+
+
+# Publishing a new version
+
+When you are ready to release a new version, run
+
+```
+$ npm version []
+```
+
+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.
+
+
+
+
+
+# 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.
+
+
+
+
+
+# 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.
+
+
+
+
diff --git a/docs/index.md b/docs/index.md
index 78c8ec6ac0..49b25a7597 100644
--- a/docs/index.md
+++ b/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 _self-directed consumption_**, as opposed to one-size-fits-all static content.
-## :clipboard: Features
+## Features
#### ✓ Support for Markdown and GFMD
@@ -156,7 +156,7 @@ In CS, a binary tree is a tree data structure in which each node has at most two
-## :bookmark: Examples
+## 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
+## 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
+## 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`
+ You can **email us** at `seer` at `comp.nus.edu.sg`
+
+ Interested in **contributing to MarkBind**? Visit the [MarkBind project on GitHub](https://github.com/MarkBind/markbind).
+
+# 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
+
+```
+
+**Markdown** Content
+
+```
+
+use:
+
+```
+
+
+**Markdown** Content
+
+
+```
+
+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 ``
+
+ `==Highlight Text==` => `Highlight Text`
+
+* Text Underline using ``
+
+ `++Underline Text++` => `Underline Text`
+
+* 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 Content.
+
+```
+
+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 `` tag for including contents, read the doc [here](includingContents.html).
+
+
+
+
+
+# Developing a Site with MarkBind
+
+This wiki explains the basic command you need to know to develop a site with MarkBind.
+
+## Init a site with MarkBind
+MarkBind can setup a boilerplate site in the current directory:
+```
+$ markbind init
+```
+
+If you wish to create the site into a new directory, you can do so by running `markbind init ./directory`
+
+After running `init`, two files will be created for you: `index.md` and `site.json`. `index.md` is where you can start writing your contents (and will be rendered as `index.html` later), and [`site.json`](#sitejson) is the configuration file used for MarkBind to build your website correctly. **A valid `site.json` file is required to build a MarkBind-driven site**.
+
+## Preview and serve your site using:
+```
+$ markbind serve
+```
+
+MarkBind will generate the site in a folder named `_site` in the current directory. Live reload is enabled to regenerate the site for changes, so you could see the immediate rendering result after you modify the source files.
+
+| Options | Description |
+|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `-p`, `--port ` | The port used for serving your website. |
+| --no-open | Don't open browser automatically. |
+
+
+## Build the static site
+```
+$ markbind build
+```
+
+By default, MarkBind will generate the site to the folder named `_site` in the current directory, with current directory as the root directory. You can change them using
+```
+$ markbind build ./rootFolder ./outputFolder
+```
+
+## Deploy the generated site
+```
+$ markbind deploy
+```
+
+By default, it will try to push everything in the generated site (default dir: `_site`) to the `gh-pages` branch of the current git working directory's remote repo.
+
+Please check more details of deployment [here](ghpagesDeployment.html).
+
+### site.json
+Let's take a look at this newly created `site.json`:
+```
+{
+ "baseUrl": "/",
+ "pages": [
+ {
+ "src": "index.md",
+ "title": "Hello World"
+ }
+ ],
+ "ignore": [
+ "_site/*"
+ ],
+ "deploy": {
+ "message": "Site Update."
+ }
+}
+
+```
+
+| 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). Later you could use this variable to help you create top-level navigation link in the document. |
+| **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. |
+| **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`. |
+| **deploy** | Settings for the Github page deployment. Please refer to this [doc](ghpagesDeployment.html) for more details. |
+
+
+
+
+
+# Github Pages Deployment
+
+`MarkBind` supports auto deployment to Github pages with a single command
+
+```
+$ markbind deploy
+```
+
+Make sure you have initialize your project as a Github repo and have a remote added to the repo; or please specify the repo link in the `site.json`'s deployment setting.
+
+Learn more about [Github pages](https://help.github.com/categories/github-pages-basics/).
+
+### Deploy to Github pages at `gh-pages` branch of the current repo
+By default, if you have set up the current working directory as a git project, and have added the Github remote to the repo, then you are good to deploy. Simply run
+
+```
+$ markbind deploy
+```
+
+and wait it to finish deploying.
+
+After deployment, your will be able to view your site online at http://*username*.github.io/*repository*.
+
+**Note:** Don't forget to set the `baseUrl` setting in the `site.json` otherwise your deployed website may have issue with link navigation. In the above deployment example, you should set your `baseUrl` to "/*repository*".
+
+### Deployment config in `site.json`
+
+The following deployment config is available in your `site.json`'s "*deploy*" section:
+```
+"deploy": {
+ "message": "Site Update.", // This is the message for the deployment commit
+ "repo": "https://github.com/USER/REPO.git", // Or "git@github.com:USER/REPO.git" if you use SSH
+ "branch": "gh-pages" // the branch for the deployment, default to 'gh-pages'
+}
+```
+
+**If you want to use the default setting, remove the config entry or set it to empty string (`''`)**
+
+* `deploy.message`
+
+ This is the commit message used for the deployment commit.
+ (**Default**: Site Update.)
+
+* `deploy.repo`
+
+ This is the repo you want to deploy to. By default MarkBind try to push to the same repo as the current working project. If this is set, MarkBind will deploy to the given repo instead.
+ (**Default**: the current working project's repo)
+
+* `deploy.branch`
+
+ This is the branch that will be deployed to in the remote repo.
+ (**Default**: 'gh-pages')
+
+
+
+
+
+# Including contents
+
+1. #### Use `` tag to include another markdown or HTML document into current context.
+
+ ```
+
+ ```
+
+ Attributes:
+ - `src`: specify the source file path. Use a hash (#) followed by the element id to include only a segment from the file.
+
+ You could also use a remote address to load a remote accessible page/fragment (make sure they are CORS accessible). e.g.:
+ ```
+
+ ```
+
+ - `inline` (optional): make the included result an inline element. (wrapped in `` tag)
+
+ Examples:
+ ```
+
+
+
+ ```
+
+
+2. #### Wrap elements inside a `
` or `` tag with an unique `id` if you wish to create a reusable content fragment inside a file (that could be included from other file).
+
+ ⚠ The `id` cannot be exactly the same as a preceding heading, as `id` attributes will be added to headings for creating anchors.
+
+ ```
+
+ Content of segment 1
+
+
+ Content of segment 2
+
+ ```
+
+ And use `include` tag to include it, specifying the segment (element) id with `#`.
+ ```
+
+ ```
+
+
+3. #### Direct reference to a MarkBind-driven project without changing the relative path is supported.
+
+ Suppose you have a site, A, developed with MarkBind. Now, you want to include some pages from it in another site B.
+
+ MarkBind allows you to directly clone site A inside a folder in site B (ensure the `site.json` existed for site A), and include the pages you want without change anything in site A's files. This is achieved through dynamically base url calculation.
+
+ For example, now your site structure is:
+ ```
+ B/
+ A/
+ other.md
+ site.json
+ some.md (it include a file in site A, )
+ ```
+
+
+
+
+
+# MarkBind User Guide
+
+MarkBind enhances markdown and html documents with extra features that allow you to compose content-extensive website from document fragments at ease.
+
+MarkBind provides many useful markups (customized HTML tags) to help you create complex and interactive components with simple tags such as `` and ``. The reference for all supported customized elements could be found at VueStrap modified by MarkBind.
+
+For users, take a look at the [quick start guide](userQuickStart.html) to start building your website with MarkBind. For contributors, take a look at the [developer guide]({{baseUrl}}/developerGuide.html) to start developing MarkBind project.
+
+
+
+
+# Site Configuration
+
+You can configure your site generation using the `site.json` file.
+
+Let's examine a typical `site.json` file:
+```
+{
+ "baseUrl": "",
+ "pages": [
+ {
+ "src": "index.md",
+ "title": "Hello World"
+ }
+ ],
+ "ignore": [
+ "_site/*",
+ ".git/*"
+ ],
+ "deploy": {
+ "message": "Site Update."
+ }
+}
+
+```
+
+| 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. |
+| **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. |
+
+
+
+
+
+# User Quick Start
+
+## Requirement
+We expect users to have basic knowledge of the following:
+- [x] Markdown
+- [x] Command-line Environment
+
+## Installation
+`MarkBind` can be [installed using npm](https://www.npmjs.com/get-npm).
+
+You can run:
+```
+$ npm install -g markbind-cli
+```
+to install `MarkBind` on your system.
+
+After installation, you can run
+```
+$ markbind
+```
+to ensure `MarkBind` is successfully installed on your system. You should see:
+
+```
+ __ __ _ ____ _ _
+| \/ | __ _ _ __ | | __ | __ ) (_) _ __ __| |
+| |\/| | / _` | | '__| | |/ / | _ \ | | | '_ \ / _` |
+| | | | | (_| | | | | < | |_) | | | | | | | | (_| |
+|_| |_| \__,_| |_| |_|\_\ |____/ |_| |_| |_| \__,_|
+
+
+Usage: index
+
+
+Options:
+
+ -V, --version output the version number
+ -h, --help output usage information
+
+
+Commands:
+
+ include [options] process all the fragment include in the given file
+ render [options] render the given file
+ init [root] init a markbind website project
+ serve [options] [root] build then serve a website from a directory
+ deploy deploy the site to the repo's Github pages.
+ build [root] [output] build a website
+```
+
+You can add the help flag (`--help`) to any command to show the help screen.
+
+## Using MarkBind to author a Website
+### Create a new site
+MarkBind can setup a boilerplate site in the current directory:
+
+```
+$ markbind init
+```
+
+If you wish to create the site into a new directory, you can do so by running `markbind init ./directory`
+
+After running `init`, two files will be created for you: `index.md` and `site.json`. `index.md` is where you can start writing your contents (and will be rendered as `index.html` later), and `site.json` is the configuration file used for MarkBind to build your website correctly. **A valid `site.json` file is required to build a MarkBind-driven site**.
+
+You may refer to this [doc](siteConfiguration.html) for more details about how you can configure the `site.json`.
+
+### Authoring your contents
+Read more about content authoring [here](contentAuthoring.html).
+
+### Preview your site
+After authoring your contents, you can run:
+
+```
+$ markbind serve
+```
+
+to open a live preview for your generated site.
+
+MarkBind will generate the site in a folder named `_site` in the current directory.
+
+Live reload is enabled to regenerate the site for changes, so you could see the immediate rendering result after you modify the source files.
+
+| Options | Description |
+|---|---|
+| `-p`, `--port ` | The port used for serving your website. |
+| --no-open | Don't open browser automatically. |
+
+
+### Build the static site
+
+When you are ready to deploy your website, you can run
+
+```
+$ markbind build
+```
+
+to build a static website.
+
+By default, MarkBind will generate the site to the folder named `_site` in the current directory, with current directory as the root directory. You can change them using:
+
+```
+$ markbind build ./rootFolder ./outputFolder
+```
+
+### Deploy the generated site
+
+MarkBind allows you to easily deploy your generated website to Github Pages. You must first set up the working directory as a Github repo.
+
+```
+$ markbind deploy
+```
+
+By default, it will try to push everything in the generated site (default dir: `_site`) to the `gh-pages` branch of the current git working directory's remote repo.
+
+More details of deployment setting could be found in [here](ghpagesDeployment.html).
+
+
+
+
