kneath / kss Goto Github PK

Only a single line will show up in .description, and the rest appear to be discarded.

That behavior surprised me though. I would think it would be useful to allow for multi-line descriptions.

I can kind of work around it by explicitly calling .comment_sections[0...-1] on a section instead of calling .description.

Just I didn't found any mentions about how settings the "overview" first default section in the documentation.
I found it was the styleguide.md file you have to put in the style folder, in the demo you show, but I only found it after a while. Maybe it deserve to be in main documentation.

Right now it looks like this would be a great way to do documentation for styles. But what about structures/modules?

I'm thinking in terms of OOCSS with skin vs structure.

https://github.com/stubbornella/oocss/wiki/Module

I'm not sure how well KSS would handle structures. Is there a plan for this?

Also, any reason for not doing a wiki?

The compilation is very very very very ... very very very very ... very .. very very very very ... very ... slow when you have base64 datas in your CSS.

Like this one, it import a base64 font:

 src: url(~"data:font/truetype;charset=utf-8;base64,AAEA…") format('truetype');

Also, its a .less file

Hi Kneath. Thanks for your great work, it inspires me a lot.

I created a style guide parser in nodejs, which is https://github.com/lepture/ganam

The syntax is a little different, and I am sorry for that.

A live preview of the result:

The example code at:

https://github.com/lepture/ganam/tree/master/docs/guide

Hope you can mention it somewhere in your documentation.

I'd like to document the constants that my .scss file makes available. For example, something like the following:

// Body Text
//
// The main body text.
//
// Usage: .my-rule: { font-family: $font-body-text; }
//
// Styleguide 1.0.5
$font-body-text: "Comic Sans", Tahoma, sans-serif;

In the SPEC.md and in the website, shows that there should be support for mixins, although that is not yet implemented into the code.

This issue is to track progress on that. Everyone is invited to do a pull-request of it.

Mixins should require a Section but not markup, instead, usage.

A guide to set up KSS-powered style guide documentation in a {Rails,Sinatra,plain HTML} project would be nice.

My Sass (using Sass 3.2):

%foo
  background-color: red
  &:active
    background-color: pink

.foo-big
  @extend %foo
  font-size: 24px

.foo-little
  @extend %foo
  font-size: 16px

This ends up generating CSS like

.foo-big, .foo-little {
  background-color: red;
}
.foo-big {
  font-size: 24px;
}
.foo-little {
  font-size: 16px;
}

.foo-big:active, .foo-little:active {
  background-color: pink;
}

KSS seems to be generating this CSS:

.foo-big.pseudo-class-active, .foo-little:active {
  background-color: pink;
}

Note only one of those comma-separated selectors was transmuted to its real-class form. As a result, the .foo-little:active KSS preview looks broken.

It will be awesome to generate guidelines with grunt

So yesterday I tried using kss to documenting my css. And I follow the documentation from http://warpspire.com/kss/styleguides/

Everything seems perfect until my capture method show an error:
"undefined method `close' for nil:NilClass"

