jimdo-templateflow/README.md

jimdo template grunt workflow

# jimdo templateflow [![Build Status](https://travis-ci.org/Jimdo/templateflow.svg?branch=master)](https://travis-ci.org/Jimdo/templateflow)
> grunt flow for jimdo templates

## About

The idea is to create an ability to use the same grunt flow over all jimdo templates,
to save up time and make it easier to develop the flow.

## Getting Started
This plugin requires Grunt `~1.0.1`

If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```shell
npm install jimdo-templateflow --save-dev
```

Once the package has been installed, add the following line to your Gruntfile:

```js
module.exports = require('jimdo-templateflow')
```

That's it, now you can use the provided tasks :)

## Grunt Tasks

Available grunt tasks provided by the templateflow. Note: The templateflow
will not provide any default task, so you have to call the tasks directly.

### serve

```serve
grunt serve
```

Compiles sass and starts a local server for developing. Watch und livereload
is also included.

### compile

```shell
grunt compile
```

Compiles and lints the sass files into css.

### build

```serve
grunt build
```

Creates deploy-ready css files, so it will be autoprefixed and minified.

### release

```serve
grunt release
```

Releases a version (patch as default) to the Design API. The publish process is at the
moment not public and usable for everyone.
Usage examples for bumping: https://github.com/vojtajina/grunt-bump#usage-examples

### prerelease

```serve
grunt prerelease
```

Releases a prereleased version to the Design API. The publish process is at the
moment not public and usable for everyone.
Usage examples for bumping: https://github.com/vojtajina/grunt-bump#usage-examples

## Configuration

The package provides many defaults, but you can overwrite them in the template.
Create in your root directory a `template.yml` file and use the following options.

```yml
# example for a template.yml

# directories
imgDir: 'img'

# css
cssExt: '.min.css'
```

#### baseDir
*optional* Type: `String` | Default: `./`

Set base directory for local server.

#### sassDir
*optional* Type: `String` | Default: `sass`

Set the directory for sass.

#### cssDir
*optional* Type: `String` | Default: `css`

Set the directory for compiled css.

#### imgDir
*optional* Type: `String` | Default: ``

Set the directory for images.

#### bowerDir
*optional* Type: `String` | Default: `bower_components`

Set the directory to the bower components for sass compiling.

#### cssExt
*optional* Type: `String` | Default: `.css`

Set the extension for compiled css files, for example: `.min.css`

#### port
*optional* Type: `Integer` | Default: 8080

Set the port for local server.

#### hostname
*optional* Type: `String` | Default: `localhost`

Set hostname for local server.

#### livereload
*optional* Type: `Number`|`Boolean` | Default: `true`

Set port for livereload or disable functionality.

#### designId
*optional* Type: `Integer` | no default

Set the Design ID for API. Further informations
here: https://github.com/Jimdo/grunt-template-publisher

#### publisherEndpoint
*optional* Type: `String` | Default: undefined

Set the endpoint for publishing. Further informations
here: https://github.com/Jimdo/grunt-template-publisher

#### sassCompiling
*optional* Type: `Boolean` | Default: true

Ability to switch off sass compiling (eg. for css-only templates)

## Environment

For some options it could be very helpful to use this direct in the environment,
therefore the templateflow provides some options.

#### process.env.PORT

Set the port for local server.

#### process.env.LIVERELOAD

Set port for livereload or disable functionality.

#### process.env.PUBLISHER_ENDPOINT

Set the endpoint for publishing (for example for local tests).

## CSS linter

The templateflow provides defaults for the css linter. Take a look to the
file `config/csslintDefault.js` for more details about it. You could also override
every option in your template. Create a `.csslintrc` in your root directory and add
your properties, for example:

```json
{
  "important": true
}
```

The default properties and the template based properties will be merged, so you
don't have to override every option.

## Custom grunt config

It's also possible to create template-based configs and tasks. It could
look in a way like this:

```js
module.exports = function (grunt) {

  grunt.initConfig({
    blubb: {
      option: {
        cool: true
      }
    }
  })

  require('jimdo-templateflow')(grunt)
  grunt.registerTask('default', ['serve'])
}
```

*Note:*: Write first your init config and then the requirement to the templateflow,
otherwise the config for the templateflow is missing.

## Contributing
Contributions are always welcome! Take care to maintain the existing coding style.
Add unit tests for any new or changed functionality. We're using jasmine for
unit testing. Install jasmine global on your machine (`npm install -g jasmine`)
and run `npm test`.