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
• Docs
  • Example
  • Meta Data
• Settings

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

• 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

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