Skip to content

chrometoasters/ct-grunt-styleguide

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

69 Commits
docs/kss
docs/kss
 
 
grunt-tasks
grunt-tasks
 
 
template
template
 
 
tests/test-1
tests/test-1
 
 
Gruntfile.js
Gruntfile.js
 
 
README.md
README.md
 
 
bower.json
bower.json
 
 
package.json
package.json
 
 

Repository files navigation

Grunt: Styleguide v1.2.0

Chrometoaster's KSS Styleguide generator.

Please note: this plugin is optimised for internal Chrometoaster use. YMMV.

Terminology

  • KSS - Knyle Style Sheets; if you're unfamiliar with KSS, please read our docs
  • NPM - the Node Package Manager, installed with NodeJS

Setup and Basic usage

A. One-time setup, for all projects

Open Terminal

1. Install KSS

  1. npm list kss -g, to check whether you have the kss NPM package installed [src]
  2. If KSS is (empty):
    1. In Terminal: sudo npm install -g kss, to instruct NPM to install the KSS binary so that is available globally

2. Install KSS-Node and its dependencies

This project uses the NodeJS implementation of KSS, so you will also need to install kss-node from Github:

  1. TODO: ???, to check whether you have this installed
  2. If not:
    1. cd /path/to/github-clones, to change to the directory where you store Git repositories that you clone
    2. git clone https://github.com/chrometoasters/kss-node.git, to clone our copy of kss-node
    3. cd kss-node, to change into the directory you just created
    4. sudo npm install -g - to instruct NPM to install the kss-node dependencies listed in package.json. The -g ('global') flag instructs OS X to copy the files to /usr/local/lib/node_modules/kss/

3. Install Grunt and its dependencies

  1. If you haven't used Grunt before, please read Set up Grunt dependencies.

4. Install Bower

  1. npm list bower -g, to check whether you have the Bower NPM package installed [src]
  2. If Bower is (empty):
    1. sudo npm install -g bower, to install Bower

B. Every time you set up a new project

Open Terminal

1. Navigate to your project directory

  1. cd /PATH/TO/PROJECT-THEME-FOLDER, to change to your project's theme folder

Note: If you wish to customise where Bower puts installed components, you may add a .bowerrc file into your project directory:

    {
        "directory" : "PATH/TO/COMPONENTS"
    }

This README makes the assumption that you have used the default Bower install path of bower_components.

2. Install the KSS Grunt Task and its dependencies

  1. bower install https://github.com/chrometoasters/ct-grunt-styleguide.git, to install this Grunt task
  2. cp bower_components/ct-grunt-styleguide/package.json package.json, to copy package.json into your project's theme folder
  3. npm install, to install the dependencies listed in package.json
  4. SVN/Git ignore the generated folder: node_modules
  5. If you are using SVN, ignore the generated folder: bower_components (bower #1194)

3. Set up the KSS Grunt Task and customise for your project

Note: KSS comments are stripped when CSS is compressed. For this reason it's best to set the src to your scss folder.

  1. cp bower_components/ct-grunt-styleguide/Gruntfile.js Gruntfile.js, to copy Gruntfile.js into your project's theme folder

  2. cp -Ri bower_components/ct-grunt-styleguide/grunt-tasks grunt-tasks, to copy grunt-tasks into your project's theme folder; if this folder already exists you will need to manually merge the files contained within the options folder

  3. nano package.json to open package.json

  4. Edit the paths to suit your project; note that the styleguide.src folder must exist already, but the styleguide.dest folder will be created

  5. Control + X (exit) -> y (yes) -> Enter

  6. Create a project template (eg styleguide-page.php) to import the Styleguide page, at the path you specified in styleguide.page

     // styleguide.php
 // NOTE: DOCUMENT_ROOT is the site root, not your theme root
 <!-- header code here -->
 <?php
     // START KSS STYLEGUIDE
     include( $_SERVER['DOCUMENT_ROOT'] . '/PATH/TO/PROJECT-THEME-FOLDER/STYLEGUIDE-DEST/index.php' );
     // END KSS STYLEGUIDE
 ?>
 <!-- footer code here -->

Note that the styleguide requires jQuery be present at the top of the page, so if your project <head> does not include this already you will need to add it.

4. Run the Grunt

  1. grunt styleguide, to run the Grunt task

C. Occasional maintenance

1. To update the styleguide and/or the styleguide template version

  1. Perform step B1
  2. Perform step B2.1
  3. Perform step B4
  4. If you see Fatal error: Unable to find local grunt., perform step B2.3
  5. Perform step B4

Advanced Usage

'Pixel Perfect' style design overlays

You may optionally specify an sg-overlay before your snippet HTML. This will position the design above your component, with controls to change the opacity and toggle the overlay layer off.

/*
Module: Modulename

Markup:
<div class="sg-overlay" draggable="true" data-current="true" data-img="MOE-IE-Guide-page-v14.jpg" data-img-w="1500" data-el-w="770" data-el-h="380" data-el-x="-951" data-el-y="4855"></div>
include "my-module-snippet.html"

Styleguide 123.4
*/

Options:

Source: ct-docs.js

Required options:

  1. data-img - filename of the design image, relative to a designs_path of /PROJECT_RESOURCES_PATH/build/designs/
  2. data-img-w - the pixel width of the design image

Optional options:

  1. data-current - toggle to false to indicate that the design has been updated since the CSS was last checked
  2. data-el-w - the pixel width of the design element, defaults to the width of the parent container
  3. data-el-h - the pixel height of the design element, defaults to the height of the parent container
  4. data-el-x - the pixel distance to move the design image to the left (defaults to half of the design width), defaults to zero; use a negative value for design elements located to left of center
  5. data-el-y - the pixel distance between the top of the design image and the top of the design element, defaults to zero

Troubleshooting

  1. You may use console.log within Gruntfile.js to check paths

About

A Grunt task to generate Chrometoaster's KSS Styleguides

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

12 watching

Forks

2 forks
Report repository

Releases 1

v1.2.0 Latest
May 12, 2014

Packages

No packages published

Languages