app/controllers/kss_controller.rb:21:in `kss_block'

@example_html = capture(block)

There is no examples showing how nested classes in languages such as LESS / SCSS / Stylus should be documented.

I assume you just do the same for the parent class, but should there be a parent annotation for this for pure CSS?

These are just some basic questions that come up when documenting, but there are even more the further you go; These two should clear up most of that confusion.

More specifically, when I include fonts from google above kss.js, no dynamic pseudo-class styles are generated. I believe this is because the script stops looping through the stylesheets once it hits the font stylesheet. Perhaps this is because stylesheet.cssRules is null for that type of css file, but I'm not totally sure.

Would be cool to iterate over sections instead of manually retrieving sections.

Not sure if there is a way to do this already, but I am unable to access the @sections var of Parser publicly.

Support documentation by SASS/LESS variables

It would be nice to add a binary to the gem that takes in (mustache?) template files, css files and generates a styleguide for those who don't want to include the ruby gem in their production app.

Using the private key below, I get the following error:

Uncaught Invalid PEM format pki.js:1019
pki.pemToDer pki.js:1019
pki.encryptedPrivateKeyFromPem pki.js:3071
pki.decryptRsaPrivateKey pki.js:3105

The key was generated with openssl through Ruby, which includes encapsulated header fields defined in RFC 1421 in the pem file.

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: AES-128-CBC,908A2D85694C80A7BF001D69B48F8974

zZpNVpTuggEHTk0H1RmS9667k7p/mM/3RIyAFx2u82oNdbjI0vj75ug1M6DZHIKT
GK372Xg1ND6Xbz3N7A9Vuhu2ETmd0jv4Knp+5NNfkCpqJit//OeWfCCLLz5WlQ4Z
2YjDl57XEihJXUYq4LABJn95udFUcrKOJcj5Sz6PaiHHKOyx/KC0sil4d+AdIzL6
W4KLVygT5iymFGcWyZcW1GdVeQJAhE2qKfd3HtgvCDNPdBuaTxdGv12KFkiwvM4z
5KzIhBxTSEeFr1Ef8pzi7VRR7ip+0+d9xzNZXqlMt6FfurA+MCBF2Y1mzwyiu0EB
ka9xXQnJPTzkaPGmVDtJdxrbIWGHcYVlC+21Vo+lxJyPBqvMdAczRBslIAkmKW53
Lx/dEL3fKcbFPFoLANosLEk+pAE/Tw+ZGMwDPKrpSFdm3zwfiSlYjJexGxTQXRnp
Ot5bt463Bfio/V7hJDDuKSB65VttuqHJxo3FDNILEd/zu2T9G1mzloZWrUrMQ/nD
gHiYVi4YMNv2FEZmqNSyUMXzOnLxD+I70YArsJ9q21wNTd5cWfnRqh2osZsdeUyw
UTmMH3fBZE/L0JlnAOSsDWjUhvoPY9R/YQ8JjXrSw5BplHVpB6/UEV6MMSDFcbCg
VAo7dze9WWkRTRR+XHPmoyViik5ydJk63Hgf7JaDje2WsGUxGy011FHqsWHMb2MC
zWC2AKYzMwFSoSwwkRu0xMyghq0kR1LagX/qjMIPTcHzJ57EzXs8eZyt6Mw5cjXh
eDPADOZSLNQ/E9YHJNsMQ1/lM3YBakxGvPUBwSQ9ZTpthrcMyZo/9YVnlL6iW1mv
-----END RSA PRIVATE KEY-----

The passphrase for this key is testing if you want to use it for a test case.

Is it possible to make them optional and does it make sense? Now for example windows installation breaks because of less dependency even though we use just sass.

from: kss-node/kss-node#52

What if my modifiers are not always class names?
E.g. I often use ARIA role attributes as modifiers:

.btn[aria-disabled="true"] { ... }

I did not find any practicable solution to document those.

I think the format of Javadoc (or PHPDoc and other) should be a good thing.

/**
 * Comment
 *
 * @author Maxime
 * @deprecated ...
 */

It's "native" to CSS, and a lot of IDE already support keyword like @link, @author, @Version...

What do you think about this style of format ?

Right now, it's not possible to do:

// Thing #1
//
// Styleguide 1.0.1

... and then later do:

// Thing #2
//
// Styleguide 1.0.1

And have them both show up in section 1.0.1.

Instead, only the last assigned block will show up for a given section.

Is this the intended behavior? If so, it doesn't appear to be specified as such.

I suppose it might be useful to be able to enter multiple blocks to a single styleguide section. Either way, the spec seems ambiguous on the topic.

Cloned project and ran the example project, but it keeps crashing Chrome and Safari? To prove that I wasn't insane I tried this on a few other computers. No luck.

What's weird is that it works fine in Firefox? Finally I commented out the kss.js and the example 'works' in Chrome, but that is not a real solution.

Hi,

Would it be possible for the styleguide generator to automatically increment the styleguide index? Currently it is quite fiddly to manage the indices across lots of examples.

So for example I could do something like this:

/*
My first element

Markup:
<p class="foo">Lorem</p>

Styleguide 2.n
*/

.foo { color: red; }

/*
My second element

Markup:
<span class="bar">Ipsum</span>

Styleguide 2.n
*/

.bar { color: yellow; }

When the styleguide was generated, KSS would recognise n as a placeholder, and replace it with the appropriate integer:

2.1 - My first element
<p class="foo">Lorem</p>

2.2 - My second element
<span class="bar">Ipsum</span>

Thanks,
Dan

Hi,

Also It's a good solution to end the headache of difficult CSS, But I can't figure out what is the difference between kss and less [1]? Do they have the same goal? Maybe my imagination on what is kss is wrong.

May you help me understand why one should use kss instead of less?

[1] http://lesscss.org/

Hello! I'd like to use kss to document some interactive components and animations. Looks like this section of the GitHub style guide intended to do the same:

https://github.com/styleguide/css/12.0

However, trying to execute any of the animations results in this error:

Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' https://github.global.ssl.fastly.net https://jobs.github.com https://ssl.google-analytics.com https://collector-cdn.github.com https://analytics.githubapp.com https://embed.github.com https://raw.github.com".

Not sure if this is a kss bug, or an error in GitHub's implementation...

Thanks!

According to the spec:

CSS rules that depend on specific HTML structures should describe those structures using <element#id.class:pseudo> notation. For example:

// A feed of activity items. Within each <section.feed>, there should be many
// <article>s which are the  feed items.

But the spec doesn't indicate how those pseudo-HTML blocks should be displayed in the output of a generated styleguide.

I'm assuming they should be output as plain-text, escaped, and not actually inserted as HTML?

Personally, I would actually prefer if there was some way to include raw HTML examples right in the KSS docs. I think keeping the HTML next to the CSS could – in certain cases – be helpful.

first, this looks amazing(!)

I have a project w/ a bunch of .sass formatted in "traditional" (non scss) format...I tried adding some kss docs w/ a subset to test, but was geting a parser exception.

I then just did a bare simple test w/ a trivial .sass file, but got the same issue - an exception from the parser call (pasted below)

It looks like you are using the scss parser directly rather than the wrapper? http://sass-lang.com/docs/yardoc/Sass/Engine.html

(.scss works like a charm, so I maybe this is the impetus to go through a conversion...though I'm still not sure why .scss seems to have emerged as more common since .sass seems so much more readable to me)

styleguide = Kss::Parser.new(".")
Sass::SyntaxError: Invalid CSS after "$margin": expected selector or at-rule, was ": 16px"
from (sass):13
from /Library/Ruby/Gems/1.8/gems/sass-3.1.11/lib/sass/../sass/scss/parser.rb:926:in expected' from /Library/Ruby/Gems/1.8/gems/sass-3.1.11/lib/sass/../sass/scss/parser.rb:872:inexpected'
from /Library/Ruby/Gems/1.8/gems/sass-3.1.11/lib/sass/../sass/scss/parser.rb:29:in parse' from /Library/Ruby/Gems/1.8/gems/kss-0.1.1/lib/kss/parser.rb:15:ininitialize'
from /Library/Ruby/Gems/1.8/gems/kss-0.1.1/lib/kss/parser.rb:14:in each' from /Library/Ruby/Gems/1.8/gems/kss-0.1.1/lib/kss/parser.rb:14:ininitialize'
from (irb):3:in `new'
from (irb):3

