@ithaka/bonsai v1.19.6

Bonsai

ITHAKA core styling and JavaScript functionality

Installation

$ npm install @ithaka/bonsai

Development

System Dependencies

This project requires Node.js and npm to be installed prior to development work.

Package Dependencies

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

$ npm install

Building the package

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

$ npm run build

To watch for changes:

$ npm run watch

To start a local development server with hot reloading:

$ npm run start  # or simply "npm start"

Testing

To run tests:

$ npm run test  # or simply "npm test"

Style Guide

The Bonsai Style Guide is dynamically generated using the 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 and git installed on your machine.

$ 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

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

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

---
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:

```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

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

routes.js after

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?

1. Webpack is run, processing all the files defined in the entry object in webpack.config.js
2. Once all the files are processed, the WebpackShellPlugin runs node generate-docs.js
3. generate-docs.js contains the SuperCollider configuration and initialization.
4. 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
5. 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/