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 displays your description, your HTML example and the code written (with full syntax highlighting for easy reading).
It automagically creates a navigation based off the section and title of each block, from across your SASS files.
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 **/
Add this to your Gemfile:
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.