Holograph NPM | npm.io

Holograph (alpha)

Holograph is a NPM module that parses comments in your CSS and turns them into a beautiful style guide. It is initially a port of the excellent work done by the Hologram Ruby gem and aims to be compatible with most of its features.

In addition to features found in Hologram, Holograph includes:

a responsive version of the Hologram GitHub Template with some minor alterations to content styles
support for displaying multiple colour palettes

Installation

Install the latest release from npm with:

npm install holograph

Using the --save or --save-dev flag will add the dependency to your project's package.json.

Configuration

Settings for your Holograph instance are found in holograph_config.yml and use YAML syntax. To begin, copy the template configuration file into your project root with:

cp node_modules/holograph/holograph_config.yml .

Settings in this file include the relative location of dependencies (for your project and for Holograph), the destination path, and a title for your style guide.

For more complete documentation, see how to configure Holograph.

Usage

The binary takes no parameters and just reads all options from the config file

node_modules/.bin/holograph

The default build location is ./holograph/. You can configure this by setting the destination value in holograph_config.yml.

Documenting your styles

Holograph will scan for stylesheets (.css, .scss, .sass, .less, .styl) within the source directory defined in your configuration. It will find Holograph comments and generate style guide sections from your comment's settings and content.

Sample comment:

/*doc
---
title: Headings
name: headings
category: typography
---

Headings should follow appropriate heading hierarchy.

```html_example
    <h1>Hello, world!</h1>
```
*/

For more complete documentation, see how to document your components.

Colour palettes

Holograph allows creation of colour palettes from your proprocessor stylesheets (.css, .scss, .sass, .less, .styl). This feature is new for Holograph and is not found in Ruby Hologram.

In brief, to mark colour variables to include in Holograph, use the following comment syntax:

$variable-name: <value>;    // hg-palette: Palette name

For more complete documentation, see how to use colour palettes.

How to test the software

Tests are being written with Mocha and the Chai assertion library

npm test

Known issues

Incomplete features

content and configuration for index.html
parent option
support for JavaScript content
referencing other components

Unsupported features

colour values in palettes that require compilation, such as darken($brand-primary, 10%) and nested colour variables
Ruby-specific: .erb as a source and 'slim' for templates