node_modules/jade/support/stylus/docs/import.md

   1
   2 ## Import
   3
   4  Stylus supports both literal __@import__ for CSS, as well as dynamic importing of other Stylus sheets.
   5
   6 ### Literal CSS
   7
   8   Any filename with the extension `.css` will become a literal, for example:
   9
  10      @import "reset.css"
  11
  12 will render to the literal css __@import__ shown below:
  13
  14      @import "reset.css"
  15
  16 ### Stylus Import
  17
  18  When using __@import__ without the `.css` extension, it is assumed to be a Stylus sheet, for example `@import "mixins/border-radius"`.
  19
  20  __@import__ works by iterating an array of directories, and seeing if this file lives in any of them, similar to node's `require.paths`. This array defaults to a single path which is derived from the `filename` option's dirname. So if your filename is `/tmp/testing/stylus/main.styl`, then import will look in `/tmp/testing/stylus/`.
  21
  22  __@import__ also supports index styles, meaning if you `@import blueprint`, it will resolve either `blueprint.styl` or `blueprint/index.styl`, useful for libraries to expose all of their features, but still allow a subset of the library to be imported. For example a common lib structure might be:
  23
  24     ./tablet
  25       |-- index.styl
  26       |-- vendor.styl
  27       |-- buttons.styl
  28       |-- images.styl
  29
  30  In the example below we set the `paths` options to provide additional paths to Stylus. Within `./test.styl` we could then `@import "mixins/border-radius"` or `@import "border-radius"` since `./mixins` is exposed to Stylus.
  31
  32       /**
  33        * Module dependencies.
  34        */
  35
  36       var stylus = require('../')
  37         , str = require('fs').readFileSync(__dirname + '/test.styl', 'utf8');
  38
  39       var paths = [
  40           __dirname
  41         , __dirname + '/mixins'
  42       ];
  43
  44       stylus(str)
  45         .set('filename', __dirname + '/test.styl')
  46         .set('paths', paths)
  47         .render(function(err, css){
  48           if (err) throw err;
  49           console.log(css);
  50         });
  51
  52 ### JavaScript Import API
  53
  54  When using the `.import(path)` method, these imports are deferred until evaluation:
  55
  56        var stylus = require('../')
  57          , str = require('fs').readFileSync(__dirname + '/test.styl', 'utf8');
  58
  59        stylus(str)
  60          .set('filename', __dirname + '/test.styl')
  61          .import('mixins/vendor')
  62          .render(function(err, css){
  63          if (err) throw err;
  64          console.log(css);
  65        });
  66
  67  The following are essentially equivalent:
  68
  69      @import 'mixins/vendor'
  70
  71 and
  72      .import('mixins/vendor')
  73