grunt-kssでスタイルガイド作成

スタイルガイド作成にgrunt-kssを使うと便利で楽チンでしたので、grunt-kssを敢えて紹介。

grunt-kssとは

grunt-kssは、KSSというスタイルガイドジェネレータのGruntプラグインです。

grunt-kssのインストール

grunt-kssをインストールするには下記のコマンドをターミナルに入力し、力強くEnterキーを押します。

npm install grunt-kss

インストールが終わったら、Gruntfile.js(ここではgruntfile.coffeeで記述しています。)にタスクを追加します。

kss:
	options:
		includeType: 'css'
		includePath: '/css/style.css'
	dist:
		files:
			'styleguide': ['htdocs/css']


//タスクの登録
grunt.registerTask "style", [
	"compass"
	"kss"
]
includeType: 'css'
grunt-kssのサイトには、sassを指定することが可能なように書いていますが、ここをsassを指定すると空のcssができてしまいます。バグかなんかでしょうか。cssを指定すると特に問題ありませんのでここはcssを指定
includePath: '/css/style.css'
スタイルガイド用のHTMLで読み込むCSSを指定します。
'styleguide': ['htdocs/css']
styleguideディレクトリにスタイルガイド用のHTMLを生成し、htdocs/css以下のCSSをパース

そして、scssににスタイルガイド用のコメントを書きます。

// Heading(モジュール名)
//
// 見出しのモジュールです。(モジュールの説明)
//
// .title - フォントサイズを14pxにしちゃいます。(モジュールの付属classの説明とか)
//
// Markup:
// <h2 class="mod-heading {$modifiers}">見出し</h2>(マークアップ例)
//
// Styleguide 1(スタイルガイドの章)

.mod-heading {
	border-left: 5px solid #B7B800;
	padding-left: 8px;
	&.title {
		font-size: 14px;
	}
}

そして、下記のコマンドをターミナルに入力し、力強くEnterキーを押してスタイルガイド用のHTMLを作成します。

grunt style

下記図のような感じでスタイルガイドが作成されます。

blog20140601-01.png

レイアウト変更

デフォルトのままだと上記のような感じな見た目になります。デフォルトのレイアウトが気に食わないときは

node_modules > grunt-kss > node_modules > kss > lib > template

にある index.html に手を加えてやれば簡単にレイアウトを変更することができます。

しかし、複数人で開発をしている場合、node_modules内のGruntプラグインはGit等で管理していないケースがほとんどだと思います。

そのため別の人がテンプレートを更新変更できない場合があります。そのような問題を孕むためテンプレートのHTMLはnode_modules内から切り離したくなります。

テンプレート用のフォルダを作成

テンプレートのHTMLをnode_modules内から切り離すためには、grunt-kssではtemplateというオプションがあるのでテンプレート用のフォルダを作成し、下記のようにgruntfile.jsに記述します。(テンプレートのHTMLは、node_modules > grunt-kss > node_modules > kss > lib > template にあるindex.htmlをそのままもってきてHTMLを変更すると楽です。)

kss:
	options:
		template: 'styleguide/template'  //テンプレート用のフォルダを指定
		includeType: 'css'
		includePath: '/css/kss.css'
	dist:
		files:
			'styleguide': ['htdocs']

例えば、仮に柿のような感じのHTMLにして、それに合わせていい感じの見た目にするCSSを書いてやるだけでレイアウトの変更ができます。

  <div role="main" id="kss-main">
    <article id="kss-content">
      {{#if overview}}
        {{html overview}}
      {{else}}
        {{#eachSection rootNumber}}
          {{#whenDepth 1}}
            <h1 class="kss-title"><span class="kss-ref">{{ reference }}.0</span> - {{ header }}</h1>
          {{else}}
           <section class="kss-depth-{{ refDepth }}">
            <h1 class="kss-title"><span class="kss-ref">{{ reference }}</span> - {{ header }}</h1>
          {{/whenDepth}}
            {{#ifAny markup modifiers}}
                <!-- モジュールの説明の箇所 -->
                <div class="kss-box">{{html description}}</div>
                  <div class="kss-mode-view-example">
                    {{modifierMarkup}}
                  </div>
                {{#eachModifier}}
                  <!-- class名の箇所 -->
                  <h2 class="kss-mod-heading">{{name}}</h2>
                  <!-- class名の説明の箇所 -->
                   <p class="kss-mod-desc">{{html description}}</p>
                  <!-- プレビューの箇所 -->
                  <div class="kss-mode-view-example">
                    {{modifierMarkup}}
                  </div>
                {{/eachModifier}}
                <div class="kss-markup">
                  <!-- マークアップ例の箇所 -->
                  <pre class="prettyprint lang-html">{{markup}}</pre>
                </div>
            {{else}}
                {{#if description}}
                  {{html description}}
                {{/if}}
            {{/ifAny}}
          {{#whenDepth 1}} {{else}}
            </section>
          {{/whenDepth}}
        {{/eachSection}}
      {{/if}}
    </article>
  </div>
blog20140601-02.png

まとめ(というか感想)

grunt-kssを使うと簡単にスタイルガイドを作成でき、且つレイアウト変更もそれなりに自由にできるので、シャレ乙な感じのスタイルガイドを作成したい場合にはよいツールです。