UltraCollider

UltraCollider is a style guide or pattern library generator with a single source of truth about each component. Just make a markdown file for every component that you want documented. UltraCollider will then pull in SassDoc and JSDoc from the component source code, compiling everything into html.

UltraCollider is run with Node.js, and can hook into any build system that can execute a javascript file.

Inspired by Supercollider from Zurb

Contents

• Installation
• The Basics
• Initialization
• Configuration

Installation

$ npm install ultracollider

The Basics

Create a directory of markdown files. Think of these as your single source of truth about the components you're documenting. Every markdown file will be compiled into an html file. There shouldn't be anything else in this directory.

One Markdown File per Component

---
title: Buttons
description: This is how you use a button
sass: ./scss/_buttons.scss
---

## Example

```
<button class="button">My Button</button>
```

<img src="./img/good-job.jpg" />

Everything between the ---'s at the top of the file gets turned into a key / value pair to be passed into your handlebars template, with the exception of sass and js behaving a bit differently.

sass and js take a path to the sass or javascript file(s) that power the actual component, in order to process the SassDoc and JSDoc.

Inside your handlebar template, you can access the SassDoc and JSDoc with simply sass and js.

Any other arguments placed in the header are passed along 1:1 to the template.

Everything below the header is parsed into html and assigned the key docs

Template file

Your Handlebar template can be as simple or as complex as you like. UltraCollider has no opinions about this.

<h1>{{title}}</h1>
<p>{{description}}</p>

{{{docs}}} <!-- triple braces to not escape the html -->

Initialization

A bare bones configuration would look like this:

generate-docs.js

const UltraCollider = require("ultracollider");

const config = {
  files: "./path/to/md/files/",
  output: "./output/my/files/here/", // NOTE: this directory is deleted and recreated at runtime. Don't place files you need in here
  template: "./template.html"
};

new UltraCollider(config).run();

then simply run the file with $ node generate-docs.js

Configuration

The configuration can take these parameters.

Note: the output directory and its contents are deleted at runtime. Do not store files here.

| key | type | required? | description | | ------------ | ------------------- | -------------- | -------------- | | files | string | required | a path to a directory of markdown files to generate docs from | | output | string | required | a path to a directory where the generated html will output to | | template | string | required | a path to a handlebars template used to create the style guide | | handlebars | Handlebars Instance | optional | custom handlebars instance to be used to generate the docs with | | marked | Marked Renderer | optional | custom marked renderer used to parse the markdown | | data | object | optional | additional data to make available in the handlebar template |

Testing

$ npm test