csscomb/csscomb.js

CSS coding style formatter

DEPRECATED

This version of CSScomb is no longer supported, guys.
We have a new super cool Node.js version instead!

Tool for sorting CSS properties

• Sorts CSS properties into a logical, consistent order
• Allows for custom sorting of CSS properties (set it to whatever order you're accustomed to)
• Parses CSS in style tags and style attributes -- can comb other languages for CSS as well
• Does not change existing formatting of style sheets --target single or multiple lines of CSS
• Separates CSS properties into groups (you can have groups of empty strings, if you want)
• Fully supports CSS2/CSS2.1/CSS3

The CSScomb algorithm simulates a web developer's judgment in ordering CSS styles. You can spend tons of time re-ordering code--moving lines over each other, working around comments in the code, moving multi-line sets of property values, and all sorts of hacking to make your code more readable. CSScomb takes care of these tasks for you. It "thinks" like a person editing the text, not as a blind robot parsing CSS.

CSScomb.com

The Requirements

CSScomb is written in pure PHP, without any external libraries or dependencies. See details at wiki.

Download plugins

• Sublime Text 2 plugin avaliable in Package Control as 'CSScomb'
• TextMate plugin
• Coda plugin
• Coda 2 plugin
• Espresso 2 plugin (How to install)
• IntelliJIDEA plugin
• WebStorm plugin
• PyCharm plugin
• Notepad ++ plugin
• Chocolat Mixin
• Vim Plugin

CLI usage

Available at csscomb.com

% php csscomb.php

CSSComb
Command line tool for resort CSS code.

SYNOPSIS
    $ php csscomb.php -s <file with JSON array> -i <path to input css file> -o <path to result css file>

DESCRIPTION
    options:
    -s, --sort-order    specify file with custom sort order. File must contain JSON data. For detail information run 'csscomb.php --help-sort-order'
    -i, --input         must be directory name or file that needs to be sorted
    -o, --output        sort result file. Use output when input is not a directory name, otherwise output param ignored. If output filename does not exist, the file is created. Otherwise, the existing file is overwritten.

    --help, -help, -h, -? or no options will print this man.

EXAMPLE
    csscomb.php -s my-custom-sort-order.json -i css/style.css -o css/style-resorted.css

EXAMPLE 2
    csscomb.php -i some_directory_name

Twitter

@csscomb

csscomb.js's Issues

Option: stick-brace

Default value — false (no changes will be made).

Available (valid) values:

1. Boolean true — 1 space
2. String \s+ — selector%space%{

Examples:

"stick-brace": true
"stick-brace": "\n"

Results:

/* true */
a {
    color: red;
}

/* \n */
a
{
    color: red;
}

Option for whitespaces around combinators

• .foo>.bar vs. .foo > .bar
• .foo~.bar vs. .foo ~ .bar

etc.

Support for Roole preprocessor

Quotes for urls

url(blah.png) or url('blah.png') pr url("blah.png").

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Option: strip-spaces

Default value — false (no changes will be made).

Available (valid) value: Boolean true

Example:

"strip-spaces": true

Results:
1)

a { color: red }\n
\n
\n

vvvvvvvvvvvv

a { color: red }\n

2. a { color: red } \n => a { color: red }\n

Use external files for tests

As we test stylesheets, it seems rather strange to include css code inside js files.
It's hard to write and hard to find a certain case.

I'd love to have two files for a test, e.g. input-x.css and expected-x.css.
Configuration can be set inside test.js or as a separate file config-x.json, where x is test's id.

This would help to test large files and stylesheets with indent-based syntax.

Option for whitespaces around the comma in “functions”

• scale(0.5,1) vs. scale(0.5, 1)
• rgba(0,0,0,.5) vs. rgba(0, 0, 0, .5)

etc.

Maybe, there should be a way to set this option to be different for different functions, for example some people like to set newlines inside gradients etc.

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/1519095-option-for-whitespaces-around-the-comma-in-functions?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github).

Option: colon-space

Default value — false (no changes will be made).

Available (valid) values:

1. Boolean true — 1 space after colon (same as after)
2. String before|after|both — color%a%:%b%

Examples:

"colon-space": true
"colon-space": "both"

Results:

/* true */
a {
    color: red;
}

/* both */
a {
    color : red;
}

