middleman-kss
middleman-kss
provides KSS helpers for
Middleman. With these helpers, you can easily
insert KSS styleguide blocks. Great for creating styleguides or design
guidelines.
P.S. This gem was mainly created to be used with my middleman-styleguide-template, which I use for creating styleguides and other documentation.
Requirements
middleman-kss
has currently only been tested with Middleman 3.2.0.
Installation
Add this line to your Middleman project Gemfile:
gem 'middleman-kss'
And then execute:
$ bundle
Open your config.rb
and add the required settings:
set :markdown_engine, :redcarpet
activate :kss, :kss_dir => 'stylesheets/external'
Note: The :kss_dir should be set so all the url('...')
s in your CSS map correctly.
Create a styleblocks
-directory under source/
$ mkdir source/styleblocks
And read the next chapter for usage instructions.
Usage
Okay, here's the deal:
- Write your CSS* in KSS
- Insert your CSS into the directory you specified as your
kss_dir
inconfig.rb
- Create individual style blocks into
source/styleblocks
- Name them like this:
_buttons.html.erb
, you know
- Name them like this:
- Include the CSS files in the styleguide HTML
- Use the helper (documentation below) to print the style blocks
See my middleman-styleguide-template for examples!
* You can use Sass, SCSS or LESS, too :)
Configuration
Here is a full extension activation string with all the configuration variables and default options:
activate :kss, :kss_dir => 'stylesheets',
:styleblock_path => 'styleblocks',
:custom_styleguide_block => false,
:styleguide_block_file => '_styleguide_block.html.erb'
If you want to create a custom styleguide block file, refer to the default styleguide block file for help.
Helpers
styleblock <%= styleblock 'filename', [section: '1.1'] %>
Renders the styleblock named filename
.
Optional: section
parameter maps the
rendered styleblock to a KSS section, which will expand the section into a fully
documented KSS styleblock with all the available classes and such.
Examples:
<%= styleblock 'buttons' %>
<%= styleblock 'buttons', section: '1.1' %>
Contributing
Contributions are most welcome! And well-tested and documented contributions are more welcome than others ;)
- Fork the repository
-
Create a 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 a pull request