The first reference to the variable stylesheet on line 17 is misspelled. Causes kss.js not to work.

https://github.com/kneath/kss/blob/master/example/public/javascripts/kss.js#L17

A useful feature could be a Dependencies section.

Here a mockup:

// Buttons
// 
// A cool submit button.
//
// Markup: <input type="submit" />
//
// Styleguide: forms.button

[type="submit"]
  line-height: 1.2em

// Textfield
//
// A cool textfield.
// 
// Markup: <input type="text" />
//
// Styleguide: form.text

[type="text"]
  margin: 0 1em

// Small form
//
// A very small search form.
//
// Markup:
// <form class="small-form">
//  <div>
//     <input type="text" />
//     <input type="submit" />
//   </div>
// </form>
//
// Styleguide: form.small-form
//
// Dependencies:
// * form.text
// * form.button

.small-form > div
  display: flex

An HTML styleguide then could list links to all dependent components:

Small Form

A very small search form.

Example:

<form class="small-form">
 <div>
    <input type="text" />
    <input type="submit" />
  </div>
</form>

Dependencies:

• Button
• Textfield

Or even warn if a component is missing:

Dependencies:

• Button
• form.text Warning: dependency missing!

Also the dependent sections could link to sections which are dependent from it:

Button

A cool submit button.

Example:

<input type="submit" />

Required by:

• Small Form

This could help to keep track of the code. When one changes the Button Component he might be interested to check if the Small Form Component was unintentionally affected by the change.

Neither the spec or the documentation on the KSS site touch on mutliline modifier statements, which the ruby and node implementations both support. Is this supported in the spec, and should the spec take a stance on this explicitly?

When you click the image, it redirects to a 404 page. GitHub moved their style guide over to http://primercss.io/.

Here's the page with the broken link.
http://warpspire.com/kss/styleguides/

In my index file I'm using handlebars to generate the left nav (same as bootstrap) based on the titles of the page. My issue is if I have a section such as "Inputs" I need to have the left nav contain a sub section with Normal, Disabled, Required, etc etc. Is there a way to do this with the current KSS Template file using handlebars? I just need to be able to maybe call out a sub section with a character or something so it knows the difference between a Main header section and the sub level.

Included for reference: http://stackoverflow.com/questions/26414632/kss-knyle-style-sheet-creating-sub-nav-for-table-of-contents

Thanks

The spec mentions support for LESS files, but currently KSS only parses SASS files. Could we please get a parser for us LESS folks?

Hi,

I read other tickets about including markup in CSS comments, and I fully agree that there's no place for HTML in CSS, but generating only modifiers and sticking to KSS markup generation features is very limited. Do you plan to support template includes alongside section description?

