thomasdavis / kaleistyleguide

This project aims at making sure your style sheets are fully documented whilst being synchronized with your webpages styles. To do this it actually uses your live stylesheets in so that at anytime you can review how your styleguide looks.

Kalei - Style guide

This project aims at making sure your style sheets are fully documented whilst being synchronized with your webpages styles. To do this it actually uses your live stylesheets in so that at anytime you can review how your styleguide looks.

Main goals and benefits

• Fully documented CSS - No need to explain the benefits
• No dependencies, simply download the repository and run in your browser
• Automatic generation of demo UI components
• Easy access for anyone, designer, developer, manager and users
• Rapid development of projects by allowing developers to find the correct CSS and HTML for any given UI component
• Open sourced so that all great ideas can be included

Getting started

1. Download the repository (git clone git://github.com/kaleistyleguide/kaleistyleguide.git)
2. Serve it on a HTTP server and it should work!
3. Edit js/config.js to point at your own styles.css

Author

Thomas Davis

Contributors

Luke Brooker Richard Barret Sam Pospischil

Inspiration

Kalei is heavily influenced by the following projects and blog posts.

Pea.rs

KSS

StyleDocco

RJ Metrics

Anchoring Your Design Language in a Live Style Guide

Technologies

• marked
• jscssp
• LESS
• cssbeautify
• fixie
• highlight
• backbone
• underscore
• jquery

License

Public domain: http://unlicense.org/

kaleistyleguide's Issues

LESS' :extend not working

Hi,

Kalei looks really nice (no need to explicitly compile the styleguide), but LESS' :extend doesn't seem to work - I tried this:

.media {
  &:extend(.block);
  overflow: hidden;
}

While lessc does compile this correctly, in kalei the :extend seems to be ignored. A mixin does work, though.
Even though :extend was introduced in less 1.4.0 (I think), I also tried to swap out kalei's less.js (1.7.3) with a current one (2.5.0) - that ends up in an almost empty page, just Loading styles?
Am I doing something wrong or how can this be fixed? TIA

Organising sections

Just wondering how the sectioning is currently working? i.e. The h3's in my comments are creating extra sections in the menu but with no content under them.

Good work on this by the way. I do prefer your navigation over Styledocco's and it does seem easier to use in most cases.

Would love the to see the component in iframe functionality that Styledocco has though, as it allows you to see each component in different viewport contexts.

Actually I have a bunch of ideas that I would love to talk to you about haha and I just noticed we are both from Brisbane :)

fork/star links on website points to wrong location

they are pointing at https://github.com/thomasdavis/kaleistyleguide/

How best to document color variables in the style guide?

I am beginning a style guide project, and am looking for more examples of using KSS (which is brilliant, BTW). Right now, I am wondering how best to display 'swatches' of color variables.

I have a variables.less file that includes definitions such as:

@base:#fff;
@baseMed: darken(@base, 5%);
@baseLess: darken(@base, 15%);
@baseMin: darken(@base, 30%);

I could add a table where the cells have bgcolor, or perhaps a set of spans of class swatch, but I am sure others have implemented better solutions that I would prefer to borrow.

Improving CSS example Markup

At the moment a css rule can have example markup on a one line comment which obviously has it's limitations

/*
Markup: <p>Some example</p>
*/

At the top of a css document, you could set a possible template_parser, if none set it will treat everything as HTML

I think we could support everything with relative ease.

Multi line Mustache

Multi line HAML/HTML - http://haml.info/

Possible template_path: some_template.html <- loads it in with require.js

Also include fixie.js so you can save time in your css docs by having it auto populate fields.

License

Please specify a license for Kalei! (maybe MIT?)

Rails gem

s_paths -> does not work -> js error (screenshot)

Improving template system

Two solutions has been proposed:

1. Templates embedded in CSS comments – needs an implementation
2. Templates in external files. – an implementation of this can be seen here https://github.com/karlwestin/kalei/tree/plugin-template (updated tues 29th)

