Stylus

https://github.com/stylus/stylus
Admin
Stylus is a dynamic stylesheet preprocessor language that compiles to CSS, offering features like...
Tokens:64,226
Snippets:686
Trust Score:8.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Hash Example: get(hash, key)

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/functions.md

Defines get() to return the value for a key in a hash-like list, returning null if not found. Usage shows retrieving values and a missing key.

```stylus
get(hash, key)
  return pair[1] if pair[0] == key for pair in hash
```

```stylus
hash = (one 1) (two 2) (three 3)

get(hash, two)
// => 2

get(hash, three)
// => 3

get(hash, something)
// => null
```

--------------------------------

### Install dependencies and mocha globally

Source: https://github.com/stylus/stylus/blob/dev/Contributing.md

Run these commands at the project root before executing tests. The first installs dependencies; the second installs mocha globally for more verbose output.

```bash
npm install
# for a more verbose output you can install mocha at a global level
npm install mocha -g
```

--------------------------------

### CSS example with vendor prefixes

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Standard CSS example showing a body font rule and a button with border-radius, including vendor prefixes.

```css
body {
  font: 12px Helvetica, Arial, sans-serif;
}
a.button {
  -webkit-border-radius: 5px;
  -moz-border-radius: 5px;
  border-radius: 5px;
}
```

--------------------------------

### Install Stylus globally using npm

Source: https://github.com/stylus/stylus/blob/dev/Readme.md

Install the Stylus preprocessor globally on your system via npm. This command needs administrative or appropriate permissions depending on your system configuration.

```bash
$ npm install stylus -g

```

--------------------------------

### Get dependencies with .deps()

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/js.md

Returns an array of dependencies (import files). The example shows that .deps() returns the imported filenames with the .styl extension.

```stylus
stylus('@import "a"; @import "b"')
  .deps();

// => ['a.styl', 'b.styl']
```

--------------------------------

### Install Stylus globally with npm or pnpm

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Install Stylus globally using either npm or pnpm. Requires Node.js and npm to be installed on your system.

```bash
# npm
$ npm install stylus -g

# pnpm
$ pnpm add -g stylus
```

--------------------------------

### Stylus import and mixin usage

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Stylus example demonstrating importing a vendor file and using the border-radius mixin.

```stylus
@import 'vendor'

body
  font: 12px Helvetica, Arial, sans-serif

a.button
  border-radius: 5px
```

--------------------------------

### Postfix for-loop examples

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/iteration.md

Same sum and join functions but using the postfix 'for' syntax, where the loop appears after the statement.

```stylus
sum(nums)
  sum = 0
  sum += n for n in nums


join(delim, args)
  buf = ''
  buf += i ? delim + arg : arg for arg, i in args
```

--------------------------------

### current-media(): get current @media rule

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the string of the current block's @media rule, or '' if there is no @media above the block. The example shows the output for a media query with only screen and min-width.

```stylus
@media only screen and (min-width: 1024px)
  current-media()
// => '@media (only screen and (min-width: (1024px)))'
```

--------------------------------

### Install styl.lang for gedit (gtksourceview 2.0/3.0)

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/gedit.md

Install the Stylus language specification for GtkSourceView. The first two commands download styl.lang to the appropriate language-specs folder for gtksourceview 2.0 or 3.0 (gedit 3.0). The final command updates the MIME database so gedit recognizes .styl files.

```bash
mkdir -p ~/.local/share/gtksourceview-2.0/language-specs/ && wget https://raw.github.com/stylus/stylus/master/editors/gedit/styl.lang -O ~/.local/share/gtksourceview-2.0/language-specs/styl.lang
```

```bash
mkdir -p ~/.local/share/gtksourceview-3.0/language-specs/ && wget https://raw.github.com/stylus/stylus/master/editors/gedit/styl.lang -O ~/.local/share/gtksourceview-3.0/language-specs/styl.lang
```

```bash
cd ~/.local/share
update-mime-database mime
```

--------------------------------

### Postfix for-loop example

Source: https://github.com/stylus/stylus/blob/dev/Changelog.md

Postfix for-loop syntax in Stylus. The loop iterates over nums and returns n if it is even.

```stylus
return n if n % 2 == 0 for n in nums
```

--------------------------------

### Stylus example without braces or semi-colons

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Stylus example omitting both braces and semi-colons.

```stylus
body
  font: 12px Helvetica, Arial, sans-serif

a.button
  -webkit-border-radius: 5px
  -moz-border-radius: 5px
  border-radius: 5px
```

--------------------------------

### Stylus CSS-style syntax examples

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/css-style.md

These four Stylus examples show the same border-radius mixin and body/form styles written in different syntaxes: indented, CSS-style with braces/colons/semicolons, a mixed indentation variant, and a fully mixed example. They illustrate that Stylus accepts both indented and CSS-like syntax, and that the two can be combined in one file.

