kss-nodeの導入

# kss-node
kss-nodeの導入方法について備忘録的に書いてみます。
kss-nodeは、広く知られるスタイルガイドジェネレーターKSSのNode実装版になります。
https://github.com/kss-node/kss-node

## 導入方法

まず、npmでインストール

```
$ npm install -g kss
```

以下は設置の一例です。
Sassを使用しているとして、例えば下記のようなディレクトリ構成だとします。

```
├ css
│  └ style.css
└ scss
 　├ style.scss
 　└ styleguide.md
```

`style.scss`には以下のような形式でコメント、SCSSを記述しておきます。

```
// Button
//
// Buttons can and should be clicked.
//
// Markup:
// <button class="button {{modifier_class}}">
//
// :hover    - Highlights when hovering.
// :disabled - Dims the button when disabled.
// .primary  - Indicates button is the primary action.
// .smaller  - A little bit smaller now.
//
// Styleguide 1.1

.button {
  ...
  &.primary {
    ...
  }
  &.smaller {
    ...
  }
  &:hover {
    ...
  }
  &:disabled {
    ...
  }
}
```

`css/style.css`は上記のscssがコンパイルされたものとします。


下記コマンドを実行

```
$ kss-node sass styleguide --css ../css/style.css
```

すると、

```
├ css
│  └ style.css
├ scss
│　├ style.scss
│　└ styleguide.md
└ styleguide
 　├ index.html
 　├ public
 　└ section-1.html
```

と出力され、`/styleguide/index.html`をブラウザで表示するとスタイルガイドが確認できます。

コマンド解説をしますと、

```
$ kss-node (生成元のディレクトリ) (出力先のディレクトリ) --css (生成されたスタイルガイドで読み込むCSSのパス)
```
となっています。環境によってディレクトリ名やパスは異なります。

### 備考
- スタイルガイドはMarkdownファイルから生成されるため、生成元のディレクトリ内に、`styleguide.md`という名前でファイルを用意しておく。
- 生成されたスタイルガイドで読み込むCSSのパスは、指定したパスがそのまま出力される。コマンドを実行したディレクトリからの相対パスではない。  
（生成されたスタイルガイド内で、CSSが反映されなくてしばらくハマりました。。）

## コメントの書き方

```
// Button（タイトル）
//
// Buttons can and should be clicked.（説明）
//
// Markup:
// <button class="button {{modifier_class}}">
//
// :hover    - Highlights when hovering.
// :disabled - Dims the button when disabled.
// .primary  - Indicates button is the primary action.
// .smaller  - A little bit smaller now.
//
// Styleguide 1.1

.button {
  ...
  &.primary {
    ...
  }
  &.smaller {
    ...
  }
  &:hover {
    ...
  }
  &:disabled {
    ...
  }
}
```

- 1行目はタイトル
- タイトルの下に1行開けて書くと説明文
- `:hover` `:disabled` `.primary`など1行ずつ書くと、スタイルガイドにその分を繰り返し生成される。
- `{{modifier_class}}` の箇所に指定したクラスが挿入される。（ここでは `.primary` と `.smaller`)
- `Styleguide` の後ろに「数字」+「.」+「数字」とすると章の構成を作れる。（ここでは `Styleguide 1.1`）  
  例えば、タイトルを「Modules」としたコメントエリアの最後に「Styleguide 1.」と書き、タイトルを「Buttons」としたコメントエリアの最後に「Styleguide 1.1」と書くと、「1 Modules」の中の「1.1 Buttons」となる。
- コメントの「Styleguide」に対応して、`section-1.html`、`section-2.html`のような形でスタイルガイドが出力される。

### 備考
- コメント内の`{{modifier_class}}`については、`${modifiers}`と紹介されてる記事も多いが、仕様変更があり現在は`{{modifier_class}}`が正しい。  


## テンプレート
そのまま生成されたスタイルガイドはデザインがイケてません。スタイリッシュなテンプレートがありますのでこちらを利用すると良いかと思います。
[htanjo/kss-node-template](https://github.com/htanjo/kss-node-template)
一例ですが、設置方法としては、例えばダウンロードしたtemplateフォルダを以下のように置いたとします。

```
├ css
│  └ style.css
├ scss
│　├ style.scss
│　└ styleguide.md
└ template
```
下記のようにコマンドを実行します。

```
$ kss-node sass styleguide --css ../css/style.css --template template
```
`--template`としたあとに、そのパスを設定します。

## コマンド

```
$ kss-node [options]
```

```
File locations:
  --source       Source directory to parse for KSS comments                                                     [文字列]
  --destination  Destination directory of generated style guide                      [文字列] [デフォルト: "styleguide"]
  --mask, -m     Use a mask for detecting files containing KSS comments
                                                     [文字列] [デフォルト: "*.css|*.less|*.sass|*.scss|*.styl|*.stylus"]
  --config, -c   Load the kss-node configuration from a json file

Template:
  --clone, --init, -i  Clone a style guide template to customize                                                [文字列]
  --template, -t       Use a custom template to build your style guide
                          [文字列] [デフォルト: "../../../usr/local/lib/node_modules/kss/generator/handlebars/template"]

Style guide:
  --css          URL of a CSS file to include in the style guide                                                [文字列]
  --js           URL of a JavaScript file to include in the style guide                                         [文字列]
  --custom       Process a custom property name when parsing KSS comments                                       [文字列]
  --helpers      Location of custom handlebars helpers; see http://bit.ly/kss-wiki                              [文字列]
  --homepage     File name of the homepage's Markdown file                        [文字列] [デフォルト: "styleguide.md"]
  --placeholder  Placeholder text to use for modifier classes                  [文字列] [デフォルト: "[modifier class]"]
  --nav-depth    Limit the navigation to the depth specified                                             [デフォルト: 3]
  --title        Title of the style guide                                       [文字列] [デフォルト: "KSS Style Guide"]

オプション:
  --verbose       Display verbose details while generating                                                    [カウント]
  --xdemo         Builds a KSS demo.                                                          [真偽] [デフォルト: false]
  --//            JSON configurations will ignore comments.
  --help, -h, -?  ヘルプを表示                                                                                    [真偽]
  --version       バージョンを表示                                                                                [真偽]
```

## 参考

- kss-node https://github.com/kss-node/kss-node
- Quick Start Guide https://github.com/kss-node/kss-node/wiki/Quick-Start-Guide
- コメントの書き方→ https://github.com/kss-node/kss/blob/spec/SPEC.md
- [いまどきのスタイルガイドジェネレータ](http://www.september-creator.com/2013/07/styleguide/)
- [KSS-NODEのREADMEを日本語訳したったった](http://35n139e.tumblr.com/post/55750248543/kss-node%E3%81%AEreadme%E3%82%92%E6%97%A5%E6%9C%AC%E8%AA%9E%E8%A8%B3%E3%81%97%E3%81%9F%E3%81%A3%E3%81%9F%E3%81%A3%E3%81%9F)
- [スタイルガイドに KSS を導入](http://moqada.hatenablog.com/entry/2014/02/13/233411)