We're also discussing whether to use underscore's erb-style templates or go for mustache or handlebars instead

Different Code From Example

It is possible to put the code block so that is different example.

Example:

Code:
font-family:arial;

@import of web fonts prevents comments from being rendered

If you use a google font or any other web font with the import syntax inside of your css, it prevents all comments and markdown that occur after it from being rendered

Currently shown css file doesn't pick up css from other files.

When having more than one css file, the second css file doesn't pick up the css of the first file. Because we are working with multiple of css file, I'm wondering if there is a way to get css from other css files in the page into the currently loaded css without having to have duplicate the rule throughout your css files.

eg. I have different rules for the same element in both 1.css and 2.css, is it possible to have 2.css having the rules of both 1.css and 2.css instead of just loading css from 2.css?

Integration with asp mvc

Hi, i am having trouble integrating the styleguide with my asp mvc project.

Two things that i am sure is affecting this:

1. the index extension for kalei is .html, but asp mvc uses cshtml
2. Routing in mvc uses the Controller/Action format. I created a styleguide controller but it still doesn't work. Any thought?

Here is my controller:
public ActionResult Index()
{
return View();
}

I put the kalie library in this directory
MyASPProject
--Controllers
--StyleguideController
--Views
--Styleguide
--css
--js
--template
--index.html
--README.md

Submenu active state not set...

minor issue but the active state for the "Headings and paragraphs" section of theme.css is not being set...

Unable to use Kalei to document simple AngularJS examples

I would like to use Kalei to document various Angular directives that render UI widgets in use throughout my app. Unfortunately, it doesn't look like I can get even the simplest Angular examples to work. 😢

I added ng-app to the html tag in index.html, as well as adding the following to the bottom of the body: <script src="../js/angular.min.js">, but the following example in a css file still does not work:

/*
## Widgets

```
<input type="text" ng-model="name" /> {{ name }}
```
*/

The {{ name }} remains displayed literally.

Any clues on getting a basic AngularJS example working within Kalei?

Bombing on large css...

I cloned, pointed to a compressed local CSS, and, well.. here you go

http://198.101.238.147:8899/

Phil

When using fixie, don't output the classname in the code preview

When you add random text using fixie, currently in the code preview the "class="fixie"" still shows up. Would be amazing if this is filtered out (also for images).

The preview window shouldn't wrap content that is wider than the display

I noticed this with the titlebar. the wrapping on the preview made it difficult to know whether the CSS was invalid due to the wrapping of the content preview window.

SASS Support?

Any chance of getting this to work with SASS comments?

Ignoring comments in selected CSS files

I am creating some components on top of Zurb Foundation (imported via ruby gem), which requires me to load the framewor ,but I don't want the comments in the framework to show up in kalei styleguide. Is there a way I can accomplish this? Thanks.

Multiple CSS files without @import

is it possible to have multiple stylesheets with out importing them to the default css file?

We have several css files that we use on specific pages of our site that I want to document. Is it possible to append them to the css_path in the config file?

listing multiple css files in config.js

this doesn't work for me:
css_paths: [ '/styleguide/css/theme.css','/application.css'],

it only reads the first css file not the second.

Display actual CSS in the styleguide

I have a block of CSS (ie: my reset) that I would like to display in the styleguide. Is there a way to accomplish this without rewriting the CSS in a comment?

In the following example, I'd like to output both the comment and the actual CSS to a Kalei styleguide block.

/*
### Reset body line-height to unitless 1.
*/
body {
    line-height: 1;
}

Perhaps there could be a rule where, if a code block is followed immediately by */, it outputs everything until the next code block mark preceeded by /*.

/*
### Reset body line-height to unitless 1.
```*/
body {
    line-height: 1;
}
/*```
*/

To say it differently: Print everything between

```*/

and

/*```

as a block of CSS in the styleguide.

