Simple toolkit to generates Less, Sass/Scss & Stylus libraries defined through YAML.
Install the module with: npm install librarianowl
librarianowl = require 'librarianowl'
# compile the library
librarianowl.library "src", "lib",
helpers: "helpers.js"
template: "template-lib.hbs"
# compile the documenation
librarianowl.documentation "src", "docs",
helpers: "helpers.js"
template: "template-docs.hbs"
# compile the examples
librarianowl.examples "src", "examples",
helpers: "helpers.js"
template: "template-examples.hbs"
imports: (syntax) ->
switch syntax
when "sass" then return "@import '../../lib/#{syntax}/cssowl'"
when "scss" then return "@import '../../lib/#{syntax}/cssowl';"
when "less" then return "@import '../../lib/#{syntax}/cssowl';"
when "styl" then return "@import '../../lib/#{syntax}/cssowl'"
Librarianowl is based on the simple idea to write one YAML file per mixin with it's code in each syntax together with a shared documentation and example. Librarianowl will then generate each library with your custom Handlebars template or a default one.
The same can be done with the documentation. This too will be rendered with your custom Handlebars template or the default one. With this approach we try to keep it as simple as possible to make it easier to integrate the documentations into you own layout.
Librarianowl was built to work with the same namespace concept that has been used to generate cssowl. Thus you'll need to structure your YAML file in the same way like:
src
└── cssowl
├── _imports.yml
├── position
│ ├── absolute-inside.yml
│ ├── absolute-outside.yml
│ └── absolute.yml
└── sprite
├── _imports.yml
├── absolute-inside.yml
├── absolute-outside.yml
├── absolute.yml
├── after-absolute-inside.yml
├── after-absolute-outside.yml
├── after-absolute.yml
├── after-float.yml
├── after-inline.yml
├── after.yml
├── before-absolute-inside.yml
├── before-absolute-outside.yml
├── before-absolute.yml
├── before-float.yml
├── before-inline.yml
├── before.yml
├── display-block.yml
├── display-inline.yml
├── display.yml
├── float-left.yml
├── float-right.yml
├── replace-block.yml
├── replace-inline.yml
└── replace.yml
Compiled as library this will look like:
lib
├── less
│ ├── cssowl
│ │ ├── position.less
│ │ └── sprite.less
│ └── cssowl.less
├── sass
│ ├── cssowl
│ │ ├── position.sass
│ │ └── sprite.sass
│ └── cssowl.sass
├── scss
│ ├── cssowl
│ │ ├── position.scss
│ │ └── sprite.scss
│ └── cssowl.scss
└── styl
├── cssowl
│ ├── position.styl
│ └── sprite.styl
└── cssowl.styl
And compiled as documentation it'll look like:
docs
└── cssowl
├── position
│ ├── absolute-inside.html
│ ├── absolute-outside.html
│ └── absolute.html
└── sprite
├── absolute-inside.html
├── absolute-outside.html
├── absolute.html
├── after-absolute-inside.html
├── after-absolute-outside.html
├── after-absolute.html
├── after-float.html
├── after-inline.html
├── after.html
├── before-absolute-inside.html
├── before-absolute-outside.html
├── before-absolute.html
├── before-float.html
├── before-inline.html
├── before.html
├── display-block.html
├── display-inline.html
├── display.html
├── float-left.html
├── float-right.html
├── replace-block.html
├── replace-inline.html
└── replace.html
Taking the src/cssowl/sprite/display.yml file as an example a definition might look like this:
description: |
Displays an element with it's *width*, *height*, *background-image* and *background-position*.
mixin:
parameters:
x: position of the element
y: position of the element
width: element width
height: element height
src: background image source
less: |
.cssowl-sprite-display(@x, @y, @width, @height, @src) {
width: @width;
height: @height;
background-image: @src;
background-position: @x @y;
background-repeat: no-repeat;
}
sass: |
@mixin cssowl-sprite-display($x, $y, $width, $height, $src)
width: $width
height: $height
background-image: $src
background-position: $x $y
background-repeat: no-repeat
scss: |
@mixin cssowl-sprite-display($x, $y, $width, $height, $src) {
width: $width;
height: $height;
background-image: $src;
background-position: $x $y;
background-repeat: no-repeat;
}
styl: |
cssowl-sprite-display(x, y, width, height, src)
width: width
height: height
background-image: src
background-position: x y
background-repeat: no-repeat
examples:
sass: |
.example-display
+cssowl-sprite-display(-10px, -10px, 91px, 95px, url("sprite.png"));
scss: |
.example-display {
@include cssowl-sprite-display(-10px, -10px, 91px, 95px, url("sprite.png"));
}
less: |
.example-display {
.cssowl-sprite-display(-10px, -10px, 91px, 95px, url("sprite.png"));
}
styl: |
.example-display
cssowl-sprite-display(-10px, -10px, 91px, 95px, url("sprite.png"))
html: |
.example-display
To import other files and to insure the import definitions are at the top of the file you can place a _imports.yml file into the directory that looks something like:
imports:
less: |
@import "cssowl/position";
@import "cssowl/sprite";
sass: |
@import "cssowl/position"
@import "cssowl/sprite"
scss: |
@import "cssowl/position";
@import "cssowl/sprite";
styl: |
@import "cssowl/position"
@import "cssowl/sprite"
###
@param {String} source Source directory
@param {String} target Target directory
@param {Object} options Optional options
###
library: (source, target, options={}) ->
...
Type: String
Default: librarianowl/templates/library.hbs
Handlebars template file to render the library file.
// {{{description}}}
{{#each mixin.parameters}}
// {{@key}}: {{{this}}}
{{/each}}
{{{mixin.syntax}}}
Type: Object String
Default: {}
You can define you custom helpers that will be available with the Handlebars template rendering. It can be either a object containing each helper or a external file in which you define your helpers:
# Helpers as an object
librarianowl.library "src", "docs",
helpers:
"trim": (val) ->
return val.trim()
# Helpers in a seperate file
librarianowl.library "src", "docs",
helpers: "helpers.js"
Type: Function
Default: false
You can modify the target filename.
librarianowl.library "src", "docs",
filename: (item, syntax) ->
return "#{item.basename}.#{syntax}"
###
@param {String} source Source directory
@param {String} target Target directory
@param {Object} options Optional options
###
documentation: (source, target, options={}) ->
...
Type: String
Default: librarianowl/templates/documentation.hbs
Handlebars template file to render the documentation file.
<h2>{{mixinName}}</h2>
<p>{{{description}}}</p>
<ul class="nav nav-tabs">
<li class="active">
<a href="#example-{{{basename}}}-sass">Sass</a>
</li>
<li>
<a href="#example-{{{basename}}}-scss">Scss</a>
</li>
<li>
<a href="#example-{{{basename}}}-less">Less</a>
</li>
<li>
<a href="#example-{{{basename}}}-styl">Stylus</a>
</li>
<li>
<a href="#example-{{{basename}}}-html">Html</a>
</li>
</ul>
<div class="tab-content">
<code id="#example-{{{basename}}}-sass" class="tab-pane active">
{{examples.sass}}
</code>
<code id="#example-{{{basename}}}-scss" class="tab-pane">
{{examples.scss}}
</code>
<code id="#example-{{{basename}}}-less" class="tab-pane">
{{examples.less}}
</code>
<code id="#example-{{{basename}}}-styl" class="tab-pane">
{{examples.styl}}
</code>
<code id="#example-{{{basename}}}-html" class="tab-pane">
{{examples.html}}
</code>
</div>
Type: Object String
Default: {}
You can define you custom helpers that will be available with the Handlebars template rendering. It can be either a object containing each helper or a external file in which you define your helpers:
# Helpers as an object
librarianowl.documentation "src", "docs",
helpers:
"trim": (val) ->
return val.trim()
# Helpers in a seperate file
librarianowl.documentation "src", "docs",
helpers: "helpers.js"
Type: Function
Default: false
You can modify the target filename.
librarianowl.documentation "src", "docs",
filename: (item, syntax) ->
return "#{item.basename}.#{syntax}"
###
@param {String} source Source directory
@param {String} target Target directory
@param {Object} options Optional options
###
examples: (source, target, options={}) ->
...
Type: String
Default: librarianowl/templates/examples.hbs
Handlebars template file to render the documentation file.
{{{examples.syntax}}}
Type: Object String
Default: {}
You can define you custom helpers that will be available with the Handlebars template rendering. It can be either a object containing each helper or a external file in which you define your helpers:
# Helpers as an object
librarianowl.examples "src", "examples",
helpers:
"trim": (val) ->
return val.trim()
# Helpers in a seperate file
librarianowl.examples "src", "examples",
helpers: "helpers.js"
Type: Function
Default: false
You can modify the target filename.
librarianowl.examples "src", "examples",
filename: (item, syntax) ->
return "#{item.basename}.#{syntax}"
Type: Function
Default: false
Return a string that should be prepended to the generated file.
librarianowl.examples "src", "examples",
imports: (syntax) ->
switch syntax
when "sass" then return "@import 'path/to/file'"
when "scss" then return "@import 'path/to/file';"
when "less" then return "@import 'path/to/file';"
when "styl" then return "@import 'path/to/file'"
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Copyright (c) Owl-Stars under the MIT license.