Easily create front-end style guides with Markdown and Sass/SCSS.
Easily create front-end style guides with Markdown and Sass/SCSS.
Easily create living style guides/front-end style guides/pattern libraries by adding Markdown documentation to your Sass project. Follow @LSGorg for updates.
Setup
$ gem install livingstyleguide
Create sass/styleguide.lsg (replace sass/ with the directory name of your Sass files) with:
// Replace with your default Sass/SCSS file name:
@scss application.css.scss
// Set the HTML title of the document:
@title My Living Style Guide
// Import all your style guide files
@import sass/**/*.lsg
Write documentation for each module sass/partials/_buttons.lsg (to describe _buttons.scss in the same folder):
# Buttons
```
Example button
```
```
Example button
```
Call livingstyleguide compile sass/styleguide.lsg public/styleguide.html
This will automatically:
Be aware: From LSG v2 on Rails 3.x is not supported due to outdated Sprockets and Tilt versions.
Setup: Add this line to your application’s Gemfile:
gem "livingstyleguide"
And then execute:
$ bundle
$ rails s
Create app/assets/stylesheets/styleguide.html.lsg with:
// Replace with your default Sass/SCSS file name:
@scss application.css.scss
// Set the HTML title of the document:
@title My Living Style Guide
// Import all your style guide files
@import **/*.lsg
Write documentation for each module app/assets/stylesheets/partials/_buttons.lsg (to describe _buttons.sass in the same folder):
# Buttons
```
Example button
```
```
Example button
```
Open . This will automatically:
Add the styleguide.html to the precompile list in config/application.rb:
config.assets.precompile += ["styleguide.html"]
There is a Rails example application available on Github.
Use sass-rails > v5 to allow Sass > v3.2:
# Gemfile:
gem "sass-rails", "~> 5.0.0.beta1"
See issue #99 for discussions.
Since Rails 4 non-digest assets are not created anymore. If you want a public sharable url consider using something like Non Stupid Digest Assets
Setup: Add this line to your application’s Gemfile:
gem "livingstyleguide"
And then execute:
$ bundle
$ middleman
Create source/styleguide.html.lsg with:
// Replace with your default Sass/SCSS file name:
@scss application.css.scss
// Set the HTML title of the document:
@title My Living Style Guide
// Import all your style guide files
@import css/**/*.lsg
Write documentation for each module source/css/partials/_buttons.lsg (to describe _buttons.sass in the same folder):
# Buttons
```
Example button
```
```
Example button
```
Open . This will automatically:
source/css/). It won’t work.See NexwayGroup/grunt-livingstyleguide.
See efacilitation/gulp-livingstyleguide.
See livingstyleguide/broccoli-livingstyleguide.
See livingstyleguide/broccoli-livingstyleguide (comments on Ember CLI can be found there).
Just write normal Markdown. The style guide examples are written in code blocks surrounded by three backticks:
```
This is an example
```
Just make sure, when you write a headline, put a space between # and the headline.
In other words: # Headline, not #Headline.
In addition to Markdown, there are several commands (starting with an @) which automate things to make generating style guides more fun. Commands can be used within and outside of code blocks, but will have a different meaning. Commands available are:
You can import any other *.lsg file at any place within any *.lsg file:
```
// Import a file:
@import folder/file.lsg
// Import a file (`.lsg` will be added by default):
@import folder/file
// Import a file starting with `_` (folder/_file.lsg); this works automatically:
@import folder/file
// Import multiple files:
@import folder/*.lsg
@import folder/*
// Importing from multiple folders:
@import **/*.lsg
@import **/*
// Importing a Haml file (the resulting HTML will be rendered into the style guide):
@import folder/file.haml
@import folder/*.haml
@import **/*.haml
```
All file types supported by Tilt can be imported.
By default, @import is looking for *.lsg files.
A default example outputs the HTML source as:
Example:
```
Example button
```
There are more commands to generate output. They start with an @ and can be put in the code block:
You can automatically generate color swatches out of your Sass variables:
@colors {
$light-red $gray $green $red $dark-red $black
}
By clicking the color swatch in the style guide, users can copy the hex code of the color (useful for designers). When pointing the cursor on the variable name, it will be copied on click instead (useful for developers).
The output will respect newlines. The example below will create a 3 × 3 matrix
of color swatches and groups shades in columns which might be more easy to
understand. - leaves a cell empty in the matrix:
@colors {
- $light-red $gray
$green $red -
- $dark-red $black
}
The LivingStyleGuide also supports CSS colors and Sass functions. All of them will work:
@colors {
red #ca1f70 #FFF rgba(0, 0, 0, 0.5)
$my-color my-color-function() lighten(red, 10%) darken($my-color, 20%)
}
This will output the code as HTML but display the syntax highlighted source as Haml (learn how to use Haml by default):
```
@haml
%button.button Example button
```
You can add any CSS to each example if it helps to make it better in the style guide only. For example, add some margin between elements:
```
Example button
Example button
@css {
.button + .button {
margin-left: 3em;
}
}
```
This adds 3em margin between both buttons.
To avoid this to affect other examples, the CSS code will be scoped to this example only (each example automatically gets a unique id).
If you need the same CSS code for several examples, you can put the CSS outside of the example. This way it will be scoped to the current file:
```
Example button
Example button
```
```
Example button
Example button
```
@css {
.button + .button {
margin-left: 3em;
}
}
For Sass you can also use @sass and @scss:
@sass
.button + .button
margin-left: 3em
@scss {
.button + .button {
margin-left: 3em;
}
}
Within the @scss/@sass helper, all variables, mixins, … of your project are
available. For example, if my-styles.scss sets $my-project-margin, you can
write this:
@scss my-styles.scss
@scss {
.button + .button {
margin-left: $my-project-margin;
}
}
It is possible to add Sass code without scoping (works for @css/scss/sass).
@scss scope: global {
.code { ... }
}
Or as a shortcut inspired by Sass’ global variables (for @scss/@sass):
@scss !global {
.code { ... }
}
This will show and execute the JavaScript, e. g. you designed tabs and need few lines of jQuery to bring them alive.
```
@javascript {
$(".button").click(function() {
alert("Hello World!");
});
}
```
Same example but using CoffeeScript. It will be executed as JavaScript and displayed as CoffeeScript:
```
@coffee-script
$(".button").click ->
alert "Hello World!"
```
Show which fonts should be used on your website—this will output and example text block (A—Z, a—z, 0—9, and some special characters) of the given font. It accepts valid CSS like for font: 32px comic sans ms;.
@font-example 32px comic sans ms
Use your own text (defaults to “ABC…\nabc…\n123…\n!&…” if not set):
@font-example 32px comic sans ms {
Schweißgequält zündet Typograf Jakob
verflixt öde Pangramme an.
}
You can require any Ruby file (e.g. for custom commands) or Ruby Gems (e.g. a Compass plugin:
Loads `my-ruby-file.rb`:
@require my-ruby-file
Loads the Susy Gem (must be installed on your system):
@require susy
If you just want to output code with no extras (just like in a normal Markdown file), you only need to add the language:
No open issues yet, or sync has not completed.