Just one approach - but this feature would be great to have!

Syntax

Hi!

I'm working on StyleDocco, a tool that's similar to Kalei, but runs on Node.js. I really like your approach of running in the browser!

There are some other CSS documentation tools out there, and I think it would be very cool if we could work toward making our syntaxes somewhat compatible with each other, to let users easily try out the different tools without doing too many changes to their existing CSS documentation.

Here is a comparison between different syntaxes:

Kalei

/*
Name: Default button
Description: A simple example showing a default button
Markup: <button class="default">Simple button</button>
*/

StyleDocco

/*
Default button
--------------
A simple example showing a default button

    <button class="default">Simple button</button>
*/

Knyle Style Sheets

/*
A simple example showing a default button

.default          - Default styles

Styleguide 2.1.3.
*/
button.default { }

I think headings are added in Ruby in KSS, and that the markup is assumed from the CSS, but I'm not sure.

Do you know of any other documentation tools?

I am obviously biased toward the syntax I'm using in StyleDocco, but I'm willing to compromise if you find the idea interesting.

Request: CSS Groups

Hi, first of all I think this is brilliant! Thank you for sharing.

I use @groups to jump around in Sublime Text. These were originally made available in CSS Edit (now called Espresso).

Example:
Espresso: http://cl.ly/image/110G3g073H3h
Sublime: http://cl.ly/image/2M0T3r160S3d

I guess my request for now is there any way to ignore certain strings?
In the future, I'd like to make use of them for expandable sections.

css files specified in `external_stylesheets` load after the own css?

I want to base my css code upon normalize.css, so I added the cdn link to the external_stylesheets array in js/config.js.

Unfortunately, the css code is loaded after my own css. So, this causes normalize.css to overwrite my own paddings, margins, etc.

For now, I work around this by just not using the option and putting <link rel="stylesheet" href="//cdn-server/.../normalize.css"> into the styleguide's index.html instead.

Site disabled

When I go to http://kaleistyleguide.com/. I get the following screen shot:

I don't know if the site is supposed to be down. But wanted to flag it.

Floating Style List

On each style page, maybe we should float a menu of the sections in the style like twitter boot strap.

http://twitter.github.com/bootstrap/components.html#pagination

Maybe if each styles page was listed in a combo box above and the list of styles of the selected css goes below in a twitter bootstrap fashion.

IE9 "Console" Fix

On Windows 7 (and possibly other Win OS?) in IE9 when launching http://kaleistyleguide.com/ (or a deployed guide) the styles do not load, but instead get stuck at "loading styles" text with a blank page.

Error from IE9:
line15 in menu.js: 'console' is undefined

Jakub's Quick Fix:
In 'index.html' I've placed the following code above the require.js script tag:
'<script type="text/javascript"> if (!window.console) console = {log: function() {}}; </script>'

With that, IE9 loads everything properly :) Maybe there is a cleaner way ...

Jakub

Ability to define menu name of CSS file

Hi there, I'd like to be able to change e.g. "style.css" in the menu to something like "Base stylesheet". Is this currently possible?

Absolute CSS path for @import rule in main style sheet

Seems the page.js and text.js can't load the correct CSS file if the @import rule in the main styles.css is using an absolute path. Is there a way to fix this?

I have a use case that require me to load an absolute path rather than relative.

@import url("/css/test/fixie-demo.css");
the route is loaded as : http://kalei/#/style//css/test/buttons.css in the window.location.url
the text.js is trying to load http://kalei///css//css/test/fixie-demo.css?bust=1342532271918

Error with []'s in CSS comments

The following:

/* [ foo ] */

Causes this result in Chrome:

Uncaught TypeError: Cannot read property ' foo ' of undefined marked.js:427 inline.lexer marked.js:427 tok marked.js:622 parse marked.js:650 marked.parser marked.js:773 Backbone.View.extend.render page.js:75 d.execCb require.js:27 o require.js:11 f require.js:12 o require.js:12 e require.js:12 g.finishLoad text.js:10 g.load text.js:10 window.undefined.window.navigator.window.document.c.onreadystatechange text.js:7