README: add info about available values for every option

Options for order the multiple values when the order don't matter

• border: 1px solid #FFF vs. border: #FFF solid 1px

• background: #FFF 0 0 no-repeat url() vs. background: url() #FFF no-repeat 0 0

  etc.

Of course, when order matters it mustn't be changed (multiple backgrounds, shorthand paddings, font, transform etc).

Поправить конфиг: свойства font и line-height должны быть в самом начале

Support for global config

CSSComb should follow directory structure up to the root looking for configuration. If nothing found, use config from user home dir (like .gitconfig).

Option for whitespaces around the comma in selectors

.foo,.bar {}

vs.

.foo, .bar {}

vs.

.foo,
.bar {}

etc.

Option to align property-value parts

Similar to #17, but for aligning all the property-value parts. For example, property-value-align.

I guess, when this option is true, we should align things only inside their “groups”. I don't think that overall aligning among all the properties inside a declaration makes any sense, and adding different values to make all variants possible would just complicate things.

So, false value should remove all the aligning if it present, and true should align the values inside groups, like this:

/* before */
p {
    margin: 0;
    padding: 0;

    border: 0;
    background: none;
}

/* after */
p {
    margin:  0;
    padding: 0;

    border:     0;
    background: none;
}

It's obvious, that this option should run after the sort-order one, so the right groups would be aligned.

While I think those two (true and false) values would be enough, there could be different possible variants (including overall aligning), like

p {
    margin : 0;
    padding: 0;

    border    : 0;
    background: none;
}

p {
     margin: 0;
    padding: 0;

        border: 0;
    background: none;
}

p {
    margin:     0;
    padding:    0;

    border:     0;
    background: none;
}

etc. Dunno if someone would need those, but we could add different string keywords to make those possible.

Fails on empty CSS files

stack:  Error: Undefined tree at ./empty.css: "" => undefined
    at Object.Comb.processString (/Users/rudeshko/.nvm/v0.8.25/lib/node_modules/csscomb/lib/csscomb.js:103:19)
    at Comb.processFile (/Users/rudeshko/.nvm/v0.8.25/lib/node_modules/csscomb/lib/csscomb.js:119:46)
    at Array.Promise._callCallbacks [as 189] (/Users/rudeshko/.nvm/v0.8.25/lib/node_modules/csscomb/node_modules/vow/lib/vow.js:200:56)
    at callFns (/Users/rudeshko/.nvm/v0.8.25/lib/node_modules/csscomb/node_modules/vow/lib/vow.js:458:35)
    at process.startup.processNextTick.process._tickCallback (node.js:245:9)

Empty files should be ignored or reported as warnings.

Output usage when no arguments passed

Nothing happens when i do just csscomb without arguments. There should be usage info.

Support -v shortcut for --version

Fails on symlinks

$ csscomb .
stack:  Error: ENOENT, stat './.symlink'

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/1519085-fails-on-symlinks?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github).

Remove dublicates

Sometimes, there's a chance to get dublicates inside the CSS code because of the mixins usage.

For example, some element has both border-radius and box-shadow, pie is added to handle backwards compatibility. Each mixin (for radius and shadow) may add its own behavior: url(PIE.htc), so in the output there'll be two instances of behavior: url(PIE.htc).

Dublicates removal would be a great option.

Option: rule-indent

Default value — false (no changes will be made).

Available (valid) values:

1. Boolean true — 4 spaces
2. Number n — {n} spaces
3. String ^[ \t]+$

Examples:

"rule-indent": true
"rule-indent": 2
"rule-indent": "\t"

Results:

/* true */
a {
    color: red;
}

/* 2 */
a {
  color: red;
}

/* \t */
a {
        color: red;
}

Hexadecimal color shorthands

There should be an option on how to display shorthand hexadecimal colors: #333 or #333333 etc.

Broken indentation in rulesets with multiple selectors

    .first,
    .third,
    .second
    {
        width: 10px;
    }

results in

.first,
    .third,
    .second
{
    width: 10px;
}

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Option: always-semicolon

Default value — false (no changes will be made).
Available value: Boolean true — 1 space after colon (same as after)

Example:

"always-semicolon": true

Before:

a { color: red }

After:

a { color: red; }

Proper `\n` and `\t` in whitespace options

