Skip to content
This repository was archived by the owner on Apr 29, 2019. It is now read-only.

Developer Guide

Jump to bottom
Aaron Chong edited this page Jan 19, 2018 · 18 revisions

Requirement

We expect contributors for MarkBind have the following knowledges:

  • JavaScript (ES6)
  • Node.js (LTS or higher)
  • HTML & CSS
  • Markdown
  • Command-line interface application

Environment

The MarkBind project should be developed with Node.js v6.5 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 Strcutre

MarkBind project consists of three repos:

MarkBind Core Library

The core library parse the given markdown file, process all the content include, and render all markdown code into HTML so that it could 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 include stage, it will check if the node 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 process to include, but it will render the content recursively to ensure all markdown are converted to HTML.

MarkBind uses 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 and 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.

The auto deployment library used is gh-pages.

VueStrap

The VueStrap library is Bootstrap components rewriting in Vue.js. 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.

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.

  1. 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.

  1. Now you can start making changes.

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.

Clone this wiki locally