Node Hologram

Inspired by Hologram.

Allows for the easy generation of styleguides from markdown documentation.

Usage

Ensuring you have a version of node >= 4 installed.

npm install --save-dev node-hologram

Then require in your script file:

const hologram = require('node-hologram')(options);
hologram.init();

Hologram will then scan the directories specified in the options parameter, accessing any file ending in the correct file extension (see options ext). If the file's first comment is suffixed with the word doc hologram will then take the contents of this comment and attempt to convert it to markdown which will then be used to create a styleguide.

Example Doc

/*doc
---
colors: {red: '#f00'}
order: 1
---

## Example

_I am some markdown_

Docs for the example component.

Put example html inside the <example> tag. This will be extracted and
placed in an iframe.

`` `
<h2>Code snippet inside the doc</h2>
`` `

<example>
    <h2>I will be rendered as HTML</h2>
</example>


*/

Components in Docs

Example components can be placed inside the markdown docs. They should be placed inside an <example> tag, like so:

<example>
    <h2>I will be extracted and placed in an iframe.</h2>
</example>

The content inside the example tag will be extracted and placed in it's own html page. It will then be iframed into the styleguide. The reason for this is to prevent styleguide specific styles from affecting the example content.

NB:

• If the word doc is not present in the first line of the comment that file will be ignored.
• Only the first correctly formatted comment will be used. Eg: One doc per file.
• Only the first <example> of each doc will be extracted, Eg: One example per file.

Meta Data

The below node-hologram features can be set using markdown meta data.

order

The order option allows you to specify the index of an item in the styleguide. The order starts at 1. So an item given an order of 1 will appear as the first item in the styleguide.

---
order: 1
---

colors

As well as being defined in the options object the styleguide's colors pallette can also be created via markdown. Colors should be defined in the markdown as per the example below.

---
colors: {red: '#f00'}
---

Options

root required

The root of your project. All paths provided should be relevant to this. By default you should pass in __dirname, unless in a specific circumstance.

root: __dirname

dest required

The path to the folder where the styleguide generated by Hologram will be placed.

dest: '/path/to/dest'

styles required

Information on which folders your stylesheets are contained in (dir). The specified directories will be recursively searched for files with the correct extension (scss by default, can be changed using ext option), as well the paths to your app's stylesheets (files).

styles: {
    dir: ['/path/to/dir', '/path/to/other'],
    files: ['/path/to/mycompiledcss.css']
}

ext optional

The file extensions which will be used by Hologram, defaults to scss and js. Compatible with less, css, ts, jsx.

ext: {
    styles: 'scss',
    scripts: 'js'
}

title optional

The title of your styleguide. Will be displayed above documentation list.

title: 'My awesome app'

colors optional

The styleguide's color pallette, will be displayed at the top of the documentation list and below the title.

colors: {
    red: '#f00',
    green: '#0f0',
    blur: '#00f'
}

Colors can also be defined within the documentation by adding them as Markdown meta. The formatting should be as follows:

---
colors: {purple: 'purple'}
---

webfonts optional

The styleguide's webfonts, will be displayed at the top of the documentation list and below the title.

webfonts: {
    'Roboto': 'https://fonts.googleapis.com/css?family=Roboto',
    'Open Sans': 'https://fonts.googleapis.com/css?family=Open+Sans'
}

scripts optional

Information on which folders your scripts are contained in (dir). The specified directories will be recursively searched for files with the correct extension (js by default, can be changed using ext option), as well the paths to your app's scripts (files).

scripts: {
    dir: ['/path/to/dir', '/path/to/other'],
    files: ['/path/to/myscript.js']
}

customStylesheet optional

Add a custom stylesheet to the style guide. This approach is recommended as it will allow you to brand the styleguide. A template stylesheet is provided here.

customStylesheet: '/path/to/customStylesheet.css'

description optional

Allows you to add a small app description.

description: 'A big client site that needs a styleguide'

highlight optional

Add highlight.js to the style guide. This option is enabled by default.

highlightjs: true

idelink optional

Add support for IDE protocols to open files containing hologram docs.

The generated link will have the following format: %protocol%://open/?url=file://%file%&line=1

A general icon is provided for any IDE.

Following IDE are provided with a custom icon

• Sublime Text sublime : '...'
• Phpstorm phpstorm : '...'
• Textmate textmate : '...'

You may need to download a plugin for your IDE.

i.e.

• SublimeText,
• PhpStorm

This option is disabled by default.

idelink: {
    idename : 'protocol',
    otheridename : 'otherprotocol'
}

Examples

Gulp

// Require gulp
const gulp = require('gulp');

// Define options that will be passed to hologram
const options = {
    root: __dirname,
    ext: {
        styles: 'scss',
        scripts: 'js'
    },
    dest: '/path/to/dest',
    title: 'My awesome app',
    description: 'A big client site that needs a styleguide',
    customStylesheet: '/path/to/customStylesheet.css',
    colors: {
        red: '#f00',
        green: '#0f0',
        blut: '#00f'
    },
    webfonts: {
        'Roboto': 'https://fonts.googleapis.com/css?family=Roboto',
        'Open Sans': 'https://fonts.googleapis.com/css?family=Open+Sans',
    }
    styles: {
        dir: ['/path/to/dir', '/path/to/other'],
        files: ['/path/to/mycompiledcss.css']
    },
    scripts: {
        dir: ['/path/to/dir', '/path/to/other'],
        files: ['/path/to/myscript.js']
    },
    highlight : false,
    idelink : {
        phpstorm : 'phpstorm',
        sublime : 'subl'
        textmate : 'txmt'
    }
};

// Require hologram passing in the desired options
const hologram = require('node-hologram')(options);

// Call hologram.init() to generate the styleguide
gulp.task('hologram', () => hologram.init());

Slack

Slack channel/