This package has been deprecated

Author message:

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

Bootstrap Brandy

A living style guide for Bootstrap 3 Sass projects, built on Node.js, Grunt, and Handlebars, with optional Brand.ai integration.

Installation

(If you want to skip this part, just copy /example and customize it. Make sure you change the dependency in package.json to point to the npm package bootstrap-brandy not the github repo.)

The easiest way to get started is via npm.

1. Install Node.js version 6.0 or higher.

2. Install Grunt, and be sure to check out the Getting Started guide.

3. Create a new Node.js project folder and install the style guide core:

   $ npm install bootstrap-brandy --save

4. Create Gruntfile.js in the root folder of your new project:

   module.exports = function(grunt) {
       require('load-grunt-tasks')(grunt)
       var path = require('path')
       grunt.initConfig({
           brandy: {
               styleguide: {
                   options: {
                       npmInstall: true
                   },
                   projects: {
                       'node_modules/bootstrap-brandy': ['default', '--assets=' + path.resolve()]
                   }
               }
           }
       })
       grunt.registerTask('default', ['subgrunt:brandy'])
   }

5. Create a package.json file in the root folder of your project:

   {
     "description": "My example style guide, built on bootstrap-brandy.",
     "main": "server.js",
     "name": "My Style Guide",
     "version": "0.0.1",
     "devDependencies": {
       "grunt": "^0.4.5",
       "grunt-auto-install": "^0.3.1",    
       "grunt-check-dependencies": "^0.12.0",
       "grunt-contrib-copy": "^1.0.0",
       "grunt-subgrunt": "^1.2.0",
       "load-grunt-tasks": "^3.5.0"
     },
     "dependencies": {
       "bootstrap-brandy": "latest",
       "express": "^4.14.0",
       "handlebars": "^4.0.5",
       "lodash": "^4.13.1",
       "minimist": "^1.2.0",
       "request": "^2.72.0",
       "rootpath": "^0.1.2"
     }
   }

6. Install npm dependencies in the root folder of your project:

   $ npm install

Configuration

Create a new config.json file in the root folder of your project:

{
    "brandai": {
        "enabled": true,
        "key": "yourAPIKey",
        "name": "yourStyleGuideName",
        "org": "yourOrg"
    },
    "livereload": {
        "port": 35729
    },
    "project": {
        "name": "My",
        "description": "<blockquote>About my style guide, how you should use it, and why it's awesome!</blockquote>"
    },
    "server": {
        "port": 8080
    },
    "external": {
        "css": [
            "https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css"
        ],
        "js": [
            "https://cdnjs.cloudflare.com/ajax/libs/6px/1.0.3/6px.min.js"
        ]
 
    }
}

Adding external resources

Need to include external resources from a CDN in your project? No problem. Use the external property of your config.json to include them in your style guide:

{
    ...
    "external": {
        "css": [
            "https://your.cdn.here/file.css"
        ],
        "js": [
            "https://your.cdn.here/file.js"
        ]
 
    }
}

Creating content

All user-configurable content (elements, patterns, etc.) must be added to the /content directory as individual .html files.

Create an applicable .html file for the content you want to add. Each file must named identically in all the folders they're being added to.

For example, if you want to add a section for buttons, you'll need to add:

• Page-rendered markup: markup/*/buttons.html
• Usage doc: usage/*/buttons.html (optional)
• Copy/paste-friendly code snippets: examples/*/buttons.html (optional)

Customizing bootstrap with CSS/SCSS

There are two controller files for managing SCSS:

• _theme.scss: Override Bootstrap's existing SCSS variables. If you're integrating with Brand.ai, you'll want to import external/brandai.scss at the top of this file.
• style.scss: Define custom variables and styles. You can also include external files* if you want to break out components, e.g.:

@import "_theme.scss";
 
/* Variables */
$pressed-darken-amount: 10%;
$active-darken-amount: 5%;
 
/* Global Styles */
body:not(pre):not(code) {
    letter-spacing: 0.5px;
    -webkit-font-smoothing: antialiased;
}
 
/* Elements */
@import "elements/_buttons.scss";
@import "elements/_well.scss";
 
/* Patterns */
@import "patterns/_forms.scss";

^{* Make sure you prefix all your external files with an underscore, the standard Sass partial syntax.}

Fire it up!

To run the project, simply run:

$ grunt

(That was easy, right?)

Contributing

Please fork and submit a pull request. The project has been designed to keep the core services isolated from any user-configurable content, but please ensure sure you don't include any user-created elements in the PR.

By default, you should not include any of the following:

scss/_theme.scss
scss/style.scss
scss/**/*
js/**/*
content/**/*
config.json

To make developing easier, you may want to clone this project and keep it separate from your user-configurable elements. To do this, edit your project's Gruntfile.js to add a grunt-contrib-copy option (which you'll need to install):

module.exports = function(grunt) {
    require('load-grunt-tasks')(grunt)
    var path = require('path')
    grunt.initConfig({
        copy: {
            dev: {
                expand: true,
                cwd: '/Users/{you}/Development/bootstrap-brandy',
                src: ['scss/**/*', 'js/**/*', 'components/**/*', '*.*'],
                dest: path.join(process.cwd(), 'node_modules/bootstrap-brandy/')
            }
        },
        subgrunt: {
            styleguide: {
                options: {
                    npmInstall: false // or true, if you want to force dependency installs
                },
                projects: {
                    'node_modules/bootstrap-brandy': ['default', '--assets=' + path.resolve()]
                }
            }
        }
    })
    grunt.registerTask('default', ['subgrunt:styleguide'])
    grunt.registerTask('dev', ['copy:dev', 'subgrunt:styleguide'])
}

Then add the dev argument when starting the project:

$ grunt dev

Updating Bootstrap Brandy

When a new version is released, you'll probably want to check it out. To do that, simply run:

$ npm update bootstrap-brandy

Troubleshooting

Sass is not installed

If you try to run the project and don't have Sass installed, you might get an error indicating as much. El Capitan has Ruby restrictions, so try:

$ sudo gem install sass -n/usr/local/bin

Or use NVM, brew, or rubenv to manage a local instance of Ruby.

Fatal error: Unable to find local grunt

You probably forgot to run $ npm install after cloning the project. Check out Installation step 5.

npm ERR! enoent ENOENT: no such file or directory, rename

You might see something like this happen after updating Brandy:

npm ERR! enoent ENOENT: no such file or directory, 
rename '/Users/.../node_modules/bootstrap-brandy/node_modules/.staging/bootstrap-brandy-221efde2' 
-> '/Users/.../node_modules/bootstrap-brandy'

If this happens, you probably need to run:

$ npm prune

Licensing

Bootstrap Brandy is licensed under the MIT License

Additional Resources

• Bootstrap documentation
• Grunt.js getting started guide