現在担当しているプロジェクトでLivingStyleGuideをいれてみたのでメモ。
公式サイトはこちら

できることとかできないこととか

マークダウンで記述するスタイルガイド
Sassを使用しているプロジェクトに限られる？
JSを埋め込めるので、動きのあるものもプレビューできる
スタイルガイドのデフォルトデザインはCSSを上書きすることでカスタム可能
header、footerもオリジナルのHTMLを挿入できる
gulp、gruntのプラグインあり
ページ分割はできなさそう

必要なものの準備

Sass

Sassファイルを用意する。

ディレクトル構成は下記のようにしてみた。

│──sass
│   │── foundation
│   │    │── _base.scss
│   │    └── _reset.scss
│   │── component
│   │    │── _button.scss
│   │    │── _button.md
│   │    │── _icon.scss
│   │    └── _icon.md
│   │── app.scss
│   └── styleguide.lsg

livingstyleguideのインストール

ターミナルで下記を叩いてインストール

$ sudo gem install livingstyleguide

styleguide.lsgファイルを作成

下記内容でsassディレクトリ直下にstyleguide.lsgファイルを作成する

styleguide.lsg

source: 'app.scss' # replace with your default Sass/SCSS file name
title: 'My Living Style Guide'

sourceはデフォルトのscssファイルを指定
これをCSSにコンパイルしたコードがスタイルガイドのhtmlのheadタグ内に記述される。
今回はapp.scssを指定している。

titleにはスタイルガイドのtitleタグの内容を指定

マークダウン

各パーシャルファイル名と同じ名前のマークダウンファイルを作成すし、スタイルガイドを書く。
_button.scssに記述してあるCSSのスタイルガイドを作成する場合、同じ階層に_button.mdを作成する。

_button.scss

.c-button {
  display: inline-block;
}
.c-button-more {
  font-size: 13px;
  font-weight: bold;
  border-radius: 2px;
  background-color: #fbc30a;
  padding: 0 12px;
}

_button.md

Buttons
======= 

```　
 <a class="c-btn c-btn-more">続きを見る</a> 
```

スタイルガイドを生成する

必要なマークダウンファイルを作成したら、スタイルガイドを作成する。

コマンドラインでスタイルガイドを生成

下記コマンドでスタイルガイドのhtmlを生成する。

$ livingstyleguide compile sass/styleguide.lsg docs/styleguide.html

gruntでスタイルガイドを生成

プラグインをインストールする

$ npm i grunt-livingstyleguide -D

Gruntfile.js

grunt.initConfig({
  livingstyleguide: {
    generate: {
      options: {
        src: './sass/styleguide.lsg',
        dest: './docs/styleguide.html'
      }
    }
  },
})

gulpでスタイルガイドを生成

プラグインをインストールする

$ npm i gulp-livingstyleguide -D

gulpfile.js

var gulp = require('gulp');
var livingStyleGuide = require('gulp-livingstyleguide');

gulp.task('livingstyleguide', function () {
  return gulp.src('./sass/styleguide.lsg')
    .pipe(livingStyleGuide())
    .pipe(gulp.dest('./docs'));
});

最終的なディレクトリ構成

│──docs
│   └── styleguide.html
│──sass
│   │── foundation
│   │    │── _base.scss
│   │    └── _reset.scss
│   │── component
│   │    │── _button.scss
│   │    │── _button.md
│   │    │── _icon.scss
│   │    └── _icon.md
│   │── app.scss
│   └── styleguide.lsg

ヘッダー、フッターのカスタマイズ

styleguide.lsgに下記記法でhtmlを記述することでヘッダー、フッターのhtmlを変更できる。
また、CSSも新たに追加することができる。

styleguide.lsg

header: |
  <div class="sg-header">
    <div class="sg-header__main">
      <h1>Style Guide</h1>
    </div>
  </div>

footer: |
  <div class="sg-footer">
    <div class="sg-footer__copyright">
      <p>copyright</p>
    </div>
  </div>
 
styleguide-scss: |
  .sg-header {
    background-color: #ffd400;
  }
  .sg-header__main {
    margin: 0 auto;
    padding: 20px 0;
    box-sizing: border-box;

    h1 {
      font-size: 30px;
      font-weight: bold;
    }
  }

スタイルガイドのデフォルトスタイルを変更する

styleguide.lsgに設定を追加することでデフォルト設定を上書きできる。

デフォルト設定は下記ページのscssファイルに記載してある。
https://github.com/livingstyleguide/livingstyleguide/blob/master/stylesheets/_livingstyleguide.scss

$livingstyleguide-- で始まる変数の値を上書きできる
例えばフォントサイズを変更したい場合は $livingstyleguide--base-font-size で変数が定義されているので、
base-font-size: 10px
のように記載する。
全てのSass記法が使える
自分のプロジェクトで定義している変数も使用できる

下記が設定してみた例。

styleguide.lsg

style:
  base-font: 'Helvetica, Arial, "Hiragino Kaku Gothic ProN", Meiryo, sans-serif'
  width: $site-width
  base-font-size: 10px
  base-line-height: 1.5
  code-color: 'darken(red, 10%)'

所感

導入するにあたり学習コストは高くない。
ページ分割ができないので、大規模サイトだとつらそう。
マークダウンで別ファイルで書けるのがいい

Sassを使用している小規模なサイトで、スタイルガイドのデザインにそこまでこだわらない（以前にhologramいれてみたけど、デザインカスタマイズにすごい時間割いた記憶があるので・・）のであれば、LivingStyleGuideを導入するのがいいのではないかと思った。

あと、細かく見てないがv2.0で大幅にアップデートされるっぽい。