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 parentoption- 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:
.erbas 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
- Fork it
- Create your feature/bug fix branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
More about the project
Contributors
Open source licensing info
Credits and references
- Hologram
- Base theme css: hologram-github-template
- Syntax: highlight.js using
github-gisttheme