less.js/README.md

Less.js v1.6.0

The dynamic stylesheet language. http://lesscss.org.

This is the JavaScript, and now official, stable version of LESS.

Getting Started

Options for adding Less.js to your project:

• Install with NPM: npm install less
• Download the latest release
• Clone the repo: git clone git://github.com/less/less.js.git

Feature Highlights

LESS extends CSS with dynamic features such as:

• nesting
• variables
• operations
• mixins
• extend (selector inheritance)

To learn about the many other features Less.js has to offer please visit http://lesscss.org and the Less.js wiki

Examples

nesting

Take advantage of nesting to make code more readable and maintainable. This:

.nav > li > a {
  border: 1px solid #f5f5f5;
  &:hover {
    border-color: #ddd;
  }
}

renders to:

.nav > li > a {
  border: 1px solid #f5f5f5;
}
.nav > li > a:hover {
  border-color: #ddd;
}

variables

Updated commonly used values from a single location.

// Variables ("inline" comments like this can be used)
@link-color:  #428bca; // appears as "sea blue"

/* Or "block comments" that span
   multiple lines, like this */
a {
  color: @link-color; // use the variable in styles
}

Variables can also be used in @import statements, URLs, selector names, and more.

operations

Continuing with the same example above, we can use our variables even easier to maintain with operations, which enables the use of addition, subraction, multiplication and division in your styles:

// Variables
@link-color:        #428bca;
@link-color-hover:  darken(@link-color, 10%);

// Styles
a {
  color: @link-color;
}
a:hover {
  color: @link-color-hover;
}

renders to:

a {
  color: #428bca;
}
a:hover {
  color: #3071a9;
}

mixins

"implicit" mixins

Mixins enable you to apply the styles of one selector inside another selector like this:

// Variables
@link-color:        #428bca;

// Any "regular" class...
.link {
  color: @link-color;
}
a {
  font-weight: bold;
  .link; // ...can be used as an "implicit" mixin
}

renders to:

.link {
  color: #428bca;
}
a {
  font-weight: bold;
  color: #428bca;
}

So any selector can be an "implicit mixin". We'll show you a DRYer way to do this below.

parametric mixins

Mixins can also accept parameters:

// Transition mixin
.transition(@transition) {
  -webkit-transition: @transition;
     -moz-transition: @transition;
       -o-transition: @transition;
          transition: @transition;
}

used like this:

// Variables
@link-color:        #428bca;
@link-color-hover:  darken(@link-color, 10%);

//Transition mixin would be anywhere here

a {
  font-weight: bold;
  color: @link-color;
  .transition(color .2s ease-in-out);
  // Hover state
  &:hover {
    color: @link-color-hover;
  }
}

renders to:

a {
  font-weight: bold;
  color: #428bca;
  -webkit-transition: color 0.2s ease-in-out;
     -moz-transition: color 0.2s ease-in-out;
       -o-transition: color 0.2s ease-in-out;
          transition: color 0.2s ease-in-out;
}
a:hover {
  color: #3071a9;
}

extend

The extend feature can be thought of as the inverse of mixins. It accomplishes the goal of "borrowing styles", but rather than copying all the rules of Selector A over to Selector B, extend copies the name of the inheriting selector (Selector B) over to the extending selector (Selector A). So continuing with the example used for mixins above, extend works like this:

// Variables
@link-color:        #428bca;

.link {
  color: @link-color;
}
a:extend(.link) {
  font-weight: bold;
}
// Can also be written as
a {
  &:extend(.link);
  font-weight: bold;
}

renders to:

.link, a {
  color: #428bca;
}
a {
  font-weight: bold;
}

Usage

Compiling and Parsing

Invoke the compiler from node:

var less = require('less');

less.render('.class { width: (1 + 1) }', function (e, css) {
    console.log(css);
});

Outputs:

.class {
  width: 2;
}

You may also manually invoke the parser and compiler:

var parser = new(less.Parser);

parser.parse('.class { width: (1 + 1) }', function (err, tree) {
    if (err) { return console.error(err) }
    console.log(tree.toCSS());
});

Configuration

You may also pass options to the compiler:

var parser = new(less.Parser)({
    paths: ['.', './src/less'], // Specify search paths for @import directives
    filename: 'style.less'      // Specify a filename, for better error messages
});

parser.parse('.class { width: (1 + 1) }', function (e, tree) {
    tree.toCSS({ compress: true }); // Minify CSS output
});

More information

For general information on the language, configuration options or usage visit lesscss.org or the less wiki.

Here are other resources for using Less.js:

• stackoverflow.com is a great place to get answers about Less.
• node.js tools for converting Less to CSS
• GUI compilers for Less
• Less.js Issues for reporting bugs

Contributing

Please read CONTRIBUTING.md. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Reporting Issues

Before opening any issue, please search for existing issues and read the Issue Guidelines, written by Nicolas Gallagher. After that if you find a bug or would like to make feature request, please open a new issue.

Please report documentation issues in the documentation project.

Development

Install Less.js

Start by either downloading this project manually, or in the command line:

git clone https://github.com/less/less.js.git "less"

and then cd less.

Install dependencies

To install all the dependencies for less development, run:

npm install

If you haven't run grunt before, install grunt-cli globally so you can just run grunt

npm install grunt-cli -g

You should now be able to build Less.js, run tests, benchmarking, and other tasks listed in the Gruntfile.

Using Less.js Grunt

Tests, benchmarking and building is done using Grunt ~0.4.1. If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to install and use Grunt plugins, which are necessary for development with Less.js.

The Less.js Gruntfile is configured with the following "convenience tasks" :

test - grunt

Runs jshint, nodeunit and headless jasmine tests using phantomjs. You must have phantomjs installed for the jasmine tests to run.

test - grunt benchmark

Runs the benchmark suite.

build for testing browser - 'grunt browser'

This builds less.js and puts it in 'test/browser/less.js'

build - grunt stable | grunt beta | grunt alpha

Builds Less.js from from the /lib/less source files. This is done by the developer releasing a new release, do not do this if you are creating a pull request.

readme - grunt readme

Build the README file from a template to ensure that metadata is up-to-date and (more likely to be) correct.

Please review the Gruntfile to become acquainted with the other available tasks.

Please note that if you have any issues installing dependencies or running any of the Gruntfile commands, please make sure to uninstall any previous versions, both in the local node_modules directory, and clear your global npm cache, and then try running npm install again. After that if you still have issues, please let us know about it so we can help.

Release History

See the changelog

License

Copyright (c) 2009-2014 Alexis Sellier & The Core Less Team Licensed under the Apache License.