From f5e26c0745f44708e77ce5a9fa45d8d70a77e1c0 Mon Sep 17 00:00:00 2001 From: "Damith C. Rajapakse" Date: Fri, 30 Mar 2018 19:47:11 +0800 Subject: [PATCH 1/7] docs/index.md: use glyphicons --- docs/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index 195ae7d38d..e2a5b99587 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,7 +165,7 @@ 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 @@ -176,7 +176,7 @@ Examples of websites built using MarkBind: * [Developer Guide](https://github.com/MarkBind/markbind-cli/wiki/Developer-Guide) -## :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/). @@ -187,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). From b492f964e424c7f5613919f53e8e54d04826cc1f Mon Sep 17 00:00:00 2001 From: nicholaschuayunzhi Date: Sat, 31 Mar 2018 14:17:56 +0800 Subject: [PATCH 2/7] Add user guide and dev guide to main site --- docs/common/header.md | 12 +++ docs/common/userGuideSections.md | 8 ++ docs/developerGuide.md | 154 +++++++++++++++++++++++++++++ docs/index.md | 33 ++++--- docs/sections/contentAuthoring.md | 92 +++++++++++++++++ docs/sections/developingASite.md | 83 ++++++++++++++++ docs/sections/ghpagesDeployment.md | 62 ++++++++++++ docs/sections/includeAndRender.md | 65 ++++++++++++ docs/sections/includingContents.md | 69 +++++++++++++ docs/sections/siteConfiguration.md | 41 ++++++++ docs/sections/userQuickStart.md | 131 ++++++++++++++++++++++++ docs/site.json | 36 +++++++ docs/userGuide.md | 16 +++ 13 files changed, 786 insertions(+), 16 deletions(-) create mode 100644 docs/common/userGuideSections.md create mode 100644 docs/developerGuide.md create mode 100644 docs/sections/contentAuthoring.md create mode 100644 docs/sections/developingASite.md create mode 100644 docs/sections/ghpagesDeployment.md create mode 100644 docs/sections/includeAndRender.md create mode 100644 docs/sections/includingContents.md create mode 100644 docs/sections/siteConfiguration.md create mode 100644 docs/sections/userQuickStart.md create mode 100644 docs/userGuide.md diff --git a/docs/common/header.md b/docs/common/header.md index 4632d79ff0..d24b8dd928 100644 --- a/docs/common/header.md +++ b/docs/common/header.md @@ -1,3 +1,15 @@ + +
  • Home
    • +
  • Quick Start
    • +
  • Command: include and render
    • +
  • Content Authoring
    • +
  • Developing a Site
    • +
  • Github Pages Deploment
    • +
  • Including Contents
    • +
  • Site Configuration
    • +     +
  • Developer Guide
    • +     diff --git a/docs/common/userGuideSections.md b/docs/common/userGuideSections.md new file mode 100644 index 0000000000..a0f4065277 --- /dev/null +++ b/docs/common/userGuideSections.md @@ -0,0 +1,8 @@ +## Sections +- Quick Start +- Command: include and render +- Content Authoring +- Developing a Site +- Github Pages Deploment +- Including Contents +- Site Configuration diff --git a/docs/developerGuide.md b/docs/developerGuide.md new file mode 100644 index 0000000000..6ca961b3fa --- /dev/null +++ b/docs/developerGuide.md @@ -0,0 +1,154 @@ + + + + +
    + +## 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). + +## 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 [] +``` + +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. + +
    diff --git a/docs/index.md b/docs/index.md index e2a5b99587..733b6e021e 100644 --- a/docs/index.md +++ b/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: - +
     
    @@ -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. - + 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_. Primitive data types on the other hand ... @@ -57,7 +57,7 @@ In CS, a binary tree is a [source:wikipedia]%%   - +   @@ -69,7 +69,7 @@ In CS, a binary tree is a +    
    @@ -85,7 +85,7 @@ _itatic text_    → 
    - + **bold text**
    _itatic text_
    @@ -103,7 +103,7 @@ _itatic text_
    In the example below, there is a expandable panel that can reveal more content. - + 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. - + - + - + Details of exercise 1 - + Details of exercise 2 - + Details of exercise 3 @@ -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. - + 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_. Primitive data types on the other hand ... @@ -158,23 +158,24 @@ In CS, a binary tree is a tree data structure in which each node has at most two ## 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) -## Documentation +## Documentation #### For Users -* [Quick Start](https://github.com/MarkBind/markbind-cli/wiki/User-Quick-Start) +* [Quick Start]({{baseUrl}}/sections/userQuickStart.html) +* [User Guide]({{baseUrl}}/userGuide.html) #### For Developers -* [Developer Guide](https://github.com/MarkBind/markbind-cli/wiki/Developer-Guide) +* [Developer Guide]({{baseUrl}}/developerGuide.html) ## About us diff --git a/docs/sections/contentAuthoring.md b/docs/sections/contentAuthoring.md new file mode 100644 index 0000000000..9e20381040 --- /dev/null +++ b/docs/sections/contentAuthoring.md @@ -0,0 +1,92 @@ + + + + +
    + +# 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]({{baseUrl}}/sections/includingContents.html). + + + +
    diff --git a/docs/sections/developingASite.md b/docs/sections/developingASite.md new file mode 100644 index 0000000000..507d52514f --- /dev/null +++ b/docs/sections/developingASite.md @@ -0,0 +1,83 @@ + + + + +
    + +# 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]({{baseUrl}}/sections/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]({{baseUrl}}/sections/ghpagesDeployment.html) for more details. | + + + +
    diff --git a/docs/sections/ghpagesDeployment.md b/docs/sections/ghpagesDeployment.md new file mode 100644 index 0000000000..48d6830d78 --- /dev/null +++ b/docs/sections/ghpagesDeployment.md @@ -0,0 +1,62 @@ + + + + +
    + +# 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') + + + +
    diff --git a/docs/sections/includeAndRender.md b/docs/sections/includeAndRender.md new file mode 100644 index 0000000000..7a31e3a584 --- /dev/null +++ b/docs/sections/includeAndRender.md @@ -0,0 +1,65 @@ + + + + +
    + +# 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? +
    + +Joff-tchoff-tchoffo-tchoffo-tchoff! +Tchoff-tchoff-tchoffo-tchoffo-tchoff! +Joff-tchoff-tchoffo-tchoffo-tchoff! + +
    +``` +(**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`. + + + +
    diff --git a/docs/sections/includingContents.md b/docs/sections/includingContents.md new file mode 100644 index 0000000000..db3aae2dcb --- /dev/null +++ b/docs/sections/includingContents.md @@ -0,0 +1,69 @@ + + + + +
    + +# 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, ) + ``` + + + +
    diff --git a/docs/sections/siteConfiguration.md b/docs/sections/siteConfiguration.md new file mode 100644 index 0000000000..5790b17814 --- /dev/null +++ b/docs/sections/siteConfiguration.md @@ -0,0 +1,41 @@ + + + + +
    + +# 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]({{baseUrl}}/sections/ghpagesDeployment.html) for more details. | + + + +
    diff --git a/docs/sections/userQuickStart.md b/docs/sections/userQuickStart.md new file mode 100644 index 0000000000..3242221eec --- /dev/null +++ b/docs/sections/userQuickStart.md @@ -0,0 +1,131 @@ + + + + +
    + +# User Quick Start + +## Requirement +We expect users to have basic knowledge of the following: +- [x] Markdown +- [x] HTML & CSS +- [x] npm (Node.js) +- [x] Command-line Environment + +## Installation +`MarkBind` can be installed using npm + +`v1.4.3`: and above: Node.js with version 8.0 and higher is required. +`v1.4.2`: We recommend users to use Node.js with version 6.5 or higher. + +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. + +``` +__ __ _ ____ _ _ +| \/ | __ _ _ __ | | __ | __ ) (_) _ __ __| | +| |\/| | / _` | | '__| | |/ / | _ \ | | | '_ \ / _` | +| | | | | (_| | | | | < | |_) | | | | | | | | (_| | +|_| |_| \__,_| |_| |_|\_\ |____/ |_| |_| |_| \__,_| + + +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. + +## Start Site Development +### Create a new 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` 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]({{baseUrl}}/sections/siteConfiguration.html) for more details about how you can configure the `site.json`. + +### Authoring your contents. +Read more about content authoring [here]({{baseUrl}}/sections/contentAuthoring.html). + +### Preview and serve your site using: +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. + +There are also two useful commands, [*include* and *render*]({{baseUrl}}/sections/includeAndRender.html) that could help you handle ad-hoc including/rendering work. You may also use it for debug purpose as well. . + +More details of deployment setting could be found in [here]({{baseUrl}}/sections/ghpagesDeployment.html). + + + +
    diff --git a/docs/site.json b/docs/site.json index 220311d98b..0528ff208a 100644 --- a/docs/site.json +++ b/docs/site.json @@ -4,6 +4,42 @@ { "src": "index.md", "title": "MarkBind: Generate Course Websites from Markdown Text" + }, + { + "src": "userGuide.md", + "title": "MarkBind: User Guide" + }, + { + "src": "developerGuide.md", + "title": "MarkBind: Developer Guide" + }, + { + "src": "sections/userQuickStart.md", + "title": "MarkBind: User Guide - Quick Start" + }, + { + "src": "sections/includeAndRender.md", + "title": "MarkBind: User Guide - Include and Render" + }, + { + "src": "sections/contentAuthoring.md", + "title": "MarkBind: User Guide - Content Authoring" + }, + { + "src": "sections/developingASite.md", + "title": "MarkBind: User Guide - Developing a Site" + }, + { + "src": "sections/ghpagesDeployment.md", + "title": "MarkBind: User Guide - Github Pages Deploment" + }, + { + "src": "sections/includingContents.md", + "title": "MarkBind: User Guide - Including Contents" + }, + { + "src": "sections/siteConfiguration.md", + "title": "MarkBind: User Guide - Site Configuration" } ], "ignore": [ diff --git a/docs/userGuide.md b/docs/userGuide.md new file mode 100644 index 0000000000..2a31e9fda2 --- /dev/null +++ b/docs/userGuide.md @@ -0,0 +1,16 @@ + + + + +
    + +# 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]({{baseUrl}}/sections/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. + + +
    From e4f39e17b8f20ca258a85525199d75a06b53e269 Mon Sep 17 00:00:00 2001 From: nicholaschuayunzhi Date: Sat, 31 Mar 2018 16:30:37 +0800 Subject: [PATCH 3/7] Edit user quick start based on suggestions --- docs/sections/userQuickStart.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/sections/userQuickStart.md b/docs/sections/userQuickStart.md index 3242221eec..90d0a871a0 100644 --- a/docs/sections/userQuickStart.md +++ b/docs/sections/userQuickStart.md @@ -9,15 +9,10 @@ ## Requirement We expect users to have basic knowledge of the following: - [x] Markdown -- [x] HTML & CSS -- [x] npm (Node.js) - [x] Command-line Environment ## Installation -`MarkBind` can be installed using npm - -`v1.4.3`: and above: Node.js with version 8.0 and higher is required. -`v1.4.2`: We recommend users to use Node.js with version 6.5 or higher. +`MarkBind` can be [installed using npm](https://www.npmjs.com/get-npm). You can run: ``` @@ -29,10 +24,10 @@ After installation, you can run ``` $ markbind ``` -to ensure `MarkBind` is successfully installed on your system. +to ensure `MarkBind` is successfully installed on your system. You should see: ``` -__ __ _ ____ _ _ + __ __ _ ____ _ _ | \/ | __ _ _ __ | | __ | __ ) (_) _ __ __| | | |\/| | / _` | | '__| | |/ / | _ \ | | | '_ \ / _` | | | | | | (_| | | | | < | |_) | | | | | | | | (_| | @@ -60,8 +55,8 @@ Commands: You can add the help flag (`--help`) to any command to show the help screen. -## Start Site Development -### Create a new site with MarkBind +## Using MarkBind to author a Website +### Create a new site MarkBind can setup a boilerplate site in the current directory: ``` @@ -74,11 +69,11 @@ After running `init`, two files will be created for you: `index.md` and `site.js You may refer to this [doc]({{baseUrl}}/sections/siteConfiguration.html) for more details about how you can configure the `site.json`. -### Authoring your contents. +### Authoring your contents Read more about content authoring [here]({{baseUrl}}/sections/contentAuthoring.html). -### Preview and serve your site using: -After authoring your contents, you can run +### Preview your site +After authoring your contents, you can run: ``` $ markbind serve @@ -91,7 +86,7 @@ MarkBind will generate the site in a folder named `_site` in the current directo 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. | @@ -106,7 +101,7 @@ $ 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 +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 @@ -122,8 +117,6 @@ $ 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. -There are also two useful commands, [*include* and *render*]({{baseUrl}}/sections/includeAndRender.html) that could help you handle ad-hoc including/rendering work. You may also use it for debug purpose as well. . - More details of deployment setting could be found in [here]({{baseUrl}}/sections/ghpagesDeployment.html). From 5aa9bbf8e2ff3133af292be09301d433020fdcdc Mon Sep 17 00:00:00 2001 From: nicholaschuayunzhi Date: Sat, 31 Mar 2018 16:37:34 +0800 Subject: [PATCH 4/7] Group user guide content in the same folder --- docs/common/userGuideSections.md | 14 +++++++------- docs/index.md | 4 ++-- docs/site.json | 16 ++++++++-------- docs/{sections => userGuide}/contentAuthoring.md | 2 +- docs/{sections => userGuide}/developingASite.md | 4 ++-- .../{sections => userGuide}/ghpagesDeployment.md | 0 docs/{sections => userGuide}/includeAndRender.md | 0 .../{sections => userGuide}/includingContents.md | 0 docs/{userGuide.md => userGuide/index.md} | 7 ++++--- .../{sections => userGuide}/siteConfiguration.md | 2 +- docs/{sections => userGuide}/userQuickStart.md | 6 +++--- 11 files changed, 28 insertions(+), 27 deletions(-) rename docs/{sections => userGuide}/contentAuthoring.md (93%) rename docs/{sections => userGuide}/developingASite.md (93%) rename docs/{sections => userGuide}/ghpagesDeployment.md (100%) rename docs/{sections => userGuide}/includeAndRender.md (100%) rename docs/{sections => userGuide}/includingContents.md (100%) rename docs/{userGuide.md => userGuide/index.md} (59%) rename docs/{sections => userGuide}/siteConfiguration.md (93%) rename docs/{sections => userGuide}/userQuickStart.md (88%) diff --git a/docs/common/userGuideSections.md b/docs/common/userGuideSections.md index a0f4065277..b714edd4bb 100644 --- a/docs/common/userGuideSections.md +++ b/docs/common/userGuideSections.md @@ -1,8 +1,8 @@ ## Sections -- Quick Start -- Command: include and render -- Content Authoring -- Developing a Site -- Github Pages Deploment -- Including Contents -- Site Configuration +- Quick Start +- Command: include and render +- Content Authoring +- Developing a Site +- Github Pages Deploment +- Including Contents +- Site Configuration diff --git a/docs/index.md b/docs/index.md index 733b6e021e..3909a2ccac 100644 --- a/docs/index.md +++ b/docs/index.md @@ -169,8 +169,8 @@ Examples of websites built using MarkBind: #### 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 diff --git a/docs/site.json b/docs/site.json index 0528ff208a..6e25f552d4 100644 --- a/docs/site.json +++ b/docs/site.json @@ -6,7 +6,7 @@ "title": "MarkBind: Generate Course Websites from Markdown Text" }, { - "src": "userGuide.md", + "src": "userGuide/index.md", "title": "MarkBind: User Guide" }, { @@ -14,31 +14,31 @@ "title": "MarkBind: Developer Guide" }, { - "src": "sections/userQuickStart.md", + "src": "userGuide/userQuickStart.md", "title": "MarkBind: User Guide - Quick Start" }, { - "src": "sections/includeAndRender.md", + "src": "userGuide/includeAndRender.md", "title": "MarkBind: User Guide - Include and Render" }, { - "src": "sections/contentAuthoring.md", + "src": "userGuide/contentAuthoring.md", "title": "MarkBind: User Guide - Content Authoring" }, { - "src": "sections/developingASite.md", + "src": "userGuide/developingASite.md", "title": "MarkBind: User Guide - Developing a Site" }, { - "src": "sections/ghpagesDeployment.md", + "src": "userGuide/ghpagesDeployment.md", "title": "MarkBind: User Guide - Github Pages Deploment" }, { - "src": "sections/includingContents.md", + "src": "userGuide/includingContents.md", "title": "MarkBind: User Guide - Including Contents" }, { - "src": "sections/siteConfiguration.md", + "src": "userGuide/siteConfiguration.md", "title": "MarkBind: User Guide - Site Configuration" } ], diff --git a/docs/sections/contentAuthoring.md b/docs/userGuide/contentAuthoring.md similarity index 93% rename from docs/sections/contentAuthoring.md rename to docs/userGuide/contentAuthoring.md index 9e20381040..d2a9def0ba 100644 --- a/docs/sections/contentAuthoring.md +++ b/docs/userGuide/contentAuthoring.md @@ -85,7 +85,7 @@ For a list of supported components, refer to the component [doc](https://markbin 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]({{baseUrl}}/sections/includingContents.html). +For detailed guide on using `` tag for including contents, read the doc [here](includingContents.html). diff --git a/docs/sections/developingASite.md b/docs/userGuide/developingASite.md similarity index 93% rename from docs/sections/developingASite.md rename to docs/userGuide/developingASite.md index 507d52514f..f831abb689 100644 --- a/docs/sections/developingASite.md +++ b/docs/userGuide/developingASite.md @@ -48,7 +48,7 @@ $ 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]({{baseUrl}}/sections/ghpagesDeployment.html). +Please check more details of deployment [here](ghpagesDeployment.html). ### site.json Let's take a look at this newly created `site.json`: @@ -76,7 +76,7 @@ Let's take a look at this newly created `site.json`: | **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]({{baseUrl}}/sections/ghpagesDeployment.html) for more details. | +| **deploy** | Settings for the Github page deployment. Please refer to this [doc](ghpagesDeployment.html) for more details. | diff --git a/docs/sections/ghpagesDeployment.md b/docs/userGuide/ghpagesDeployment.md similarity index 100% rename from docs/sections/ghpagesDeployment.md rename to docs/userGuide/ghpagesDeployment.md diff --git a/docs/sections/includeAndRender.md b/docs/userGuide/includeAndRender.md similarity index 100% rename from docs/sections/includeAndRender.md rename to docs/userGuide/includeAndRender.md diff --git a/docs/sections/includingContents.md b/docs/userGuide/includingContents.md similarity index 100% rename from docs/sections/includingContents.md rename to docs/userGuide/includingContents.md diff --git a/docs/userGuide.md b/docs/userGuide/index.md similarity index 59% rename from docs/userGuide.md rename to docs/userGuide/index.md index 2a31e9fda2..5208acf73a 100644 --- a/docs/userGuide.md +++ b/docs/userGuide/index.md @@ -1,6 +1,6 @@ - +
    @@ -10,7 +10,8 @@ MarkBind enhances markdown and html documents with extra features that allow you 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]({{baseUrl}}/sections/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. +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. - +
    + diff --git a/docs/sections/siteConfiguration.md b/docs/userGuide/siteConfiguration.md similarity index 93% rename from docs/sections/siteConfiguration.md rename to docs/userGuide/siteConfiguration.md index 5790b17814..7bb0935f7a 100644 --- a/docs/sections/siteConfiguration.md +++ b/docs/userGuide/siteConfiguration.md @@ -34,7 +34,7 @@ Let's examine a typical `site.json` file: | **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]({{baseUrl}}/sections/ghpagesDeployment.html) for more details. | +| **deploy** | Settings for the auto Github page deployment. Please refer this [doc](ghpagesDeployment.html) for more details. | diff --git a/docs/sections/userQuickStart.md b/docs/userGuide/userQuickStart.md similarity index 88% rename from docs/sections/userQuickStart.md rename to docs/userGuide/userQuickStart.md index 90d0a871a0..220eaf9dd4 100644 --- a/docs/sections/userQuickStart.md +++ b/docs/userGuide/userQuickStart.md @@ -67,10 +67,10 @@ If you wish to create the site into a new directory, you can do so by running `m 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]({{baseUrl}}/sections/siteConfiguration.html) for more details about how you can configure the `site.json`. +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]({{baseUrl}}/sections/contentAuthoring.html). +Read more about content authoring [here](contentAuthoring.html). ### Preview your site After authoring your contents, you can run: @@ -117,7 +117,7 @@ $ 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]({{baseUrl}}/sections/ghpagesDeployment.html). +More details of deployment setting could be found in [here](ghpagesDeployment.html). From 8afda30947c6a712ba21ae8716170bb059d1aedf Mon Sep 17 00:00:00 2001 From: nicholaschuayunzhi Date: Sat, 31 Mar 2018 16:39:50 +0800 Subject: [PATCH 5/7] fixup --- docs/common/header.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/common/header.md b/docs/common/header.md index d24b8dd928..d208324c7f 100644 --- a/docs/common/header.md +++ b/docs/common/header.md @@ -1,14 +1,14 @@ -
  • Home
    • -
  • Quick Start
    • -
  • Command: include and render
    • -
  • Content Authoring
    • -
  • Developing a Site
    • -
  • Github Pages Deploment
    • -
  • Including Contents
    • -
  • Site Configuration
    • +
  • Home
    • +
  • Quick Start
    • +
  • Command: include and render
    • +
  • Content Authoring
    • +
  • Developing a Site
    • +
  • Github Pages Deploment
    • +
  • Including Contents
    • +
  • Site Configuration
    •
  • Developer Guide
    • From bc43b022f333f90f8bbdf4e04ad4578f6544918b Mon Sep 17 00:00:00 2001 From: nicholaschuayunzhi Date: Sat, 31 Mar 2018 17:45:25 +0800 Subject: [PATCH 6/7] Split dev guide into smaller sections --- docs/common/devGuideSections.md | 4 + docs/common/header.md | 8 +- .../index.md} | 82 +------------------ docs/developerGuide/publishing.md | 29 +++++++ docs/developerGuide/settingUp.md | 31 +++++++ docs/developerGuide/testing.md | 76 +++++++++++++++++ docs/index.md | 2 +- docs/site.json | 20 ++++- 8 files changed, 167 insertions(+), 85 deletions(-) create mode 100644 docs/common/devGuideSections.md rename docs/{developerGuide.md => developerGuide/index.md} (58%) create mode 100644 docs/developerGuide/publishing.md create mode 100644 docs/developerGuide/settingUp.md create mode 100644 docs/developerGuide/testing.md diff --git a/docs/common/devGuideSections.md b/docs/common/devGuideSections.md new file mode 100644 index 0000000000..2cd48a26f5 --- /dev/null +++ b/docs/common/devGuideSections.md @@ -0,0 +1,4 @@ +## Sections +- Setting up for Development +- Testing +- Publishing to npm diff --git a/docs/common/header.md b/docs/common/header.md index d208324c7f..6a02174d03 100644 --- a/docs/common/header.md +++ b/docs/common/header.md @@ -6,10 +6,14 @@
  • Command: include and render
  • Content Authoring
  • Developing a Site
    • -
  • Github Pages Deploment
    • +
  • Github Pages Deployment
  • Including Contents
  • Site Configuration
    • -
  • Developer Guide
    • + +
  • Home
    • +
  • Setting up for Development
    • +
  • Testing
    • +
  • Publishing to npm
    •      diff --git a/docs/developerGuide.md b/docs/developerGuide/index.md similarity index 58% rename from docs/developerGuide.md rename to docs/developerGuide/index.md index 6ca961b3fa..510b02ec6f 100644 --- a/docs/developerGuide.md +++ b/docs/developerGuide/index.md @@ -1,9 +1,11 @@ - +
    +# Developer Guide + ## Requirement We expect contributors for *MarkBind* have the following knowledges: @@ -73,82 +75,6 @@ The VueStrap library is [Bootstrap](getbootstrap.com/components/) components rew 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 [] -``` - -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. +
    diff --git a/docs/developerGuide/publishing.md b/docs/developerGuide/publishing.md new file mode 100644 index 0000000000..2309f1b497 --- /dev/null +++ b/docs/developerGuide/publishing.md @@ -0,0 +1,29 @@ + + + + +
    + +# 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. + + + +
    diff --git a/docs/developerGuide/settingUp.md b/docs/developerGuide/settingUp.md new file mode 100644 index 0000000000..79fdb8934d --- /dev/null +++ b/docs/developerGuide/settingUp.md @@ -0,0 +1,31 @@ + + + + +
    + +# 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. + + + +
    diff --git a/docs/developerGuide/testing.md b/docs/developerGuide/testing.md new file mode 100644 index 0000000000..756b0cf852 --- /dev/null +++ b/docs/developerGuide/testing.md @@ -0,0 +1,76 @@ + + + + +
    + +# 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 3909a2ccac..e7efbb967c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -175,7 +175,7 @@ Examples of websites built using MarkBind: #### For Developers -* [Developer Guide]({{baseUrl}}/developerGuide.html) +* [Developer Guide](./developerGuide/index.html) ## About us diff --git a/docs/site.json b/docs/site.json index 6e25f552d4..3342c0c7b7 100644 --- a/docs/site.json +++ b/docs/site.json @@ -9,10 +9,6 @@ "src": "userGuide/index.md", "title": "MarkBind: User Guide" }, - { - "src": "developerGuide.md", - "title": "MarkBind: Developer Guide" - }, { "src": "userGuide/userQuickStart.md", "title": "MarkBind: User Guide - Quick Start" @@ -40,6 +36,22 @@ { "src": "userGuide/siteConfiguration.md", "title": "MarkBind: User Guide - Site Configuration" + }, + { + "src": "developerGuide/index.md", + "title": "MarkBind: Developer Guide" + }, + { + "src": "developerGuide/publishing.md", + "title": "MarkBind: Developer Guide - Publishing to npm" + }, + { + "src": "developerGuide/settingUp.md", + "title": "MarkBind: Developer Guide - Setting up for Development" + }, + { + "src": "developerGuide/testing.md", + "title": "MarkBind: Developer Guide - Testing" } ], "ignore": [ From 2070ee376d48f502c6010a7fb66a7623450ed399 Mon Sep 17 00:00:00 2001 From: nicholaschuayunzhi Date: Sat, 31 Mar 2018 17:47:20 +0800 Subject: [PATCH 7/7] Migrate include and render to dev guide --- docs/common/devGuideSections.md | 2 ++ docs/common/header.md | 2 +- docs/common/userGuideSections.md | 1 - docs/{userGuide => developerGuide}/includeAndRender.md | 0 docs/site.json | 8 ++++---- 5 files changed, 7 insertions(+), 6 deletions(-) rename docs/{userGuide => developerGuide}/includeAndRender.md (100%) diff --git a/docs/common/devGuideSections.md b/docs/common/devGuideSections.md index 2cd48a26f5..d746227e0f 100644 --- a/docs/common/devGuideSections.md +++ b/docs/common/devGuideSections.md @@ -1,4 +1,6 @@ ## Sections - Setting up for Development +- Command: include and render - Testing - Publishing to npm + diff --git a/docs/common/header.md b/docs/common/header.md index 6a02174d03..56dd56313a 100644 --- a/docs/common/header.md +++ b/docs/common/header.md @@ -3,7 +3,6 @@
  • Home
  • Quick Start
    • -
  • Command: include and render
  • Content Authoring
  • Developing a Site
  • Github Pages Deployment
    • @@ -13,6 +12,7 @@
  • Home
  • Setting up for Development
    • +
  • Command: include and render
  • Testing
  • Publishing to npm
    •  diff --git a/docs/common/userGuideSections.md b/docs/common/userGuideSections.md index b714edd4bb..f9354bb6e2 100644 --- a/docs/common/userGuideSections.md +++ b/docs/common/userGuideSections.md @@ -1,6 +1,5 @@ ## Sections - Quick Start -- Command: include and render - Content Authoring - Developing a Site - Github Pages Deploment diff --git a/docs/userGuide/includeAndRender.md b/docs/developerGuide/includeAndRender.md similarity index 100% rename from docs/userGuide/includeAndRender.md rename to docs/developerGuide/includeAndRender.md diff --git a/docs/site.json b/docs/site.json index 3342c0c7b7..d797e92f2d 100644 --- a/docs/site.json +++ b/docs/site.json @@ -13,10 +13,6 @@ "src": "userGuide/userQuickStart.md", "title": "MarkBind: User Guide - Quick Start" }, - { - "src": "userGuide/includeAndRender.md", - "title": "MarkBind: User Guide - Include and Render" - }, { "src": "userGuide/contentAuthoring.md", "title": "MarkBind: User Guide - Content Authoring" @@ -41,6 +37,10 @@ "src": "developerGuide/index.md", "title": "MarkBind: Developer Guide" }, + { + "src": "developerGuide/includeAndRender.md", + "title": "MarkBind: User Guide - Include and Render" + }, { "src": "developerGuide/publishing.md", "title": "MarkBind: Developer Guide - Publishing to npm"