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

    furret

    0.0.3 • Public • Published

    Furret

    yet another node.js styleguide generator / cause why not

    Inspired by Hologram and node-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 furret

    Then require in your script file:

    const furret = require('furret')();
    furret.init();

    furret will then scan the directories specified in the .furretrc file, accessing any file ending in the correct file extension (see options ext).

    If the file's first comment is suffixed with the word doc furret will then take this comment and attempt to convert it to markdown which will then be used to create a styleguide.

    Gulp

     
    // Require gulp
    const gulp = require('gulp');
     
    // Require furret passing in the desired options
    const furret = require('furret');
     
    // Call furret.init() to generate the styleguide
    gulp.task('furret', () => furret.init());
     

    Docs

    /*doc
    ---
    title: module title
    group: group name
    order: 1
    colors:
        - red: '#f00'
        - white: '#fff'
    dependencies:
        - style :
            - 'path/to/dependency'
            - 'https://cdn.dependency.css'
        - scripts :
            - 'path/to/dependency'
            - 'https://cdn.dependency.js'
    ---
     
    __I am some markdown and I will describe this snippet__
     
    <example>
        <h2>I will be rendered as HTML and placed in an iframe.</h2>
    </example>
    */

    Exmple

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

    <example>
        <h2>I will be rendered as HTML 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 furret features can be set using markdown meta data. Meta data are optional.

    titleoptional

    The title option allows you to specify the name of an item in the styleguide.

    ---
    title: module title
    ---
    

    groupoptional

    The group option allows you to define groups of items in the styleguide. Groups will appear in alphabetical order

    ---
    group: group name
    ---
    

    orderoptional

    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
    ---
    

    colorsoptional

    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'
        - white: '#fff'
    ---
    

    dependenciesoptional

    The dependencies meta allow to list an example dependencies. Those can come from both cdn or local files.

    • style will define css dependencies that will be wrapped inside a style tag
    • script will define js dependencies that will be wrapped inside a script tag
    ---
    dependencies:
        - style
            - 'path/to/file.css'
            - 'https://cdn.dependency.css'
        - script
            - 'path/to/file.js'
            - 'https://cdn.dependency.js'
    ---
    

    Settings

    Create a .furretrc file in the project root. .furretrc contains furret settings.

    Settings can be defines as JSON, yaml or ini.

    title optional

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

    title: 'My awesome app'

    description optional

    Allows you to add a small app description.

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

    dest required

    The path to the folder where the styleguide generated by furret 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 (main).

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

    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 (main).

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

    ext optional

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

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

    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'
    }

    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'

    customLayout optional

    Use a custom handlebars.js template to render the styleguide. This approach is recommended as it will allow you to brand the styleguide. A starter layout template is provided here.

    customLayout: '/path/to/customlayout.hbs'

    customExample optional

    Use a custom handlebars.js template to render examples. This approach is recommended as it will allow you to brand the styleguide. A starter layout template is provided here.

    customExample: '/path/to/customExample.hbs'

    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 furret 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

    Yaml

     
    ---
      title: "My awesome app"
      description: "A big client site that needs a styleguide"
      dest: "/path/to/dest"
      ext:
        styles: "scss"
        scripts: "js"
      styles:
        dir:
          - "/src/scss/"
        main:
          - "./assets/furret.css"
          - "./assets/layout/furret.css"
      scripts:
        dir:
          - "/src/js/"
        main:
          - "./assets/main.js"
      colors:
        black: "rebeccapurple"
        dark: "#555a5b"
        white: "#ffffff"
        gray: "rgba(239, 238, 238, 0.5)"
        silver: "#cccccc"
        teal: "#00a6a9"
      idelink:
        phpstorm: "phpstorm"
     

    JSON

     
    {
        "title": "My awesome app",
        "description" : "A big client site that needs a styleguide",
        "dest": "/path/to/dest",
        "ext": {
            "styles": "scss",
            "scripts": "js"
        },
        "styles": {
            "dir": [
                "/src/scss/"
            ],
            "main": ["./assets/furret.css", "./assets/layout/furret.css"]
        },
        "scripts": {
            "dir": [
                "/src/js/"
            ],
            "main": ["./assets/main.js"]
        },
        "colors": {
            "black": "#000000",
            "dark": "#555a5b",
            "white": "#ffffff",
            "gray": "rgba(239, 238, 238, 0.5)",
            "silver": "#cccccc",
            "teal": "#00a6a9"
        },
        "idelink": {
            "phpstorm": "phpstorm"
        }
    }
     

    Sponsored by Ippocrate.srl

    Install

    npm i furret

    DownloadsWeekly Downloads

    3

    Version

    0.0.3

    License

    MIT

    Last publish

    Collaborators

    • avatar