```stylus
border-radius()
  -webkit-border-radius arguments
  -moz-border-radius arguments
  border-radius arguments

body a
  font 12px/1.4 "Lucida Grande", Arial, sans-serif
  background black
  color #ccc

form input
  padding 5px
  border 1px solid
  border-radius 5px
```

```stylus
border-radius() {
  -webkit-border-radius: arguments;
  -moz-border-radius: arguments;
  border-radius: arguments;
}

body a {
  font: 12px/1.4 "Lucida Grande", Arial, sans-serif;
  background: black;
  color: #ccc;
}

form input {
  padding: 5px;
  border: 1px solid;
  border-radius: 5px;
}
```

```stylus
      border-radius() {
        -webkit-border-radius: arguments;
        -moz-border-radius: arguments;
        border-radius: arguments;
      }

  body a
  {
    font: 12px/1.4 "Lucida Grande", Arial, sans-serif;
      background: black;
    color: #ccc;
  }

      form input {
        padding: 5px;
    border: 1px solid;
        border-radius: 5px;
        }
```

```stylus
border-radius()
  -webkit-border-radius: arguments;
  -moz-border-radius: arguments;
  border-radius: arguments;

body a {
  font: 12px/1.4 "Lucida Grande", Arial, sans-serif;
  background: black;
  color: #ccc;
}

form input
  padding: 5px;
  border: 1px solid;
  border-radius: 5px;
```

--------------------------------

### image-size(path): get image dimensions

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the width and height of an image found at the given path, using the same lookup as @import (altered by the paths setting). The example defines width and height helpers and shows image-size returning dimensions and comparing the first element to width.

```stylus
width(img)
  return image-size(img)[0]

height(img)
  return image-size(img)[1]

image-size('tux.png')
// => 405px 250px

image-size('tux.png')[0] == width('tux.png')
// => true
```

--------------------------------

### Watch and compile Stylus file with stylus -w

Source: https://github.com/stylus/stylus/blob/dev/Readme.md

Use the command line to watch and compile a Stylus style file into CSS. This example watches 'style.styl' and outputs 'style.css'.

```bash
stylus -w style.styl -o style.css

```

--------------------------------

### Stylus example without braces

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Stylus version of the CSS example, omitting braces but keeping semi-colons.

```stylus
body
  font: 12px Helvetica, Arial, sans-serif;

a.button
  -webkit-border-radius: 5px;
  -moz-border-radius: 5px;
  border-radius: 5px;
```

--------------------------------

### Library directory structure for index imports

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/import.md

Example directory structure for a Stylus library that supports index imports. When you @import 'blueprint', Stylus resolves either blueprint.styl or blueprint/index.styl.

```bash
./tablet
  |-- index.styl
  |-- vendor.styl
  |-- buttons.styl
  |-- images.styl
```

--------------------------------

### Argument Defaults: add() with default b = a and b = unit(a, px)

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/functions.md

Shows argument defaults, including defaulting to an earlier argument and using a function call for the default. The first example demonstrates the default behavior with output comments.

```stylus
add(a, b = a)
  a + b

add(10, 5)
// => 15

add(10)
// => 20
```

```stylus
add(a, b = unit(a, px))
  a + b
```

--------------------------------

### Chained selectors example

Source: https://github.com/stylus/stylus/blob/dev/Changelog.md

Chaining selectors in Stylus without trailing commas.

```stylus
td:nth-child(2)
td:nth-child(3)
```

--------------------------------

### contrast(top[, bottom]) examples

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the contrast ratio object between two colors. The second argument defaults to #fff. The returned object has a ratio key, and when the bottom color is transparent, it also includes min, max, and error values.

```stylus
contrast(#000, #fff).ratio
// => 21
contrast(#000, rgba(#FFF, 0.5))
// => { "ratio": "13.15;", "error": "-7.85", "min": "5.3", "max": "21" }
```

--------------------------------

### Initial Reference `~/` in Stylus

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/selectors.md

Use the initial reference `~/` at the start of a selector to point to the first nesting level, equivalent to `^[0]`. The example shows a hover state on the root element, and the compiled CSS places the hover on the parent before the nested element.

```stylus
.block
  &__element
    ~/:hover &
      color: red

```

```css
.block:hover .block__element {
  color: #f00;
}

```

--------------------------------

### luminosity(color) examples

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the relative luminance of a color. The examples show that white yields 1, black yields 0, and red yields approximately 0.2126.

```stylus
luminosity(white)
// => 1

luminosity(#000)
// => 0

luminosity(red)
// => 0.2126
```

--------------------------------

### range(start, stop[, step]) - generate list

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns a list of units from `start` to `stop` (included) by given `step`. The `step` argument defaults to `1` if omitted and cannot be `0`.

```stylus
range(1, 6)
// equals to `1..6`
// 1 2 3 4 5 6

range(1, 6, 2)
// 1 3 5

range(-6, -1, 2)
// -6 -4 -2

range(1px, 3px, 0.5px)
// 1px 1.5px 2px 2.5px 3px
```

--------------------------------

### arguments: sum() using arguments local

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/functions.md

