New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include stylesheet source code into styleguide #50

Open
indieveed opened this Issue Feb 17, 2014 · 12 comments

Comments

Projects
None yet
9 participants
@indieveed

indieveed commented Feb 17, 2014

May be i just did not figure out this thing, but is it possible to output source code (CSS, SASS, LESS). There are only html outputs in examples, but i would like to show my source code too. I know that syledocco can do this. Is it possible with kss-node?
If not, it could be a good feature.

@sioked

This comment has been minimized.

sioked commented Feb 28, 2014

Not sure if this is exactly what you're looking for, but all kss comments are parsed via markdown (specifically GitHub Flavored Markdown by default), so it's possible to include a code block for any other code that you would like to display. I use this to add some documentation around how to use some javascript that goes along with one of the components I'm documenting (i.e. how a custom dropdown looks and how to hook up the javascript to get it to function).

As far as I've seen, there is no ability to include all of your source code around specific comments like styledocco does (Doesn't seem to really fit the kss style of documentation).

@indieveed

This comment has been minimized.

indieveed commented Feb 28, 2014

ok, your point makes sense. May be including something like source map could be a good feature to fit the kss style? Just to know wich line is responsible for what i see in a styleguide. But may be i just need to structure my code better and this problem will go away

@JohnAlbin

This comment has been minimized.

Contributor

JohnAlbin commented Jul 21, 2014

Actually, I was thinking about a feature like this in order to properly document Sass variables. Something like:

// Sass color variables
//
// code block:
$my-var: 'foo';
$my-var2: 'bar';
// etc.
$my-var3: 'baz';
// end code block
//
// Styleguide 1.2

FYI, the "end code block" (or similar) would be required to make it possible to include comments within the code block. It would also make parsing drop dead simple.

Not sure if breaking a KSS doc block in half with code block section would work, but its something to investigate.

@JohnAlbin JohnAlbin added this to the 1.x milestone Jul 21, 2014

@JohnAlbin JohnAlbin modified the milestones: 2.x, 1.x Jul 24, 2014

@JohnAlbin JohnAlbin changed the title from Include source code into living styleguide to Include stylesheet source code into styleguide Jul 24, 2014

@daften

This comment has been minimized.

daften commented Oct 21, 2014

I would mainly find this interesting to document the color scheme for the theme I'm working on and have a visual representation of the colors. Is the only possibility to create classes for that color (that just use that variable) and use those classes as modifiers?

@daften

This comment has been minimized.

daften commented Nov 2, 2014

For colors and base HTML elements (and e.g. icons), there should be an example, without markup, similar to how bootstrap does it IMO.
So for colors, showing the variable is fine, but the only way i see to show an example is with custom css classes made for this and a markup section.

@JohnAlbin

This comment has been minimized.

Contributor

JohnAlbin commented Nov 3, 2014

Can you provide a screenshot or link to explain your "similar to how bootstrap does it" example?

@daften

This comment has been minimized.

daften commented Nov 3, 2014

For icons: http://getbootstrap.com/components/
For typography (very basically): http://getbootstrap.com/css/#type

The base elements such as headings and paragraphs do interfere with the template look-and-feel though, but that's another problem :)

I'll provide some of my snippets on how I've solved it now later today normally.

@liyuankui

This comment has been minimized.

liyuankui commented Nov 3, 2014

It would be great with features like:
font.less:

// Font color
// .font-strong - for bigger contrast
// Markup:
// <span class="{$modifiers}">testing text</span> has less variable {$variable}
// Styleguide 1.1
.font-strong {
  color:@text-color-black
}

renders to:

Font color
.font-strong for bigger contrast
<span class="font-strong">testing text</span> has less variable @text-color-black

@JohnAlbin JohnAlbin referenced this issue May 21, 2015

Closed

Release 2.2.0 #208

7 of 14 tasks complete
@erfanimani

This comment has been minimized.

erfanimani commented Oct 5, 2015

Github's styleguide has something similar to that what is being requested in this issue: http://primercss.io/colors/

But, unfortunately, theirs doesn't seem to be automatically generated either: https://raw.githubusercontent.com/primer/primer/master/docs/colors.md

@vidhill

This comment has been minimized.

vidhill commented Mar 10, 2016

I'm just going to add this as a reference for others looking into this,

The project sc5-styleguides, which uses kss-node as a dependency achieves this.

They use gonzales-pe in combination with gonzales-ast to parse sass sourse.

Their source is here

@tsi

This comment has been minimized.

tsi commented Sep 19, 2016

This is my work-around for a color list, it's far from perfect, and I have to maintain 2 lists, but it works.

// Colors
//
// #97007A - : Magenta
// #424344 - : Grey
// #28292A - : Dark grey
//
// Markup: <div style="background: {{modifier_class}};" class="styleguide-color">{{modifier_class}}</div>
//
// Styleguide 1

$color--magenta: #97007A;
$color--grey: #424344;
$color--grey-dark: #28292A;
@ryuran

This comment has been minimized.

Collaborator

ryuran commented Sep 19, 2016

My way with custom field and twig extend (I have a handlebars version too):

Result: http://20minutes.github.io/colette/section-settings.html#kssref-settings-colors

You can style it.

But stay duplicate date (code vs comment).
The main raison is, KSS do not parse the code to keep support for every languages (css/less/sass/scss/stylus). Parse code could be complexe.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment