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

Getting help

If you have questions, concerns, bug reports, etc, please file an issue in this repository's issue tracker.

Getting involved

1. Fork it
2. Create your feature/bug fix branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

More about the project

Contributors

• Ben Longden
• Laura Kishimoto

Open source licensing info

• Terms
• License
• CFPB Source Code Policy

Credits and references

• Hologram
• Base theme css: hologram-github-template
• Syntax: highlight.js using github-gist theme