We should allow users to set both \n and \t as a value for any whitespace options. However, there are currently two problems:

1. \n is inserted as is, without the proper indent. It should be inserted always at the same level as the original line had.
2. \t is inserted as an actual tab indent, however it would make more sense to insert it as the current indent size set. This way we could use it to place code more intelligently, so to change the overall indents we could change only one option instead of every.

Those things are already done in most text editors, so users would wait them to work in this matter, however we could introduce an option disabling this behaviour, but it should be default for the reasons I provided above.

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/1519079-proper-n-and-t-in-whitespace-options?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github).

Лишние переносы строк при "stick-brace": "\n"

.lol, .nyan,
.xxx
{
    width: 0;
}

превращается в

.lol
, .nyan
,

.xxx
{
    width: 0;
}

Move the whitespace setter to a common function

Most of the options that set the whitespace in different places should have the same logic in the setters. Right now it would be mostly copy-and-paste, but it's not optimal.

We should create a native csscomb function to use in the options, so we could just say something like readWhiteSpaceOption(value) instead of writing all those checks every time.

This would make all the similar options to have the same way of setting the value and would ease the configuring of csscomb, 'cause you won't need to know which option takes what values.

We should discuss how those values should look like. I'd suggest my vision, but it could be not ideal, so correct me if I'm wrong anywhere:

Possible values

{Array} of two values.

Each of two given values should be one of the following types (except for the {String} values other than whitespace ones).

This should set the whitespace to the left ([0]) and to the right ([1]) to the given value.

{Boolean}

• 'true' should set the “default” whitespace for the option. It could be the single space for the most of the options.
• false should remove the whitespace at all.

{Number}

Numeric value should set the size of the whitespace in spaces.

{String}

