@ithaka/bonsai

# 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 ---  ![](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/