tools.md

External tools

Mikser is very lean about the usage of external tools. It doesn't come with any plug-ins and subsystems that try to build, compile and pre-process style sheets. It provides hooks for using those tools as command line utilities. To keep things simple there are just two hooks in Mikser.

• compile - This hook is executed prior to any generation or when Mikser detects a change in files folder. It is a great place to pre-process your Less and Sass or compile scripts like CoffeeScript and TypeScript. You can configure as many commands as you need.
• build - This hook is executed after a generation is over. You can use it to add an extra build step to minify images, scripts, lint your files or run an external build system like Grunt and Gulp to do it. You can configure as many commands as you need.

For the compile hook you can configure commands either by specifying the command or add an additional pattern that will filter the files this command is relevant for. By default Mikser watches the files folder of your site for changes and takes action when something changes, the pattern filters what command to execute when a file changes. By default Mikser will inspect commands for common compilators and preprocessors and add the default pattern to the command. Currently there is a build-in support for Less, Sass, CoffeeScript and TypeScript.

Preprocessors and compilators

Mikser watches and compiles only files located in files folder. Let's see how we can configure Mikser to use Less and CoffeeScript.

compile:
- 'lessc --source-map files/styles/style.less out/styles/style.css'
- 'coffee --compile --output files/scripts/ out/scripts/'

This will pre-process your styles.less every time a *.less file changes and compile all your coffee script files when *.coffee file changes.

An alternative approach is to use Grunt or Gulp to compile things for you.

compile:
- command: 'grunt compile'
  pattern: '**/*.+(less|coffee)'

This configuration assumes that there is compile task configured in your Gruntfile.js and that grunt configuration is in the same folder as mikser.yaml. Mikser will execute grunt compile on every less or coffee script change. Here is the an example of a grunt configuration that will process less files.

module.exports = function(grunt) {
  grunt.initConfig({
    less: {
      dev: {
        options: {
          sourceMap: true,
          sourceMapFileInline: true
        },
        files: {
          'out/styles/style.css': 'files/styles/style.less',
        }
      },
      dist: {
        options: {
          sourceMap: false
        },
        files: {
          'out/styles/style.css': 'files/styles/style.less',
        }
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-less');
  grunt.loadNpmTasks('grunt-newer');

  grunt.registerTask('compile', ['newer:less:dev']);
  grunt.registerTask('default', ['newer:less:dist']);
};

Build systems

Once the generation is over Mikser will execute the build commands configured in mikser.yaml. This the best place to configure the minification of your assets or lint your files. You can use external utilities one by one or use a build system where you can configure all actions together. For example it's a good idea to output the result of this step in the separate build folder which you can later upload to your hosting server.

build:
- grunt

This configuration will execute grunt each time generation is over. By default Mikser will regenerate every time document or layout has been changed.

module.exports = function(grunt) {
  grunt.initConfig({
    less: {
      dev: {
        options: {
          sourceMap: true,
          sourceMapFileInline: true
        },
        files: {
          'out/styles/style.css': 'files/styles/style.less',
        }
      },
      dist: {
        options: {
          sourceMap: false
        },
        files: {
          'out/styles/style.css': 'files/styles/style.less',
        }
      }
    },
    cssmin: {   
      dist: {
        files: [{
          expand: true,
          cwd: 'out/',
          src: ['**/*.css'],
          dest: 'build/'
        }]
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-less');
  grunt.loadNpmTasks('grunt-contrib-cssmin');
  grunt.loadNpmTasks('grunt-newer');

  grunt.registerTask('compile', ['newer:less:dev']);
  grunt.registerTask('default', ['newer:less:dist', 'newer:cssmin:dist']);
};