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
一例ですが、設置方法としては、例えばダウンロードした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 バージョンを表示 [真偽]