Vivus —
Living CSS styleguides

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

Now they don't have to be.

Fork it on Github.
By Mark Cipolla.

Vivus is a ruby gem that builds a living, breathing styleguide from your SASS files.

No mess, no fuss.


Concept

CSS Styleguides suffer from a number of problems:

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.

Vivus is very light on syntax, and forgiving of the order you write the docs in. Don't want to add HTML examples for a given component? Sure. Don't need to have a url that it can point to? Done. Want very easy documentation syntax so you don't have to remember real tricky combinations of ``` and yaml and god knows what else?

The styleguide itself.

The styleguide displays your description, your HTML example and the code written (with full syntax highlighting for easy reading).

Example

It automagically creates a navigation based off the section and title of each block, from across your SASS files.

Syntax

The syntax is simple and easy to use (and remember). It's also quite forgiving; They can be in any order, and the example URLs are definitely optional.

/**
[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] An optional address pointing to further documentation
**/
    

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 http://localhost:3000/styleguide.
And start documenting.