LivingStyleGuideでスタイルガイドを作ってみた


現在担当しているプロジェクトでLivingStyleGuideをいれてみたのでメモ。
公式サイトは[こちら](http://livingstyleguide.org/)

## できることとかできないこととか
- マークダウンで記述するスタイルガイド
- 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で大幅にアップデートされるっぽい。