Wondering what’s next for npm?Check out our public roadmap! »

    node-hologram

    0.2.2 • Public • Published

    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

    You may need to download a plugin for your IDE.

    i.e.

    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/

    Install

    npm i node-hologram

    DownloadsWeekly Downloads

    31

    Version

    0.2.2

    License

    ISC

    Last publish

    Collaborators

    • avatar