Specific comment format for Kalei

Would be nice to be able to configure a specific format for comments meant to be parsed by Kalei, since not all the comments are of interest.
Something like:

/k
Comment
*/

Handling parameters

Currently we're doing it like this:

/*
name: Primary action button
template: button
description: Text for desc
*/

The question is what req's we have. Do we need multi-line support for example?
I would like to use some format that other people use as well, was thinking about YAML but that doesn't support multi-line.

Kalei in React

I wonder if there is still room for a styleguide similar to Kalei but built in React...

Include method to load your own JS files

Hi there,

I'd like to have the ability to add my own "custom.js" file so I can use my project's JS as well (in some cases it's necissary for the styling). I've found a way of doing this but maybe it's useful to add a method for this.

With a method we could also include other jquery plugins more easily, and this way we can also include things like slideshows in our style guide.

Homepage broken

@pospi any idea which one of those commits broke it. I'm looking into it later tonight

Parsing issue - port to new parser?

Parser stops at this selector:
.subnav-area a:visited,.subnav-area a:link{color:inherit}

Type in some selectors below this one, nothing below it will be parsed.
Can be demo'd from JSCSSP's page: http://www.glazman.org/JSCSSP/

Slow rendering & poor performance?

Hi, I am including about 15 style sheets with 2 or 3 sections on each file and I am experiencing poor performance when I scroll up and down.

Has anyone had this happen to them and is there a fix? I would really like to continue using Kalei.

Thanks

Callback or event after Kalei is done rendering?

I went trawling through Kalei's source code looking for some kind of callback or event I could hook into after Kalei was done rendering everything, but couldn't find one (perhaps I was not looking in the right place). This would be useful for kicking off functions that you would normally hook to a document.ready().

css within another folder is not routed

So in styles.css, I have:

/*
# Hello
## Dolly


### Base style
@import url('theme.css');
@import url('common/buttons.css');
*/

theme.css page works fine, but common/button.css is routed to styles.css, which is the the default route in route.js. Any hints on how to make this work?

Ability to read CSS file/s from a different domain

Hi Thomas,
Is it possible to read CSS file/s from another domain, from which to generate a documentation?
I want to be able to create a documentation for multiple websites that have different domains each, but if I refer their CSS files with an absolute path Kalei doesn't load anything.

Regarding file names, multiple CSS files

Looks cool so far, I'm just having an issue getting my local setup to work like the demo:

• How can I use a file named something other than styles.css? For instance, I want to use foo.css, and when I put that into the config, it requests foo.cssstyles.css first and then foo.css/styles.css second.
• How can I include multiple files, such as in your demo? E.g. buttons.css and fixie-demo.css.
• Is it possible for the path (that is configured in configure.js) to parse the result of a directory listing and then use any stylesheets that it finds there? Not sure why you'd make the path configurable, but seemingly not the actual css file name(s).

Thanks in advance!

SASS

Any plans on adding SCSS support? It was mentioned as "in progress" in the tutorial video, but it looks like it's still not there.

Add viewport context options

I note that this has already been raised by @lukebrooker in #21, but I thought it was worthy of its own ticket.

The iframe approach used by StyleDocco is great for testing media queries, but it's only part of the solution required of a styleguide.

Many of the components a styleguide is likely to illustrate actually depend on the size of their containing element rather than the size of the browser viewport. Many page components may be designed to occupy containers of multiple sizes (for example a panel which can be in the page body or in a sidebar).

I'd like to see a solution which can accommodate both scenarios.

Disable the code preview

Hi,
is there a way to disable sometimes the code preview?

Best wishes,
Jan

Broken on Chrome/Safari on mobile (iOS 6)