@ithaka/bonsai/README.md

# Bonsai
_ITHAKA core styling and JavaScript functionality_

## Installation

```shell
$ npm install @ithaka/bonsai
```

## Development

### System Dependencies

This project requires [Node.js](https://nodejs.org) and [npm](https://npmjs.com) to be installed prior to development work.

### Package Dependencies

Installing all necessary dependencies for building the package should be as simple as:

```shell
$ npm install
```

### Building the package

Once you've installed all the dependencies, building the package can be accomplished with:

```shell
$ npm run build
```

To watch for changes:

```shell
$ npm run watch
```

To start a local development server with hot reloading:

```shell
$ npm run start  # or simply "npm start"
```

### Testing

To run tests:

```shell
$ npm run test  # or simply "npm test"
```

## Style Guide

The Bonsai Style Guide is dynamically generated using the [zurb/supercollider](http://www.github.com/zurb/supercollider)
library.

To contribute to the Bonsai documentation and style guide, you will want to run it locally.

### Running Locally

You'll need [`node`](https://nodejs.org/en/) and `git` installed on your machine.

```bash
$ git clone https://github.com/ithaka/bonsai.git
$ cd bonsai
$ npm install # this could take a few minutes
$ npm run start
```

`$ npm run start` will launch the development server on http://localhost:8080. Navigate there and you will be
redirected to the index of the style guide

Any time a file change is saved the documentation will recompile. Refresh the page to see your change.

### Making a new page in the style guide

_You might want to write the documentation in Markdown_

[Learn Markdown](https://daringfireball.net/projects/markdown/syntax)

[Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)

Let's say that JSTOR is going to create a new feature giving esteemed researchers a plethora of new tools for their study of cats.
Suddenly the style guide needs a page about cats! Here's how you'd make it.

Create a markdown file (`cats.md`) in `documentation/pages/`. At the very minimum it needs a title, description, and content.

_`documentation/pages/cats.md`_


```markdown

---
title: Cats Cats Cats!
description: Guidelines for the JSTOR Cats feature set
---

<!-- here down can be a mix of HTML and Markdown -->

![](kitten.jpeg)

<div class="cat-container">
    <p class="cat">CAT</p>
</div>
```

The bulk of the content for each page can be markdown, html, or a mix of the two


If you want to dynamically include the sass or js documentation for the cats component, simply add it in the header of
the markdown file. Both `sass` and `js` are optional.

```markdown

---
title: Cats Cats Cats!
description: Guidelines for the JSTOR Cats feature set
sass: ./scss/_cats.scss
js: ./js/bonsai.cats.js
---

```

Additionally, supercollider allows the creation custom adapters if types of documentation other than html, sass, and js
need to be dynamically generated.


#### HTML Examples

When documenting how to use a component, you may want to include example code. Giving the markdown block
the language level of `html_example` will insert the rendered html directly after the markdown example.

For example this:

`````markdown
```html_example
<button>I am button</button>
```
`````

will display the literal code, plus the rendered button afterwards.

#### Routing

After making the markdown file, but probably before you put all your content in there, you should add it to the routes.
Go to `documentation/routes/js`, and add a line in the array that has the name of your markdown file.

_`routes.js`_ before

```javascript
module.exports = [
  "button",
  "modal"
]
```

_`routes.js`_ after

```javascript
module.exports = [
  "button",
  "modal",
  "cats"
]
```

By adding "cats" to this array, we enable hot reloading for the `cats.md` file as well as add an option for "Cats" in the
navigation of the style guide

## The Style Guide Build System

* webpack
  * webpack-shell-plugin
  * raw-loader
* supercollider
  * foundation-docs custom markdown interpreter
* handlebars

### What happens when running `npm run start`?

![](https://i.imgflip.com/1tlvet.jpg)

1. Webpack is run, processing all the files defined in the entry object in `webpack.config.js`
1. Once all the files are processed, the `WebpackShellPlugin` runs `node generate-docs.js`
1. `generate-docs.js` contains the SuperCollider configuration and initialization.
1. SuperCollider generates the html by taking all the markdown templates, running them through the markdown interpreter,
    getting the sassDocs and jsDocs associated with each markdown file, and running them all through the primary
    handlebars template. This is then all output as raw html to `documentation/styleguide/`. These settings are all in
    the `generate-docs.js` file
1. A development server is launched at localhost:8080

The development server is now watching the sass, javascript, markdown, and main template for changes.
It does this because all these files are run through webpack (even though they're not all compiled)

In `js/index.js` the main handlebar template is imported, as well as an array of all the names of the
individual components that are a part of the style guide. Iterating through the array, every markdown file
is also imported into the `js/index.js`.

We don't tell webpack what to do with these files, but we do **have** to give webpack a loader for `.html` and `.md`
files. There are rules setup to run html and md through the `raw-loader`. Now webpack is aware of everything,
and anytime something it's aware of changes it runs through the above steps again, minus launching a duplicate server.

### Publishing to NPM

Everything that gets merged into the `develop` branch will become a `beta` release

Everything that gets merged into the `master` branch will become a `latest` release.

Please note that each pull request that is being merged into either of these branches need to have an updated version
in the `package.json` file so that the `npm publish` can succeed.

Jenkins jobs that automate these releases exist here:
http://jenkins.test.cirrostratus.org:8080/job/build-bonsai-develop/
http://jenkins.test.cirrostratus.org:8080/job/build-bonsai-master/