Defines sum() that uses the arguments local to sum all passed arguments. The example call returns 15.

```stylus
sum()
  n = 0
  for num in arguments
    n = n + num

sum(1,2,3,4,5)
// => 15
```

--------------------------------

### Stylus optional syntax with variable

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Stylus example showing optional syntax: uses a variable for fonts and mixes CSS braces with Stylus features.

```stylus
fonts = Helvetica, Arial, sans-serif

body {
  padding: 50px;
  font: 14px/1.4 fonts;
}
```

--------------------------------

### transparentify(top[, bottom, alpha]) examples

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the transparent version of a color as if blended over a given bottom color (default #fff). The third argument overrides the autodetected alpha.

```stylus
transparentify(#808080)
// => rgba(0,0,0,0.5)

transparentify(#414141, #000)
// => rgba(255,255,255,0.25)

transparentify(#91974C, #F34949, 0.5)
// => rgba(47,229,79,0.5)
```

--------------------------------

### stylus -i interactive shell

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Starts the Stylus interactive shell (REPL) with the -i or --interactive flag. Only expressions are supported, not selectors. The session shows variable assignment, arithmetic, and rgba() output.

```bash
$ stylus -i
> color = white
=> #fff
> color - rgb(200,50,0)
=> #37cdff
> color
=> #fff
> color -= rgb(200,50,0)
=> #37cdff
> color
=> #37cdff
> rgba(color, 0.5)
=> rgba(55,205,255,0.5)
```

--------------------------------

### stylus --deps test.styl

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Shows how to list dependencies of a compiled Stylus file using the --deps (or -D) flag. The example uses test.styl that imports foo and bar, with foo importing baz. The output lists the import paths in order. Note that dynamically generated paths are not supported.

```stylus
@import 'foo'
@import 'bar'
```

```stylus
@import 'baz'
```

```stylus
$ stylus --deps test.styl
```

```bash
foo.styl
baz.styl
bar.styl
```

--------------------------------

### Postfix conditional example

Source: https://github.com/stylus/stylus/blob/dev/Changelog.md

Postfix conditional syntax in Stylus. The padding property is applied if allow-padding is true.

```stylus
padding 5px if allow-padding
```

--------------------------------

### Get hash keys and values

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/hashes.md

Uses the keys() and values() built-in functions to retrieve all keys and values of a hash.

```stylus
foo = { bar: 'a', baz: 'b' }

keys(foo)
// => 'bar' 'baz'

values(foo)
// => 'a' 'b'
```

--------------------------------

### json(path[, options]) - usage examples

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Loads JSON files into Stylus variables or objects. With hash:true, nested keys are joined with dashes; leave-strings:true preserves string types; optional:true suppresses errors for missing files.

```stylus
json('media-queries.json')

@media small
// => @media screen and (max-width:400px)

@media tablet-landscape
// => @media screen and (min-width:600px) and (orientation:landscape)

vars = json('vars.json', { hash: true })
body
  width: vars.width

vars = json('vars.json', { hash: true, leave-strings: true })
typeof(vars.icon)
// => 'string'

// don't throw an error if the JSON file doesn't exist
optional = json('optional.json', { hash: true, optional: true })
typeof(optional)
// => 'null'
```

--------------------------------

### Compiled CSS for block-level import

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/import.md

Compiled CSS output from the block-level @import example. The imported rules are nested inside the selector and the media query.

```stylus
.foo .bar {
  width: 10px;
}
@media screen and (min-width: 640px) {
  .bar {
    width: 10px;
  }
}
```

--------------------------------

### Postfix conditional example

Source: https://github.com/stylus/stylus/blob/dev/Changelog.md

Postfix conditional operators in Stylus. The property is set if the condition is true and unless false.

```stylus
border-radius: 5px if true unless false;
```

--------------------------------

### Rest parameter mixin for box-shadow

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/vargs.md

Defines a mixin with a rest parameter `args...` that forwards all arguments to multiple properties. The example calls it with `1px 2px 5px #eee` and shows the resulting CSS output.

```stylus
box-shadow(args...)
  -webkit-box-shadow args
  -moz-box-shadow args
  box-shadow args

#login
  box-shadow 1px 2px 5px #eee
```

```css
#login {
  -webkit-box-shadow: 1px 2px 5px #eee;
  -moz-box-shadow: 1px 2px 5px #eee;
  box-shadow: 1px 2px 5px #eee;
}
```

--------------------------------

### Join function with for-loop

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/iteration.md

Joins arguments with a delimiter, skipping the delimiter before the first element. Example 'join(', ', foo bar baz)' returns a string.

```stylus
join(delim, args)
  buf = ''
  for arg, index in args
    if index
      buf += delim + arg
    else
      buf += arg

join(', ', foo bar baz)
// => "foo, bar, baz"
```

--------------------------------

### Stylus: Extending placeholder selectors with output CSS

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/extend.md

Placeholder selectors start with $ and are not output unless extended. Extending them yields compact CSS; unused placeholders like $foo2 are omitted.

```stylus
$foo
  color: #FFF

$foo2
  color: red

.bar
  background: #000
  @extends $foo

.baz
  @extends $foo

```

```css
.bar,
.baz {
  color: #fff;
}
.bar {
  background: #000;
}

```

--------------------------------

### Stylus indentation syntax for unknown at-rules

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/atrules.md

Demonstrates that Stylus supports any unknown at-rules, allowing future CSS at-rules to be written in indentation-based syntax. The example uses @foo and @bar with a nested .baz class, compiling to CSS with braces.

```stylus
@foo
  @bar
    width: 10px

    .baz
      height: 10px
```

```css
@foo {
  @bar {
    width: 10px;
    .baz {
      height: 10px;
    }
  }
}
```

--------------------------------

### Stylus source importing nib

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Stylus source that imports the nib plugin to use its linear-gradient() function. This is the input file for the CLI examples that follow.

```stylus
@import 'nib'

body
  background: linear-gradient(20px top, white, black)
```

--------------------------------

### Block-level @import example

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/import.md

Shows block-level @import inside a selector and inside an @media rule. The imported styles are nested accordingly.

```stylus
.foo
  @import 'bar.styl'

@media screen and (min-width: 640px)
  @import 'bar.styl'
```

--------------------------------

### Serve .styl files from ./public

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/middleware.md

Serve .styl files from ./public using the default middleware options.

```js
var app = connect();

app.middleware(__dirname + '/public');
```

--------------------------------

### Sprintf with multiple values

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/operators.md

Use the sprintf-like `%` operator with multiple values, which must be parenthesized. The example formats a `-webkit-gradient` string with three arguments.

```stylus
'-webkit-gradient(%s, %s, %s)' % (linear (0 0) (0 100%))
// => -webkit-gradient(linear, 0 0, 0 100%)
```

--------------------------------

### Get current compiled selector with selector()

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/selectors.md

Use the built-in selector() bif to get the current compiled selector. The first example returns '.foo' for the .foo rule, and the second returns '.foo:hover' when used inside a &:hover nested rule.

```stylus
.foo
  selector()
  // => '.foo'

.foo
  &:hover
    selector()
  // '.foo:hover'
```

--------------------------------

### Undefined Functions - literal output

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Undefined functions are output as literals. This example defines a helper that returns the literal rgba-stop() call, which is output as-is.

```stylus
stop(pos, rgba)
  rgba-stop(pos, rgba)

stop(50%, orange)
// => rgba-stop(50%, #ffa500)
```

--------------------------------

### Stylus transparent mixin call

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Stylus example showing transparent mixins: the border-radius mixin is called without parentheses, using the property-like syntax.

```stylus
border-radius()
  -webkit-border-radius: arguments
  -moz-border-radius: arguments
  border-radius: arguments

body
  font: 12px Helvetica, Arial, sans-serif

a.button
  border-radius: 5px
```

--------------------------------

### substr(val, start, length) - extract substring in Stylus

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns characters from a string or identifier starting at the given position and length. When the input is an identifier, the result is an identifier; when quoted, the result is a quoted string. The example shows nested substr calls producing a color literal.

```stylus
substr(ident, 1, 2)
// => de

substr('string', 1, 2)
// => 'tr'

val = dredd
substr(substr(val, 1), 0, 3)
// => #f00
```

--------------------------------

### Equality and relational operators: == != >= <= > <

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/operators.md

Shows equality and relational operators (==, !=, >=, <=, >, <). Equality operators can equate units, colors, strings, and even identifiers. Only exact values match; for example, 0 == false and null == false are both false.

```stylus
5 == 5
// => true

10 > 5
// => true

#fff == #fff
// => true

true == false
// => false

wahoo == yay
// => false

wahoo == wahoo
// => true

"test" == "test"
// => true

true is true
// => true

'hey' is not 'bye'
// => true

'hey' isnt 'bye'
// => true

(foo bar) == (foo bar)
// => true

(1 2 3) == (1 2 3)
// => true

(1 2 3) == (1 1 3)
// => false
```

--------------------------------

### Stylus CLI usage and options

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Shows the full command-line help for the `stylus` executable, listing all commands and options for converting Stylus to CSS. Use this to see available flags such as `--watch`, `--compress`, and `--sourcemap`.

```bash
Usage: stylus [options] [command] [< in [> out]]
              [file|dir ...]

Commands:

  help [<type>:]<prop> Opens help info at MDC for <prop> in
                        your default browser. Optionally
                        searches other resources of <type>:
                        safari opera w3c ms caniuse quirksmode

Options:

  -i, --interactive       Start interactive REPL
  -u, --use <path>        Utilize the Stylus plugin at <path>
  -U, --inline            Utilize image inlining via data URI support
  -w, --watch             Watch file(s) for changes and re-compile
  -o, --out <dir>         Output to <dir> when passing files
  -C, --css <src> [dest]  Convert CSS input to Stylus
  -I, --include <path>    Add <path> to lookup paths
  -c, --compress          Compress CSS output
  -d, --compare           Display input along with output
  -f, --firebug           Emits debug infos in the generated CSS that
                          can be used by the FireStylus Firebug plugin
  -l, --line-numbers      Emits comments in the generated CSS
                          indicating the corresponding Stylus line
  -m, --sourcemap         Generates a sourcemap in sourcemaps v3 format
  --sourcemap-inline      Inlines sourcemap with full source text in base64 format
  --sourcemap-root <url>  "sourceRoot" property of the generated sourcemap
  --sourcemap-base <path> Base <path> from which sourcemap and all sources are relative
  -P, --prefix [prefix]   Prefix all css classes
  -p, --print             Print out the compiled CSS
  --import <file>         Import stylus <file>
  --include-css           Include regular CSS on @import
  -D, --deps              Display dependencies of the compiled file
  --disable-cache         Disable caching
  --hoist-atrules         Move @import and @charset to the top
  -r, --resolve-url       Resolve relative urls inside imports
  --resolve-url-nocheck   Like --resolve-url but without file existence check
  -V, --version           Display the version of Stylus
  -h, --help              Display help information
```

--------------------------------

### selector(): get compiled current selector

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the compiled current selector, or '&' if called at root level. The example shows selector() inside .foo returning '.foo', and inside &:hover returning '.foo:hover'.

```stylus
.foo
  selector()
// => '.foo'

.foo
  &:hover
    selector()
// '.foo:hover'
```

--------------------------------

### operate(op, left, right): perform operation

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Performs the given operation on the left and right operands. The example uses '+' to add 15 and 5, yielding 20.

```stylus
op = '+'
operate(op, 15, 5)
// => 20
```

--------------------------------

### Stylus indentation syntax for @viewport, @supports, @page

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/atrules.md

Shows how to write common CSS at-rules using Stylus indentation instead of braces. The example includes @viewport, @supports, and @page with nested @top-center. Compiles to standard CSS with braces.

```stylus
@viewport
  color: #00f

@supports (display: flex)
  div
    display: flex

@page :blank
  @top-center
    content: none
```

```css
@viewport {
  color: #00f;
}
@supports (display: flex) {
  div {
    display: flex;
  }
}
@page :blank {
  @top-center {
    content: none;
  }
}
```

--------------------------------

### Relative Reference `../` in Stylus

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/selectors.md

Use the relative reference `../` at the start of a selector to point to the previous compiled selector. The example shows a nested selector that also targets a sibling element, and the compiled CSS includes both the original and the relative reference.

```stylus
.foo
  .bar
    width: 10px

    &,
    ../ .baz
      height: 10px

```

```css
.foo .bar {
  width: 10px;
}
.foo .bar,
.foo .baz {
  height: 10px;
}

```

--------------------------------

### Stylus function with rest arguments

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Stylus in-language function example: defines a sum function that takes a variable number of arguments and returns the total, with a comment showing the output.

```stylus
sum(nums...)
  sum = 0
  sum += n for n in nums

sum(1 2 3 4)
// => 10
```

--------------------------------

### Apply mixin with iteration and interpolation

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/iteration.md

Defines a mixin 'apply' that supports comma-delimited and expression lists, iterating and setting properties. Example usage shows both direct arguments and a list variable.

```stylus
apply(props)
  props = arguments if length(arguments) > 1
  for prop in props
    {prop[0]} prop[1]

body

```

```stylus
body
  apply(one 1, two 2, three 3)

body
  list = (one 1) (two 2) (three 3)
  apply(list)
```

--------------------------------

### +prefix-classes(prefix): prefix classes in block

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Prefixes all classes inside the given Stylus block with the specified prefix. The example prefixes .bar with 'foo-' to produce .foo-bar.

```stylus
+prefix-classes('foo-')
  .bar
    width: 10px
```

```css
.foo-bar {
  width: 10px;
}
```

--------------------------------

### lookup(name): get variable value by name

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Looks up the value of a variable by its name passed as a string, returning null if undefined. The example dynamically generates class names and uses lookup to fetch font-size values, yielding the shown CSS.

```stylus
font-size-1 = 10px
font-size-2 = 20px
font-size-3 = 30px

for i in 1..3
  .text-{i}
    font-size: lookup('font-size-' + i)
```

```css
.text-1 {
  font-size: 10px;
}
.text-2 {
  font-size: 20px;
}
.text-3 {
  font-size: 30px;
}
```

--------------------------------

### Additive operators: + and -

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/operators.md

Demonstrates additive (+) and subtractive (-) operators with unit conversion. Type conversion is applied within unit type classes, or defaults to the literal value. For example, 5s - 2px results in 3s.

```stylus
15px - 5px
// => 10px

5 - 2
// => 3

5in - 50mm
// => 3.031in

5s - 1000ms
// => 4s

20mm + 4in
// => 121.6mm

"foo " + "bar"
// => "foo bar"

"num " + 15
// => "num 15"
```

--------------------------------

### Root Reference `/` in Stylus

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/selectors.md

Use the root reference `/` at the start of a selector to reference the root context, preventing the parent selector from being prepended. The example shows a hover state on both the nested elements and a root-level class, and the compiled CSS includes the root class without a parent prefix.

```stylus
textarea
input
  color #A7A7A7
  &:hover,
  /.is-hovered
    color #000

```

```css
textarea,
input {
  color: #a7a7a7;
}
textarea:hover,
input:hover,
.is-hovered {
  color: #000;
}

```

--------------------------------

### Vendor prefix interpolation with vendor() mixin

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/interpolation.md

Use interpolation with the `{}` syntax to expand vendor-prefixed properties. The `vendor()` mixin takes a property name and arguments, then outputs `-webkit-`, `-moz-`, and unprefixed versions. The `border-radius()` and `box-shadow()` mixins pass their arguments through to `vendor()`. The example applies `border-radius` to a `button` and shows the generated CSS.

```stylus
vendor(prop, args)
  -webkit-{prop} args
  -moz-{prop} args
  {prop} args

border-radius()
  vendor('border-radius', arguments)

box-shadow()
  vendor('box-shadow', arguments)

button
  border-radius 1px 2px / 3px 4px

```

```css
button {
  -webkit-border-radius: 1px 2px / 3px 4px;
  -moz-border-radius: 1px 2px / 3px 4px;
  border-radius: 1px 2px / 3px 4px;
}

```

--------------------------------

### +cache(keys...): create cachable mixins

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Creates a cachable mixin that applies its contents on first call and @extends the first call's selector on subsequent calls with the same params. The example defines a size mixin using +cache and shows the resulting CSS where selectors are grouped by the used property.

```stylus
size($width, $height = $width)
  +cache('w' + $width)
    width: $width
  +cache('h' + $height)
    height: $height

.a
  size: 10px 20px
.b
  size: 10px 2em
.c
  size: 1px 2em
```

```css
.a,
.b {
  width: 10px;
}
.a {
  height: 20px;
}
.b,
.c {
  height: 2em;
}
.c {
  width: 1px;
}
```

--------------------------------

### Attempt to render with stylus via stdio

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

First attempt to render the Stylus file via stdio. Fails because Stylus cannot find the nib module.

```bash
$ stylus < test.styl
```

--------------------------------

### Product directory structure for glob import

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/import.md

Directory structure that the glob @import 'product/*' would import from. All .styl files in the product directory are included.

```bash
./product
  |-- body.styl
  |-- foot.styl
  |-- head.styl
```

--------------------------------

### Reference files for Stylus internals

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/js.md

Lists the source files for further reference until documentation is complete.

```bash
- `lib/nodes/*`
- `lib/utils.js`
```

--------------------------------

### Create a sourcemap with the --sourcemap flag

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/sourcemaps.md

Generates a sourcemap for style.styl, producing style.css and style.css.map as siblings, and appends a sourcemap link to style.css. Use the -m flag (or --sourcemap) with a Stylus file.

```bash
stylus -m style.styl
```

--------------------------------

### use(path, options) - pass options

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Passes an optional hash object as the second argument to the use() function, providing options to the plugin.

```js
use("plugins/add.js", { foo: bar })
```

--------------------------------

### json() - sample media-queries.json

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Sample JSON file used with the json() function. Nested object keys are joined with a dash, so tablet.landscape becomes tablet-landscape.

```json
{
    "small": "screen and (max-width:400px)",
    "tablet": {
        "landscape": "screen and (min-width:600px) and (orientation:landscape)",
        "portrait": "screen and (min-width:600px) and (orientation:portrait)"
    }
}
```

--------------------------------

### In operator example

Source: https://github.com/stylus/stylus/blob/dev/Changelog.md

The 'in' operator in Stylus checks if a value is in a list.

```stylus
padding in props
```

--------------------------------

### Include Stylus paths with .include()

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/js.md

Use `.include()` as a progressive alternative to `.set('paths',...)` to expose external Stylus libraries. Each `.include()` adds a path; here it includes the `nib` library path and a mixins directory from the home environment. The `.render(...)` call is left incomplete in the source.

```js
stylus(str)
  .include(require('nib').path)
  .include(process.env.HOME + '/mixins')
  .render(...)
```

--------------------------------

### In operator example

Source: https://github.com/stylus/stylus/blob/dev/Changelog.md

The 'in' operator in Stylus checks if a value is in a list.

```stylus
3 in nums
```

--------------------------------

### add-property() basic example with output

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Shows the basic use of add-property() to add a property to the closest block. The Stylus source defines a function that adds 'bar' with value 1 2 3 and returns 'bar', then applies it to body's foo property. The CSS output shows the added property and the returned value.

```stylus
something()
  add-property('bar', 1 2 3)
  s('bar')

body
  foo: something()
```

```css
body {
  bar: 1 2 3;
  foo: bar;
}
```

--------------------------------

### stylus help <prop>

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Opens the default browser on OS X to display help documentation for the given CSS property. Replace box-shadow with any property name.

```stylus
$ stylus help box-shadow
```

--------------------------------

### Render Stylus progressively with .set() and .render()

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/js.md

Use this snippet for a progressive, chainable rendering approach. It sets the `filename` option via `.set()` and calls `.render()` with a callback. The callback receives `err` and `css`; the comment indicates where to add logic.

```js
var stylus = require('stylus');

stylus(str)
  .set('filename', 'nesting.css')
  .render(function(err, css){
    // logic
  });
```

--------------------------------

### Multi-line buffered comment syntax

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/comments.md

Multi-line comments starting with /*! are always output, even when compression is enabled.

```stylus
/*!
 * Adds the given numbers together.
 */
add(a, b)
  a + b

```

--------------------------------

### Sourcemap options: comment, inline, sourceRoot, basePath

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/sourcemaps.md

Lists the available sourcemap options: comment (default true), inline (default false), sourceRoot, and basePath (default '.'). These options control the generated sourcemap's behavior.

```bash
`comment`     Adds a comment with the `sourceMappingURL` to the generated CSS (default: `true`)
`inline`      Inlines the sourcemap with full source text in base64 format (default: `false`)
`sourceRoot`  "sourceRoot" property of the generated sourcemap
`basePath`    Base path from which sourcemap and all sources are relative (default: `.`)
```

--------------------------------

### Get hash length with length()

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/hashes.md

Uses the length() function to count the number of key-value pairs in a hash.

```stylus
foo = { bar: 'a', baz: 'b' }

length(foo)
// => 2
```

--------------------------------

### Compile Stylus directory in place

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Compiles all Stylus files in the 'css' directory and outputs .css files in the same directory.

```bash
$ stylus css
```

--------------------------------

### Get hash value with brackets

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/hashes.md

Retrieves a hash value using brackets with a string variable for any key.

```stylus
foo = { "%": 10 }
baz = "%"

foo[baz]
// => 10
```

--------------------------------

### Variable declaration and usage in SCSS, Less, and Stylus

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/compare.md

Shows how each preprocessor declares a variable and uses it in a color property. SCSS uses $, Less uses @, and Stylus uses no prefix.

```scss
$main-color: #006;
color: $main-color;
```

```less
@main-color: #006;
color: @main-color;
```

```stylus
main-color = #006
color: main-color
```

--------------------------------

### Get hash value with dot syntax

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/hashes.md

Retrieves a hash value using dot syntax for ident keys.

```stylus
foo = { bar: "baz" }

foo.bar
// => "baz"
```

--------------------------------

### Stylus mixin for border-radius

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/index.md

Stylus mixin example: defines a border-radius mixin that uses the arguments variable and applies it to a.button.

```stylus
border-radius()
  -webkit-border-radius: arguments
  -moz-border-radius: arguments
  border-radius: arguments

body
  font: 12px Helvetica, Arial, sans-serif

a.button
  border-radius(5px)
```

--------------------------------

### Subscript operator [] on lists

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/operators.md

Demonstrates the subscript operator `[]` on a list. Indexes are zero-based and negative indexes start from the last element.

```stylus
list = 1 2 3
list[0]
// => 1

list[-1]
// => 3
```

--------------------------------

### String to unit coercion example

Source: https://github.com/stylus/stylus/blob/dev/Changelog.md

String to unit type coercion in Stylus. Adding a string to a unit results in a unit value.

```stylus
5px + "10"
```

--------------------------------

### Watch a file and update sourcemap with -w -m

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/sourcemaps.md

Watches style.styl and regenerates the sourcemap on every save. Combine -w with -m to update the sourcemap automatically.

```bash
stylus -w -m style.styl
```

--------------------------------

### CSS output with --use flag

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Expected output when using --use, with the gradient data URI properly generated.

```css
body {
  background: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAUCAYAAABMDlehAAAABmJLR0QA/wD/AP+gvaeTAAAAI0lEQVQImWP4+fPnf6bPnz8zMH58oUBwkIjKJBgYGNj+w8Aphk4blt0EcMAAAAASUVORK5CYII=");
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0, #fff), color-stop(1, #000));
  background: -webkit-linear-gradient(top, #fff 0%, #000 100%);
  background: -moz-linear-gradient(top, #fff 0%, #000 100%);
  background: linear-gradient(top, #fff 0%, #000 100%);
}
```

--------------------------------

### Sprintf with % operator

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/operators.md

Use the sprintf-like `%` operator to generate a literal value, passing arguments through the `s()` built-in. The example formats a string with a color value.

```stylus
'X::Microsoft::Crap(%s)' % #fc0
// => X::Microsoft::Crap(#fc0)
```

--------------------------------

### .deps()

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/js.md

Returns an array of dependencies (import files) used in the stylesheet.

```APIDOC
## .deps()

### Description
Returns an array of dependencies (import files) used in the stylesheet.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
```stylus
stylus('@import "a"; @import "b"')
  .deps();
```

### Response
- **dependencies** (array) - List of imported file paths.

### Response Example
```js
// => ['a.styl', 'b.styl']
```
```

--------------------------------

### extname(path)

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the file extension of a path, including the leading dot. For 'images/foo.png' it returns ".png".

```stylus
extname('images/foo.png')
// => ".png"
```

--------------------------------

### Interactive Stylus session

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Starts an interactive Stylus session. Type Stylus code and press CTRL-D to signal end-of-input and compile to CSS.

```bash
$ stylus
body
  color red
  font 14px Arial, sans-serif
```

--------------------------------

### render(str, options, callback)

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/js.md

Renders Stylus source code to CSS. Accepts a string of Stylus code, optional options object, and a callback that receives the rendered CSS or an error.

```APIDOC
## render(str, options, callback)

### Description
Renders the given Stylus string to CSS. The optional `options` object can include settings such as `filename` for better error reporting. The callback receives an error and the resulting CSS.

### Method
render

### Parameters
- **str** (string) - Required - The Stylus source code to render.
- **options** (object) - Optional - An object containing settings such as `filename`.
- **callback** (function) - Required - A callback function `function(err, css)` that receives an error (if any) and the rendered CSS.

### Request Example
```js
var stylus = require('stylus');

stylus.render(str, { filename: 'nesting.css' }, function(err, css){
  if (err) throw err;
  console.log(css);
});
```

### Response
#### Success Response
- **css** (string) - The rendered CSS output.

#### Response Example
```js
function(err, css){
  if (err) throw err;
  console.log(css);
}
```
```

--------------------------------

### Logical operators && || and or in Stylus

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/operators.md

Logical operators && and || (aliased as and/or) with the same precedence. The examples show short-circuit evaluation and combining with the 'is a' operator.

```stylus
5 && 3
// => 3

0 || 5
// => 5

0 && 5
// => 0

#fff is a 'rgba' and 15 is a 'unit'
// => true
```

--------------------------------

### product/index.styl content

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/import.md

Content of ./product/index.styl. When using @require 'product/*', each individual sheet is included only once.

```stylus
@require 'head'
@require 'body'
@require 'foot'
```

--------------------------------

### pathjoin(...)

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Joins path components. The first call joins 'images' and 'foo.png' to produce "images/foo.png". The second shows combining dirname, basename with extension removal, and a custom suffix to create 'images/foo_thumb.png'.

```stylus
pathjoin('images', 'foo.png')
// => "images/foo.png"

path = 'images/foo.png'
ext = extname(path)
pathjoin(dirname(path), basename(path, ext) + _thumb + ext)
// => 'images/foo_thumb.png'
```

--------------------------------

### Prefix all classes with --prefix

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Prefixes all generated classes with the given prefix. The command uses --prefix foo- to prefix the class .bar to .foo-bar. All classes, including interpolated and extended ones, are prefixed.

```bash
$ stylus --prefix foo-
```

```stylus
.bar
  width: 10px
```

```css
.foo-bar {
  width: 10px;
}
```

--------------------------------

### Set Stylus options with .set()

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/js.md

Use `.set()` to apply settings such as `filename` and `paths`. The `paths` option accepts an array of directories for imports. This snippet shows the chainable syntax.

```js
.set('filename', __dirname + '/test.styl')
.set('paths', [__dirname, __dirname + '/mixins'])
```

--------------------------------

### For loop with strings and interpolation

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/iteration.md

Uses a range (1..10) to generate box classes and keyframes with interpolation for numbers, including an example of animation and positioning.

```stylus
for num in (1..10)
  .box{num}
    animation: box + num 5s infinite
  
  @keyframes box{num}
    0%   { left: 0px }
    100% { left: (num * 30px) }
```

--------------------------------

### error(msg) - add() expects units

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Terminates Stylus with the given error message. In this example, the error is raised when either argument is not a unit, preventing invalid addition.

```stylus
add(a, b)
  unless a is a 'unit' and b is a 'unit'
    error('add() expects units')
  a + b
```

--------------------------------

### Compile multiple Stylus files

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/executable.md

Compiles multiple Stylus files in one command. Each input file produces a corresponding .css file in the same directory.

```bash
$ stylus one.styl two.styl
```

--------------------------------

### opposite-position(positions): return opposite positions

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/bifs.md

Returns the opposite of the given positions. The examples show right -> left, top left -> bottom right, and the same for string arguments.

```stylus
opposite-position(right)
// => left

opposite-position(top left)
// => bottom right

opposite-position('top' 'left')
// => bottom right
```

--------------------------------

### for/in syntax template

Source: https://github.com/stylus/stylus/blob/dev/docs/docs/iteration.md

Shows the basic form of a for/in loop in Stylus: 'for <val-name> [, <key-name>] in <expression>'.

```bash
for <val-name> [, <key-name>] in <expression>
```
Tokens:
Raw