1 | [tests]: https://img.shields.io/circleci/project/github/shellscape/postcss-less.svg
|
2 | [tests-url]: https://circleci.com/gh/shellscape/postcss-less
|
3 |
|
4 | [cover]: https://codecov.io/gh/shellscape/postcss-less/branch/master/graph/badge.svg
|
5 | [cover-url]: https://codecov.io/gh/shellscape/postcss-less
|
6 |
|
7 | [size]: https://packagephobia.now.sh/badge?p=postcss-less
|
8 | [size-url]: https://packagephobia.now.sh/result?p=postcss-less
|
9 |
|
10 | [PostCSS]: https://github.com/postcss/postcss
|
11 | [PostCSS-SCSS]: https://github.com/postcss/postcss-scss
|
12 | [LESS]: http://lesless.org
|
13 | [Autoprefixer]: https://github.com/postcss/autoprefixer
|
14 | [Stylelint]: http://stylelint.io/
|
15 |
|
16 | # postcss-less
|
17 |
|
18 | [![tests][tests]][tests-url]
|
19 | [![cover][cover]][cover-url]
|
20 | [![size][size]][size-url]
|
21 |
|
22 | A [PostCSS] Syntax for parsing [LESS]
|
23 |
|
24 | _Note: This module requires Node v6.14.4+. `poscss-less` is not a LESS compiler. For compiling LESS, please use the official toolset for LESS._
|
25 |
|
26 | ## Install
|
27 |
|
28 | Using npm:
|
29 |
|
30 | ```console
|
31 | npm install postcss-less --save-dev
|
32 | ```
|
33 |
|
34 | Using yarn:
|
35 |
|
36 | ```console
|
37 | yarn add postcss-less --dev
|
38 | ```
|
39 |
|
40 | ## Usage
|
41 |
|
42 | The most common use of `postcss-less` is for applying PostCSS transformations directly to LESS source. eg. ia theme written in LESS which uses [Autoprefixer] to add appropriate vendor prefixes.
|
43 |
|
44 | ```js
|
45 | const syntax = require('postcss-less');
|
46 | postcss(plugins)
|
47 | .process(lessText, { syntax: syntax })
|
48 | .then(function (result) {
|
49 | result.content // LESS with transformations
|
50 | });
|
51 | ```
|
52 |
|
53 | ## LESS Specific Parsing
|
54 |
|
55 | ### `@import`
|
56 |
|
57 | Parsing of LESS-specific `@import` statements and options are supported.
|
58 |
|
59 | ```less
|
60 | @import (option) 'file.less';
|
61 | ```
|
62 |
|
63 | The AST will contain an `AtRule` node with:
|
64 |
|
65 | - an `import: true` property
|
66 | - a `filename: <String>` property containing the imported filename
|
67 | - an `options: <String>` property containing any [import options](http://lesscss.org/features/#import-atrules-feature-import-options) specified
|
68 |
|
69 | ### Inline Comments
|
70 |
|
71 | Parsing of single-line comments in CSS is supported.
|
72 |
|
73 | ```less
|
74 | :root {
|
75 | // Main theme color
|
76 | --color: red;
|
77 | }
|
78 | ```
|
79 |
|
80 | The AST will contain a `Comment` node with an `inline: true` property.
|
81 |
|
82 | ### Mixins
|
83 |
|
84 | Parsing of LESS mixins is supported.
|
85 |
|
86 | ```less
|
87 | .my-mixin {
|
88 | color: black;
|
89 | }
|
90 | ```
|
91 |
|
92 | The AST will contain an `AtRule` node with a `mixin: true` property.
|
93 |
|
94 | #### `!important`
|
95 |
|
96 | Mixins that declare `!important` will contain an `important: true` property on their respective node.
|
97 |
|
98 | ### Variables
|
99 |
|
100 | Parsing of LESS variables is supported.
|
101 |
|
102 | ```less
|
103 | @link-color: #428bca;
|
104 | ```
|
105 |
|
106 | The AST will contain an `AtRule` node with a `variable: true` property.
|
107 |
|
108 | _Note: LESS variables are strictly parsed - a colon (`:`) must immediately follow a variable name._
|
109 |
|
110 | ## Stringifying
|
111 |
|
112 | To process LESS code without PostCSS transformations, custom stringifier
|
113 | should be provided.
|
114 |
|
115 | ```js
|
116 | const postcss = require('postcss');
|
117 | const syntax = require('postcss-less');
|
118 |
|
119 | const less = `
|
120 | // inline comment
|
121 |
|
122 | .container {
|
123 | .mixin-1();
|
124 | .mixin-2;
|
125 | .mixin-3 (@width: 100px) {
|
126 | width: @width;
|
127 | }
|
128 | }
|
129 |
|
130 | .rotation(@deg:5deg){
|
131 | .transform(rotate(@deg));
|
132 | }
|
133 | `;
|
134 |
|
135 | const result = await postcss().process(less, { syntax });
|
136 |
|
137 | // will contain the value of `less`
|
138 | const { content } = result;
|
139 | ```
|
140 |
|
141 | ## Use Cases
|
142 |
|
143 | - Lint LESS code with 3rd-party plugins.
|
144 | - Apply PostCSS transformations (such as [Autoprefixer](https://github.com/postcss/autoprefixer)) directly to the LESS source code
|
145 |
|
146 | ## Meta
|
147 |
|
148 | [CONTRIBUTING](./.github/CONTRIBUTING)
|
149 |
|
150 | [LICENSE (MIT)](./LICENSE)
|