Getting Started

"Kittn" is a toolkit designed to support mainly the construction of frontends. Anyone looking for a colorful mixture of prefabricated elements, as one would expect from bootstrap and co, will not be happy with Kittn. Here rather the methods are offered to those elements on a simple way to generate and expand.

Around the CSS part, there are still many automatic functions installed that help the developer. For example, to generate image assets and distribute, to build HTML mockups, to make sprites to generate fallbacks for SVG files. That's why I also avoid the term framework.

Install

$ npm install -g generator-kittn

Usage

Jump in your Working Directory and type:

$ yo kittn

The Generator will ask you some questions, at the end it will prepare the Project.

Questions

After the generator has been started, you a number of questions are asked to preconfigure the project.

Kittn Questions

We will not now go into every single question, since most are self-explanatory.

IE8 compatibility needed?
I hope not, but when you need IE8 Compatiblity you can activate here. It include some fallbacks in your final CSS file.

How do you want to compile your Structure with Jade or Twig? Otherwise you can use the Copy Task to move Files from src to your dist dir.
The choices:

  • Twig
  • Jade
  • Uncompiled

For pure HTML prototypes template engines like Twig or jade are well suited. Who is working on a Worpdress Tempalte is better come with Uncompilied rightly (because only files copied).

The uncompiled task is always included, no matter how the decision fails. Anyone who excludes template engines can this no longer simply reactivate later. Does one need afterwards a template engine, it must be manually integrated into the package.

How do you want to use Kittn? Yeoman can integrate the Toolkit for you (setting Path etc.)
Away from prototypes (you can Kittn as Static Page Generator use), you can integrate Kittn in template workflows (for WordPress, Craft or Kirby).

Structure

If the project was created and the init task has been completed, there are two directories available :

./
.. src/ => Source Files
.. dist/ => Distribution
.. gulpfile/ => Gulp Tasks

In the directory src/ is the source code, so that our working directory. In dist/ directory that should not work, therefore, only if it is absolutely necessary.

New with Version 3.1.x is that the Gulpfile is modularized and ES6 Compatible (with Babel.js), you will find all Tasks in the gulpfile/ directory. It is now easier for you to add additional Tasks, without touching the main Gulpfile (die Main Gulpfile is only a Loader).

SRC Folderstructure:

src/
.. .system/ => Internal System Files
.. bower/ => Bower Packages
.. fonts/ => Font Files
.. framework/ => Sass Framework
.. images/
.... bitmapSingle-assets => Single Bitmap Images
.... bitmapSprite-assets => Images for Bitmap Sprites
.... vectorSingle-assets => Single Vector Images
.... vectorSprite-assets => Vector Images for Vector Sprites
.. js/ => JS Files (e.g. app.js)
.. scripts/ => Script files that are not installed on Bower
.. structure/ => Source Files for Copy (e.g. Template Files for a WP Theme)
.. template/ => Source Files for a Template Compiler (Jade / Twig)
.. style/ => Styling Source Files

If you are not happy with the structure of the src/ folder, you can customize it. In the config.json must also be entered the new paths.

The Template / Structure directories even a short explanation. If an HTML compiler like jade or twig used the files from the template/ directory are used. If the compiler is disabled, the structure/ directory used. For example, you can put the files there a Wordpress template, these are then copied with a change in the src/ directory.

So you can later change from a prototype to a WordPress template. The compiled files are then manually copied into the structure/ directory, and then further processed from there.

src part from config.json

The dist/ folder is created after initialization (gulp init) of the project. All compiled and copied files of the src/ Folders land there. The structure may vary, depending on the purpose for which the generator was set.

Dist Folderstructure:

dist/
  .. assets/
  .... css/ => CSS Files
  .... fonts/ => Font Directory
  .... js/ => Javascript Files
  .... img/ => Background Image Assets
  ...... system/ => Images like Favicons
  ...... bitmaps/ => Bitmap Images
  ...... svgfiles/ => Vector Images

If you therefore should not be satisfied, you can change the structure in the config.json. When you change, delete the dist/ Folder, than run the Init Task.

dist part from config.json

Config File

In contrast to Kittn 2.0, this time all Gulp task settings are in a separate file. In the config.json you find all settings, with which the tasks are processed.

The Config File you will find now on gulpfile/ Directory.

The part of the dist/ and src/ directory, we have already clarified, so now the other segments.

Template Path

