Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/postcss/sugarss
Indent-based CSS syntax for PostCSS
https://github.com/postcss/sugarss
Last synced: 5 days ago
JSON representation
Indent-based CSS syntax for PostCSS
- Host: GitHub
- URL: https://github.com/postcss/sugarss
- Owner: postcss
- License: mit
- Created: 2016-01-04T15:15:27.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2024-07-18T14:18:46.000Z (6 months ago)
- Last Synced: 2024-10-29T15:14:09.133Z (3 months ago)
- Language: JavaScript
- Homepage:
- Size: 1.01 MB
- Stars: 711
- Watchers: 24
- Forks: 39
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# SugarSS
Indent-based CSS syntax for [PostCSS].
```sass
a
color: blue
.multiline,
.selector
box-shadow: 1px 0 9px rgba(0, 0, 0, .4),
1px 0 3px rgba(0, 0, 0, .6)
// Mobile
@media (max-width: 400px)
.body
padding: 0 10px
```
As any PostCSS custom syntax, SugarSS has source map, [stylelint]
and [postcss-sorting] support out-of-box.
It was designed to be used with [postcss-simple-vars] and [postcss-nested].
But you can use it with any PostCSS plugins
or use it without any PostCSS plugins.
With [postcss-mixins] you can use `@mixin` syntax as in Sass.
[postcss-mixins]: https://github.com/postcss/postcss-mixins
[postcss-nested]: https://github.com/postcss/postcss-nested
[postcss-simple-vars]: https://github.com/postcss/postcss-simple-vars
[postcss-sorting]: https://github.com/hudochenkov/postcss-sorting
[stylelint]: http://stylelint.io/
[PostCSS]: https://github.com/postcss/postcss
## Syntax
SugarSS MIME-type is `text/x-sugarss` with `.sss` file extension.
### Indent
We recommend 2 spaces indent. However, SugarSS autodetects indent
and can be used with tabs or spaces.
But it is prohibited to mix spaces and tabs in SugarSS sources.
### Multiline
SugarSS was designed to have intuitively multiline selectors and declaration
values.
There are 3 rules for any types of nodes:
```sass
// 1. New line inside brackets will be ignored
@supports ( (display: flex) and
(display: grid) )
// 2. Comma at the end of the line
@media (max-width: 400px),
(max-height: 800px)
// 3. Backslash before new line
@media screen and \
(min-width: 600px)
```
In a selector you can put a new line anywhere. Just keep same indent
for every line of selector:
```sass
.parent >
.child
color: black
```
In a declaration value you can put a new line anywhere. Just keep a bigger indent
for the value:
```sass
.one
background: linear-gradient(rgba(0, 0, 0, 0), black)
linear-gradient(red, rgba(255, 0, 0, 0))
.two
background:
linear-gradient(rgba(0, 0, 0, 0), black)
linear-gradient(red, rgba(255, 0, 0, 0))
```
### Comments
SugarSS supports two types of comments:
```sass
/*
Multiline comments
*/
// Inline comments
```
There is no “silent” comment in SugarSS. Output CSS will contain all comments
from `.sss` source. But you can use [postcss-discard-comments]
for Sass’s silent/loud comments behaviour.
[postcss-discard-comments]: https://www.npmjs.com/package/postcss-discard-comments
### Rule and Declarations
SugarSS separates selectors and declarations by `:\s` or `:\n` token.
So you must write a space after the property name: `color: black` is good,
`color:black` is prohibited.
### Other
SugarSS is just a syntax, it change the way how you write CSS,
but do not add preprocessor features build-in.
Here are PostCSS plugins which could add you preprocessor features:
* **[postcss-simple-vars]** adds variables.
* **[postcss-nested]** adds nested rules.
* **[postcss-import]** adds `@import` directive support.
* **[postcss-import-ext-glob]** extends [postcss-import] path resolver to allow glob usage as a path.
* **[postcss-mixins]** add `@mixin` support.
* **[postcss-functions]** allows you to define own CSS functions in JS.
[postcss-functions]: https://github.com/andyjansson/postcss-functions
[postcss-mixins]: https://github.com/postcss/postcss-mixins
[postcss-import-ext-glob]: https://github.com/dimitrinicolas/postcss-import-ext-glob
[postcss-import]: https://github.com/postcss/postcss-import
[postcss-nested]: https://github.com/postcss/postcss-nested
[postcss-simple-vars]: https://github.com/postcss/postcss-simple-vars
## Text Editors
* SublimeText: [Syntax Highlighting for .SSS SugarSS]
* Atom: [language-postcss], [source-preview-postcss] and [build-sugarss]
* Vim: [vim-sugarss]
* VSCode: [vetur](https://vuejs.github.io/vetur/), and [postcss-sugarss-language](https://github.com/MhMadHamster/vscode-postcss-language)
We are working on syntax highlight support in text editors.
Right now, you can set `Sass` or `Stylus` syntax highlight for `.sss` files.
[Syntax Highlighting for .SSS SugarSS]: https://packagecontrol.io/packages/Syntax%20Highlighting%20for%20SSS%20SugarSS
[source-preview-postcss]: https://atom.io/packages/source-preview-postcss
[language-postcss]: https://atom.io/packages/language-postcss
[build-sugarss]: https://atom.io/packages/build-sugarss
[vim-sugarss]: https://github.com/hhsnopek/vim-sugarss
## Usage
SugarSS needs PostCSS compiler. Install [`postcss-loader`] for webpack,
[`gulp-postcss`] for Gulp, [`postcss-cli`] for npm scripts.
[Parcel] has build-in support for PostCSS.
Then install SugarSS: `npm install --save-dev postcss sugarss` if you use npm
and `yarn add --dev postcss sugarss` if you use Yarn.
Then create `.postcssrc` file:
```json
{
"parser": "sugarss",
"plugins": {
"postcss-simple-vars": {}
}
}
```
[`postcss-loader`]: https://github.com/postcss/postcss-loader
[`gulp-postcss`]: https://github.com/postcss/gulp-postcss
[`postcss-cli`]: https://github.com/postcss/postcss-cli
[Parcel]: https://parceljs.org/transforms.html
### Imports
If you doesn’t use Webpack or Parcel, you need some PostCSS plugin
to process `@import` directives.
If you want `@import`, install [postcss-import] and add it to `.postcssrc` file:
```diff js
{
"parser": "sugarss",
"plugins": {
+ "postcss-import": {},
"postcss-simple-vars": {}
}
}
```
[postcss-import]: https://github.com/postcss/postcss-import
### Mixins
For mixins support, install [postcss-mixins] and add it to `.postcssrc` file:
```diff js
{
"parser": "sugarss",
"plugins": {
+ "postcss-mixins": {
+ "mixinsDir": "./mixins"
+ },
"postcss-simple-vars": {}
}
}
```
Now you can define your mixins in `mixins/` dir.
For example create `mixins/circle.sss` with:
```sss
@define-mixin circle $size
border-radius: 50%
width: $size
height: $size
```
### Functions
To define custom functions you need to install [postcss-functions]
and add it to `.postcssrc` file:
```diff js
{
"parser": "sugarss",
"plugins": {
+ "postcss-functions": {
+ "glob": "./functions"
+ },
"postcss-simple-vars": {}
}
}
```
Then you can define functions in `functions/` dir. For example,
`functions/foo.js` will define `foo()` function in CSS:
```js
module.exports = function (args) {
return 'foo'
}
```
### SugarSS to SugarSS
Sometimes we use PostCSS not to build CSS, but to fix source files.
For example, to sort properties by [postcss-sorting].
For this cases use the `syntax` option, instead of `parser`:
```js
gulp.task('sort', function () {
return gulp.src('src/**/*.sss')
.pipe(postcss([sorting], { syntax: sugarss }))
.pipe(gulp.dest('src'));
});
```
[postcss-sorting]: https://github.com/hudochenkov/postcss-sorting
### CSS to SugarSS
You can even compile existing CSS sources to SugarSS syntax.
Just use `stringifier` option instead of `parser`:
```js
postcss().process(css, { stringifier: sugarss }).then(function (result) {
result.content // Converted SugarSS content
});
```
## Thanks
Cute project logo was made by [Maria Keller](http://www.mariakellerac.com/).