six7 / styleguide

Simple style guide for Rails 5.1+

Styleguide

Simple style guide for Rails 5.1+, designed to go well with components. The two together are inspired by the works of Brad Frost and by the thoughts behind Lonely Planet's style guide Rizzo.

Installation

Add this line to your application's Gemfile:

gem "styleguide", git: "https://github.com/jensljungblad/styleguide.git"

And then execute:

$ bundle

Run the install generator:

$ bin/rails g styleguide:install

This will create the following files and directories:

app/
  views/
    layouts/
      styleguide/
        example.html.erb
    styleguide/
      01_home.md

The style guide can be mounted in your routes file with:

mount Styleguide::Engine => "/styleguide"

You can now access the style guide at http://localhost:3000/styleguide.

Pages

You can create style guide pages simply by adding markdown files to the app/views/styleguide directory. These can be structured by putting them in subdirectories, and sorted by prefixing the file names with a digit.

Check out Brad Frost's Style Guide Guide for style guide inspiration.

Examples

A special markdown syntax, inspired by Catalog, can be used to render examples of any erb code on the style guide page, in the context of your own application:

# Example

```example
<%= "Hello world" %>
```

It is possible to pass options to the example, in order to control the width and height of the wrapping element:

```example
width: 500
height: 200
---
<%= "Hello world" %>
```

Examples need your application's CSS and JS in order to function properly. There is an app/views/layouts/styleguide/example.html.erb layout file that examples are rendered within. This file can be modified in order to add additional tags to the header, like the javascript_pack_tag when using the webpacker gem, or classes and styles to the body tag.

Acknowledgements

This library, together with components, was inspired by the writings of Brad Frost on atomic design and living style guides, and Rizzo, the Lonely Planet style guide. Other inspirations were:

• Catalog - style guide for React
• Storybook - style guide for React
• React Styleguidist - style guide for React
• Cells - view components for Ruby
• Komponent - view components for Ruby

For a list of real world style guides, check out http://styleguides.io.