Skip to content
This repository has been archived by the owner. It is now read-only.

markcipolla/vivus

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
app
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Vivus Styleguide  Gem Version

Concept

Styleguides can be a pain to keep as a living documentation for your CSS.

The issue I had with various styleguide gems is that documenting your CSS in a not-hugely specific way is hard, and that keeping the HTML examples in another files means that there are three places your code needs to be updated and checked:

  • In your CSS file,
  • in your HTML Examples,
  • and in the HTML that your app actually uses.

Too many times we'd had the styleguides become unusable as the HTML gets rewritten and the CSS updated.

By analysing the comments in your SASS files, and by adding markdown to your stylesheets, you can generate a living, breathing documentation styleguide that has examples of how the CSS is used.

Installation

Add this to your Gemfile:

gem 'vivus'

Add this to your routes.rb

if Rails.env.development?
  mount Vivus::Engine, at: "styleguide"
end

Then hit up localhost:3000/styleguide

To document your CSS, use this as a template

/**
[Name] The name of the component (e.g. Success Buttons)
[Section] A section that groups components together (e.g. Buttons)
[Description]

Write some documentation explaining the use / concept of the CSS
you've got below. This bit will be markdown rendered.

This is optional, but really... why styleguide code you don't want 
to document?

- You can use three backticks (`) to indicate a code block
- ```<div class="example"></div>```
- Code blocks will be syntax highlighted

When you've documented it nicely, use the Example markers to
indicate a block of HTML that uses the CSS.

Keeps your documentation right near the CSS.
So, if you update / refactor the CSS, update the HTML example if
need be.

[Example] 
<div class="example">
  <p>This is optional, but kinda the point</p>
  <a href="#" class="button">Some text</a>
</div>

<% 5.times do %>
  <div class="example">
    <p>This will be outputted five times!</p>
    <p>ERB in your CSS! Craziness!</p>
  </div>
<% end %>
[Url] A web address pointing to further documentation / example (optional)
**/

The only required ones are [Name] and [Section]. The rest are up to you to decide how much details you add.

This project rocks and uses MIT-LICENSE.

About

Living CSS documentation

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published