These paths are required for Sass compiler to link the assets properly.

Config Part for the Templatepathes
CSS

Here adjustments can be made to the Sass compiler. Regular Libsass is used if errors occur (Libsass is not yet on par with RubySass), you can this change to Ruby Sass (should then also be installed).

Config Part for Sass Compiler

compiler
Set the Sass Compiler
['libsass' || 'rubysass']

prefix
Settings for Autoprefixer, get the details form the Documentation.

Template

You can only adjust if a template compiler is activated, the choice between Jade and Twig takes place at the initial project creation with the generator.
If the compiler used, the files of the template/ directory are used. If the compiler is disabled, the files in the structure/ directory are used.

Settings for the Template Compiler

compiler
Activate the Template Compiler
[bool]

BrowserSync

Settings for Browsersync. You must activate the Proxy when you need PHP, BrowserSync Server is for HTML / JS only.

BrowserSync settings

openbrowser
Open the Browserwindow on Start
[bool]

proxy
Enter your vHost URL like 'testme.dev'
[bool || string]

Files

Basically we are working in the src/ directory, Fonts, Javascript and some system files are stored there. With Gulp tasks are copied then from the src/ directory to the dist/ directory. What these are is defined in the JSON object.

File Setting

jsApp
Here you can give your main JS File the Filename for src and dist. Browserify will use this file for the bundling process.

jsCombine
Only as Fallback when Browserify wont work
Include here all scriptfiles a to be combined into one file.
[array]

jsCombineFilename
Name for the Combined Script File.
[string]

jsCopy
Include here all Javascript files a need to be copied.
[array]

fonts
All Fontfiles a need to be copied in the 'dist/' folder.
[array]

"fonts": [
  "src/fonts/myFont.eot",
  "src/fonts/myFont.svg",
  "src/fonts/myFont.ttf",
  "src/fonts/myFont.woff"
]

launch
Simple System Files like .htaccess
[object]

Modernizr

Settings for the Custom Modernizr file. Link

Modernizr Settings

options
Plugins that added to Modernizr
[array]

tests
Added Tests
[array]

Conditionizr

Settings for Conditionizr. Link

Conditionizr Settigs

filename
Conditionizr File Name
[string]

files
Tests be added
[array]

Minify

Minification Settings

Minify Settings

images
Bitmap and Vector minification settings
[object]

javascript
Javascript Mangle Option
[bool]

Tasks

Init

When initializing the directory is dist/ constructed and the documentation of Sass frameworks. The Init must be started manually because it may be the one that config.json modified.

$ gulp init
Default

The default starts the BrowserSync Server (unless disabled) and monitors the working directory src/ to start, where appropriate compiler.

$ gulp
Rebuild Images

Rebuild all Image Files, copy it to distribution, build Bitmap- and Vector Sprites.

$ gulp rebuild:images
Rebuild JS

Rebuild all JS files, copy - combine - rename.

$ gulp rebuild:js
General Image Tasks

Copy Bitmap Images to distribution

$ gulp copy:bitmaps

Copy Vector Images to distribution

$ gulp copy:vectors
Publish Tasks

Publish the Project for Production - you can Bump the Version with environment variables.

$ gulp publish --type=major // Example for a Major Release
$ gulp publish

Minify JS, Images, CSS. Is for a automated Build Process, comes after a Gulp Init.

$ gulp deploy

Active Projects

The generator will create the project for the first time. When this process is finished, the generator is no longer needed. Other project members only need to load the repo to install the NPM and Bower packages and run the Init task.

$ npm install && bower install && gulp init && gulp

Extending Kittn

Kittn is designed to give the developer a skeleton in his hand, with which he can already work. Nevertheless, it will happen that not enough a the default plugins. One or the other would take the native js might use CoffeeScript might be missing that some other feature.

NPM Packages

To expand Kittn you should list the new plugins on the package.json, as the node_modules directory is not transmitted to the git repo.

$ npm install packagename --save-dev

This is a package about NPM Network, installed into the project directory and listed in the package.json. Thus, the subsequent Developer installed exactly the packages that are needed for the project.

To uninstall a NPM Package:

$ npm uninstall packagename --save-dev
Bower Packages

We have dropped the primary Bower Support, because NPM does the same Job and is easier to use NPM Packages with Browserify. Maybe when you have no luck with NPM, you can use Bowser as Fallback.

For Questions around Bower: Documentation