Support embedding example markup within KSS comments

[wireframe]

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.

[kneath]

I'm actually really against this. Separation of markup and style!

But more specifically because CSS can apply to several different types of HTML structures at once. This would be a massive amount of noise in the CSS and not work toward a living styleguide (since your HTML is divorced from your application).

Here's a good example: https://github.com/styleguide/css/6 Section 6.1 has several different HTML structures, all of which are pretty heavy.

[glenngillen]

Gah. This would make my life much easier too, but can see how messy it would be for your counter-example.

Something about having to update documentation in two places just feels wrong though. This isn't about separation of concerns, that's still occurring within my app. This is about having all of the documentation in a single place so there's no need to context switch to see an example.

I don't have an elegant solution for when there are several different structures though :(

[kneath]

Yeah, that's why I haven't really closed this issue yet. I'm not convinced what I have now is the best solution. But I'm pretty sure embedding markup isn't either.

[webholics]

1. Look at the extended KSS syntax kss-node is using to generate the styleguide: https://github.com/hughsk/kss-node
2. I think it should be good practice to keep modules small and to split growing modules into smaller parts. Therefore the markup section should never be too big.
3. For me heaving markup in place with the CSS module helps in understanding complex CSS code.

[gagarine]

We are using https://github.com/jacobrask/styledocco and it use code fence (```) for the code. We build some large website and this was very nice to have the HTML code within the CSS as reference.

[gagarine]

I think we should support ``` and indentation and eventually "Markup:" like kss-node to make the two tools compatible.

[gagarine]

@kneath do you will accept a pull request for that? I want to add the support of optionally embed markup in the CSS.