• [ \t]* (with \n if the #78 would be done) should set the whitespace to the given string.
• before, after or both should be treated as the corresponding side was true and the other one is false.
• Special symbol surrounded by proper whitespace, like [ \t]*:[ \t]* etc, should be parsed and the whitespace around the given symbol should be set as the one in the given string example. While I made this in the colon-space option, I think we should remove this value from the possible ones, 'cause it was not the best idea and it would be better to implement #30 instead.

{Object}

Some of the options could want to have more control other than those possible values above. For example, for combinators we could want to set the different values to different combinators, like { "+": true, ">": " ", "~": "both" }.

There should be a reserved keyword like default, so if you'd want to set the value for every possible situations and then configure only one or two others, you could do something like this: { "default": true, "~": false }.

This would be really useful for options that set the whitespace around the comma or around the values (#51, #53, #54), 'cause there could be a lot of combinations. For example, for the virtual comma-space option one of the possible values could look like this:

{
    "comma-space": {
        "default": " ",

        "selector": " ",
        "function": {
            "rgba": "",
            "linear-gradient": " "
        },
        "property-value": {
            "font": "",
        },
        "colors": " ",
        "gradients": " ",
        "fonts": " ",
        "backgrounds": " ",
        "transforms": " "
    }
}

The readWhiteSpaceOption shouldn't know anything about those hashes except that default should set the value for everything and that the option author would use other values as he wants. And with the one function like readWhiteSpaceOption it would be really easy to him to parse the given values for different situations.

---

So, that's it. All the names are placeholders, there could be better names for the proposed functions etc.

Discuss :)

README: write about node.js require

Sort-order shortcuts

There is one thing I don't like in messing with sort-order option. It's that I need to use the existing example of sort-order, 'cause it contains all the props and if I would write this option from scratch I would surely forget something etc.

What I'd want is this option to be smart enought to understand such way of adding it:

{
    "sort-order": [
        [
            "position"
        ],
        [
            "width",
            "height",
            "padding",
            "border",
            "margin"
        ],
        [
            "font"
        ],
        [
            "color",
            "background"
        ]
    ]
}

This example should be treated as something like that:

{
    "sort-order": [
        [
            "position",
            "z-index",
            "top",
            "right",
            "bottom",
            "left"
        ],
        [
            "width",
            "min-width",
            "max-width",
            "height",
            "min-height",
            "max-height",
            "padding",
            "padding-top",
            "padding-right",
            "padding-bottom",
            "padding-left",
            "border",
            "border-collapse",
            "border-width",
            "border-style",
            "border-color",
            "border-top",
            "border-top-width",
            "border-top-style",
            "border-top-color",
            "border-right",
            "border-right-width",
            "border-right-style",
            "border-right-color",
            "border-bottom",
            "border-bottom-width",
            "border-bottom-style",
            "border-bottom-color",
            "border-left",
            "border-left-width",
            "border-left-style",
            "border-left-color",            
            "margin",
            "margin-top",
            "margin-right",
            "margin-bottom",
            "margin-left"
        ],
        [
            "font",
            "font-family",
            "font-size",
            "font-weight",
            "font-style",
            "font-variant",
            "font-size-adjust",
            "font-stretch",
            "font-effect",
            "font-emphasize",
            "font-emphasize-position",
            "font-emphasize-style",
            "font-smooth",
            "line-height"
        ],
        [
            "color",
            "background",
            "filter:progid:DXImageTransform.Microsoft.AlphaImageLoader",
            "background-color",
            "background-image",
            "background-repeat",
            "background-attachment",
            "background-position",
            "background-position-x",
            "-ms-background-position-x",
            "background-position-y",
            "-ms-background-position-y",
            "-webkit-background-clip",
            "-moz-background-clip",
            "background-clip",
            "background-origin",
            "-webkit-background-size",
            "-moz-background-size",
            "-o-background-size",
            "background-size",
        ]
    ]
}

There could be a lot of nuances, but the main rules could be:

1. There should be groups of properties like width, max-width, min-width or the position above, so when you use one of them in settings and other properties from that list are not listed in config, they should go where the one of them was defined.
2. There should be automatic groups like for the prefixed properties (it would make sense not to mention them in the config — user don't need to know which browsers support which prefixes), however if user wants, he could move some of the prefixes here and there, so this should be, again, a default.
3. If only few properties are defined in a config, those properties should go at the start of the block and all the other stuff would go after them (as it works in the original CSSComb, I guess).
4. This behaviour should be a default one, but there could be a satellite option to prevent the use of the default groups, for those control freaks who don't like them.
5. There could be, actually, some shortcuts lists embedded in csscomb, so you could call them just by using a keyword. For example, the config could consist only from "sort-order": "yandex", this way the build-in group yandex would be used etc.

While this is not that trivial and would need to have some defaults embedded in csscomb.js, this would be really handy and would make creating and maintaining such sort lists really easy and straightforwad.

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/1519080-sort-order-shortcuts?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github).

Sort order

Hey guys, thanks for a great package.

What about the --sort-order option? Is it possible to specify a custom sort order?

Option to remove empty rulesets

Hexadecimal color case option

There should be an option on how to present hexadecimal colors: in lower or upper case, e.g. #FAFAFA or #fafafa.

Strip spaces issue

Right now the strip-spaces option contains two different options, so it would be nice to split it (naming got from the ST settings) to:

1. trim-trailing-white-space.
2. ensure-newline-at-eof.

For example, someone would need to strip trailing spaces, but don't add newline at eof or ensure newline, but don't trim trailing spaces.

Generating config based on existing styles

This could be kinda a killer-feature.

We could add a possibility to use any given styles instead of setting the config manually.

There could be a lot of use cases for this, two of them:

1. You could have a file with a sample code that would be used as a template for your other files:

   .blah {
     color: #FFF;
     }
   

   Would set all the config options to the ones were used in this example: space before opening brace, two spaces for indent, uppercase color, trailing semicolon, closing brace on the same level as properties etc.

2. We could “comb” the styles using the statistics got from all the available CSS files. This way it would be really easy to generate a config for any given project: the most used code style would become a template and all the minor inconsistencies then would be combed down.

Option: block-split

editorconfig support

See http://editorconfig.org/ — it would be nice to make CSSComb somehow get some of the settings from the corresponding .editorconfig file.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Option: vendor-prefix-align

Default value — false (no changes will be made).

Available value: Boolean true — rules are indented by base rule name, values — by colon.

Example:

"vendor-prefix-align": true

Before:

a {
  -webkit-border-radius: 3px;
  -moz-border-radius: 3px;
  border-radius: 3px;
}
b {
  background: -webkit-gradient(linear, left top, right top, color-stop(0,rgba(255,255,255,0)), color-stop(20%, #fff));
  background: -moz-linear-gradient(left, rgba(255,255,255,0) 0, #fff 20%);
  background: -o-linear-gradient(left, rgba(255,255,255,0) 0, #fff 20%);
  background: -ms-linear-gradient(left, rgba(255,255,255,0) 0, #fff 20%);
  background: linear-gradient(to right, rgba(255,255,255,0) 0, #fff 20%);
}

After:

a {
  -webkit-border-radius: 3px;
     -moz-border-radius: 3px;
          border-radius: 3px;
}
b {
  background: -webkit-gradient(linear, left top, right top, color-stop(0,rgba(255,255,255,0)), color-stop(20%, #fff));
  background: -moz-linear-gradient(left, rgba(255,255,255,0) 0, #fff 20%);
  background:   -o-linear-gradient(left, rgba(255,255,255,0) 0, #fff 20%);
  background:  -ms-linear-gradient(left, rgba(255,255,255,0) 0, #fff 20%);
  background:      linear-gradient(to right, rgba(255,255,255,0) 0, #fff 20%);
}

Option: block-indent

Default value — false (no changes will be made).

Available (valid) values:

1. Boolean true — 4 spaces
2. Number n — {n} spaces
3. String ^[ \t]+$

Examples:

"block-indent": true
"block-indent": 2
"block-indent": "\t"

Before:

/* true */
     a { color: red; }
i {
  color: red;
   }
  @media all and (min-width:0px) {
    b { font: 0/0 a; }
  }

After:

/* true */
a { color: red; }
i {
  color: red;
}
@media all and (min-width:0px) {
    b { font: 0/0 a; }
}

Leading zero option

0.13em or .13em

General quote style

"blah" or 'blah' — could be used for #35 if it is not specified, but also would apply for content property, attribute selectors etc.

Verbose option

Config value (always verbose by default):

{ "verbose": true }

CLI param:

./node_modules/.bin/csscomb . --verbose
blocks-common/b-link/b-link.css
blocks-common/competitors/competitors.css
blocks-common/content/content.css
...
30 files processed
15 secs left

Option for margins/paddings/etc. shorthands

padding: 0 10px vs. padding: 0 10px 0 10px

Some people prefer to always have the longhand ones, while other prefer to have then collapsed.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Bundle reasonable default configuration

$ csscomb
Configuration file /Users/rudeshko/dev/.csscomb.json was not found.

Please provide default (most popular CSS style) configuration in npm package (with corresponding warning like "Using default configuration, consider make a copy").
There should be a possibility to create a copy of default configuration in current directory.

Spaces inside comments

Before:

/*foobar*/
/*sdfdf
sdfsdf
*/

After:

/* foobar */
/* sfdsfsdf
   sdfdsfsdf
   sdfsfdsf */

Option for the case of element selectors

div.class {} vs. DIV.class {}

(in CSS the case of the element don't matter, so there are people who prefer the second variant, so the selectors would be more readable).

More info in lint mode

Unit for zero values

0 or 0px

However, for some cases this won't be trivial: there are places where we don't need to remove units or things would brake, also in different conditions there should be different units, like 0deg for angles etc.

Option which way of describing colors to use

#FFF, white, rgb(255,255,255) or hsl(0,0%,100%).

This option could take array as an arguments, like ['keyword', 'hexadecimal', 'rgb'], so you could say that the keywords like white are preferred instead of hex, and the hex should be used instead of rgb where possible.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Feel free to move this repo to github.com/csscomb/csscomb.js

Option for whitespaces between multiple values

foo: bar,baz vs. foo: bar, baz or even

foo: bar,
     baz

(the latest one should be described using the keyword, I guess)

There could be three (?) similar options for different possible multiple values styles:

1. For comma-separated values: foo, bar
2. For space-separated values: foo bar
3. For whitespace between the functions and following values: url()#FFF vs. url() #FFF (this is separate from the previous, 'cause the previous one can't have empty string as an argument).

Also, as with #53, there should be a way to set this option to be different for different properties: for paddings people would want to have 0 0 10px, but for transforms they would want

transform: scale(1,2)
           rotate(30deg)

etc.

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/1519093-option-for-whitespaces-between-multiple-values?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F214563&utm_medium=issues&utm_source=github).

Props order

Is props order normalization (like original CSSComb) supposed to be supported by this module?