I would expect something like this:

/*
A button suitable for giving stars to someone.

@include "template.hbs" - some targeted description

Styleguide 2.1.3.
*/

Better if we show an instruction on how add a styleguide page instead of a 500.

The screenshot example of the KSS shows the default HTML appearing after the modifiers. It doesn't appear that is showing up by default, at least not in my build. Is there a way to enable this?

Separating the HTML markup from the CSS has been a maintenance painpoint for my project and find that embedding it directly into the CSS documentation would be the most elegant solution.

example:

/*
 * Default button styling.
 *
 * :hover - highlight when hover
 *
 * Styleguide 1.1
 *   <button class="button $modifier_class">Example Button</button>
 *   <button class="button $modifier_class" disabled="disabled">Example Disabled Button</button>
 */
.button
  font-size: 16px
  margin: 0 auto
  &[disabled]
    background-color: #DDD

This is similar to YARD documentation's @example tag for self documenting ruby code.

Hi, is it works with BEM syntax - can you add some examples? :)

The BEM uses modifiers (--) and children (__) for object, so how to write documentation? :)

In most cases I do want the styleguide to include the classless default state but other times the CSS is written such that the default state is not to be used and I would prefer it not appear.

Is there an official way to flag content (either in the CSS comments or in the .erb) so that the default state is not shown?

It looks like the buttons.css in the sinatra example was generated from a SASS file, and it would be useful to see that file as well (for readability).

Also, it looks IE gradient thing is not interacting well with your SASS variables (notice $start and $end in the following line: filter: progid:DXImageTransform.Microsoft.gradient(GradientType=0, startColorstr='$start', endColorstr='$end');)

Finally, thanks for getting this ball rolling, I'm really excited about this project!

From #116:

Finding another acronym for KSS. Knyle Style Sheets was always meant to be silly, but a lot more people ended up using this than I imagined. I wouldn't mind something less silly.

Please post suggestions in the comments below. @kneath will be the final arbiter of the new backcronym.

FYI, "backcronym" is when you've decided on the acronym before you've decided on the meaning of the acronym. So we will keep "KSS", but change the meaning of it.

Just curious. Could there be a simple way to enable search across all sections?

Maybe all the html could be concatenated into a search.html page so a keyword across all sections could be found?
The guide approach is good, but being able to search by a css class name could be very useful.
Thx.

The ruby gem is great and all, but how about a Node parser? When your stack uses Node for your JS combining/minification, LESS preprocessing, template precompiling, and unit testing, its great to find additional useful tools like KSS that work well with your stack. For many people, introducing a ruby dependency wouldn't be ideal. What do you think?

I'm considering including KSS support in an interface library and quasi-styleguide project called Pattern Lab. One of the features of the project allows designers to test their "patterns" in a fluid layout and it would be great to document the changes someone had to make because of it. I was wondering if there are plans to add a formal format to the spec for documenting changes to styles across breakpoints. I know I make my breakpoint changes at the component-level so KSS would be really helpful for documenting this. For example, I might make the logo of a site bigger at a specific breakpoint:

.logo {
    float: left;
    max-width: 8rem;
    margin: 0.4rem;

    @media all and (min-width: $bp-med) {
        max-width: 9rem;
    }
}

If documenting media queries is outside the scope of this project that's cool. I can hack something together and shoot it back for consideration. Just wanted to make sure I didn't go too far off the tracks if you had thoughts in this direction.

Is there an easy way to create html files for the localhost:4567 output?

Hey,

I noticed on GitHub buttons syleguide that you have displayed the filename of the individual sass file used to create that module.

Is this something that kss makes available? Or is this something you have done manually?

Thanks in advance :-)

Since we're using the full SCSS parser on each call, producing a Parser object can end up being really slow. Need to look into either partial SCSS compilation, or caching the result of the parser somehow.

I have a pull request over a year old. And there is a pull request from 2013. #92

Do you need help maintaining this project?

My interest is in updating the KSS spec and in maintaining the kss.js script since I maintain the kss-node port. But I feel there must be others interested in the Ruby code in this repository.

Hi,

Thanks for your work with KSS, I'm a big fan of the system.

I'd like the ability to import one or more .HTML files into the stylesheet. This would allow us to maintain our HTML snippets separately, keep them DRY (cutting down on possible errors where a snippet is updated but the CSS is not) and allow them to be used (or generated) by a templating system..

So instead of this:

/*
Manually authoring HTML snippets

Markup:
<p class="foo">Lorem ipsum</p>

Styleguide xxx.x
*/

I would like something like this:

/*
Importing HTML snippets

@markup "../html/foo.html"

Styleguide xxx.x
*/

Thanks,
Dan