Add special comments to disable processing

Author: hudochenkov

README.md

@@ -32,6 +32,7 @@ Also available as [Sublime Text plugin], [Atom plugin], and [VS Code plugin].
 	* [`preserve-empty-lines-between-children-rules`](#preserve-empty-lines-between-children-rules)
 	* [`empty-lines-before-comment`](#empty-lines-before-comment)
 	* [`empty-lines-after-comment`](#empty-lines-after-comment)
+	* [Disabling in style sheet](#disabling-in-style-sheet)
 	* [Migration from CSSComb](#migration-from-csscomb)
 * [Usage](#usage)
 	* [Text editor](#text-editor)
@@ -504,6 +505,30 @@ Example: `{ "empty-lines-after-comment": 2, "sort-order": [ "..." ] }`
 }
 ```
 
+### Disabling in style sheet
+
+The plugin can be temporarily turned off by using special comments.
+
+```css
+/* postcss-sorting: off */
+.block1 {
+	width: 50px;
+	display: inline-block;
+}
+/* postcss-sorting: on */
+```
+
+Due to plugin nature only comments in the root of stylesheet will affect plugin processing. In this case comments will be treated like regular comments:
+
+```css
+.block5 {
+	/* postcss-sorting: off */
+	width: 20px;
+	display: inline-block;
+	/* postcss-sorting: on */
+}
+```
+
 ### Migration from CSSComb
 
 If you used to use custom sorting order in [CSSComb] you can easily use this sorting order in PostCSS Sorting. `sort-order` option in this plugin is compatible with `sort-order` in CSSComb. Just copy `sort-order` value from CSSComb config to PostCSS Sorting config.

index.js

@@ -221,8 +221,21 @@ module.exports = postcss.plugin('postcss-sorting', function (opts) {
 		var preserveLinesBetweenChildren = opts['preserve-empty-lines-between-children-rules'];
 		var linesBeforeComment = opts['empty-lines-before-comment'];
 		var linesAfterComment = opts['empty-lines-after-comment'];
+		var enableSorting = true;
 
 		css.walk(function (rule) {
+			if (rule.type === 'comment' && rule.parent.type === 'root') {
+				if (rule.text === 'postcss-sorting: on') {
+					enableSorting = true;
+				} else if (rule.text === 'postcss-sorting: off') {
+					enableSorting = false;
+				}
+			}
+
+			if (!enableSorting) {
+				return;
+			}
+
 			// Process only rules and atrules with nodes
 			if ((rule.type === 'rule' || rule.type === 'atrule') && rule.nodes && rule.nodes.length) {
 				// Nodes for sorting

test/fixtures/sorting-disabling.css

@@ -0,0 +1,47 @@
+/* postcss-sorting: off */
+.block1 {
+	width: 50px;
+	display: inline-block;
+}
+/* postcss-sorting: on */
+
+.block2 {
+	width: 40px;
+	display: inline-block;
+}
+
+/* postcss-sorting: off */
+.block3 {
+	width: 20px;
+	display: inline-block;
+
+	/* postcss-sorting: on */
+	.block3-1 {
+		width: 70px;
+		display: block;
+	}
+	/* postcss-sorting: off */
+}
+/* postcss-sorting: on */
+
+.block5 {
+	width: 20px;
+	/* postcss-sorting: off */
+	.block3-1 {
+		width: 70px;
+		display: block;
+	}
+	/* postcss-sorting: on */
+	display: inline-block;
+}
+
+.block4 {
+	width: 30px;
+	display: inline-block;
+}
+
+/* postcss-sorting: off */
+.block6 {
+	width: 30px;
+	display: inline-block;
+}

test/fixtures/sorting-disabling.expected.css

@@ -0,0 +1,48 @@
+/* postcss-sorting: off */
+.block1 {
+	width: 50px;
+	display: inline-block;
+}
+/* postcss-sorting: on */
+
+.block2 {
+	display: inline-block;
+	width: 40px;
+}
+
+/* postcss-sorting: off */
+.block3 {
+	width: 20px;
+	display: inline-block;
+
+	/* postcss-sorting: on */
+	.block3-1 {
+		width: 70px;
+		display: block;
+	}
+	/* postcss-sorting: off */
+}
+/* postcss-sorting: on */
+
+.block5 {
+	/* postcss-sorting: on */
+	display: inline-block;
+	width: 20px;
+
+	/* postcss-sorting: off */
+	.block3-1 {
+		display: block;
+		width: 70px;
+	}
+}
+
+.block4 {
+	display: inline-block;
+	width: 30px;
+}
+
+/* postcss-sorting: off */
+.block6 {
+	width: 30px;
+	display: inline-block;
+}

test/test.js

@@ -276,6 +276,20 @@ test('Should add empty lines after comment', t => {
 	});
 });
 
+test('Should disable/enable sorting by special comments', t => {
+	return run(t, 'sorting-disabling', {
+		'sort-order': [
+			[
+				'display',
+				'width'
+			],
+			[
+				'>child'
+			]
+		]
+	});
+});
+
 // test('Should sort LESS files', t => {
 //     return run(t, 'less.less', {}, 'less');
 // });