賢く使うStyleDocco導入ガイド 前編 基本的な使い方
短期集中連載の第1回目はStyleDoccoの基本的な使い方を解説します。インストールからスタイルガイド生成までの過程を順を追って紹介しています。
StyleDoccoとは
StyleDoccoとは、Node.jsで作られたスタイルガイドジェネレータ*です。
*注：スタイルガイドジェネレータ
StyleDocco以外にもRuby製のKSS、KSSのNode.js製kss-node、HTMLベースのKaleiなどもあります。
CSSに適切なコメントを書くことで、CSSのスタイルガイドを自動的に作成することができます。
スタイルガイドは、開発中やサイトの運営中に、デザインが変更されるたびに、細かくメンテナンスをする必要があります。情報がメンテナンスされていないスタイルガイドでは意味がありません。しかしながら、HTMLとCSSをそのつど書き直すメンテナンス作業は、若干手間がかかります。
StyleDoccoは、CSSに所定のコメントを書いておくだけで、そこからスタイルガイドを自動的に生成してくれますので、間違いもなく、メンテナンス作業も軽減されます。
StyleDoccoで生成されるスタイルガイドは、次のようになります。
［サンプルを新しく開く］ボタンで別ウインドウ（タブ）を開くとページ全体がわかります。
ご覧のように、スタイルガイドはHTMLページとして書き出されます。ページ左側にレンダリング結果、その元となるHTMLが表示され、ページ右側にHTMLに指定されたCSSのコードが表示されます。
スタイルの変更時に、CSSのコメントを変更していくだけで、このようなスタイルガイドが自動的に作成されますので、いちいちスタイルガイドのHTMLやCSSを書き直す手間がありません。
どんな開発環境への導入が向いているか
しかしながらStyleDoccoは、すべての開発環境向きとはいえません。
前述したようにCSSのコメントを利用してスタイルを生成します。CSSそのものにコメントを付け加えていくと、CSSの容量が増えます*。スタイルが自動生成されるメリットはありますが、一方でCSSが重くなり、サイト全体のパフォーマンスが落ちる可能性を考えると、デメリットの方が大きくなってしまいます。
*注：コメントの処理
CSSのコメントなどを自動的に消去してくれるminifyツールがあれば、この点は改善できるかもしれません。
一方、SassなどCSSのプリプロセッサが導入されていれば、コンパイル前のソースファイルからスタイルガイドを生成することができます（使い方は後述します）。こうすれば、スタイルを自動生成し、かつCSSそのものを軽く保つことができます。
また、スタイルの生成作業を簡単に行うためにはGruntを使うのが便利です。
以上のような理由から、この記事では、Grunt、Sassを導入済みの開発環境を対象として、解説を進めていきたいと思います。もし、GruntやSassにあまりなじみのない方は、以下のシリーズを参照してください。
StyleDoccoを導入する
それではStyleDoccoのインストールから始めてきましょう。なお、この記事で使うサンプルは以下のGitHubのリポジトリにまとめてあります。
StyleDoccoサンプルデータ
StyleDoccoの導入には、Gruntのプラグインであるgrunt-styleguideを使用します。
grunt-styleguideは、StyleDoccoとkss-nodeのラッパーで、Gruntのオプションで指定することで、好きなスタイルガイドを選択することができます。
導入する環境は、以下のようなファイル構成を想定しています。
project/
┣ package.json
┣ _previews.js
┣ Gruntfile.js
┣ docs/ // このディレクトリにスタイルガイドを書き出す
┗ css/
┗ src/ // このディレクトリ内のscssファイルがスタイル生成の対象
┣ README.md // スタイルガイドのトップページに変換される
┣ style.scss
┗ partial/
┗ _mixin.scsscss/srcに作成したscssを元に、docs/にスタイルガイドを生成して、書き出します。
scssを使ったプロジェクトは、ファイル分割などをすることがあると思うので、css/src/partialというサブディレクトリを作成し、よく使うmixinをまとめた_mixin.scssを設置しておきます。_mixin.scssはstyle.scssで@importして使用します。
README.mdはスタイルガイドのトップページとして生成されるので、コーディングガイドラインや注意書き、使用しているフレームワークなどについて書いたり自由に使うことができます。
StyleDoccoを試す
サンプル1：StyleDoccoを試す
まず、必要なパッケージをインストールします。今回はStyleDoccoはグローバルではなくプロジェクトローカルに、プロジェクトのディレクトリで、以下のコマンドを実行し、インストールします。
$ npm installpackage.jsonの中身を見ると、以下のnpmをインストールしていることがわかります。
- grunt：Grunt本体
- styledocco：StyleDocco本体
- grunt-styleguide：styledoccoとkss-nodeのラッパー。Gruntタスクのオプションで使用するスタイルガイド（今回の場合はstyledocco）を指定できる
- grunt-contrib-clean：ファイルを消去するGruntのプラグイン
grunt-contrib-cleanは、今回のタスクには関係なさそうに思えますが、使用用途とその理由は後述します。
Gruntfile.js
次にGruntfile.jsの中身を見てみましょう。
主にstyleguideとcleanの2つのタスクを登録しています。ポイントとなる部分だけ解説します。
styleguideについて
styleguideタスクは次のように定義されています。
...
styleguide: {
styledocco: {
options: {
name: 'Project Name',
framework: {
name: 'styledocco'
options: {
preprocessor: 'sass'
}
},
template: {
include: [
'_previews.js'
]
}
},
src: ['css/src/**/*.scss'],
dest: 'docs'
}
},
...まずoptionsで、使用するframeworkにstyledoccoを指定し、CSSプリプロセッサ*がsassであることも指定しています。Project Nameに指定された文字列は、生成されるスタイルガイドの左上のタイトルとなります。
*注：CSSプリプロセッサの指定
grunt-styleguideのデフォルト生成コマンドはsass --compassとなっており、CSSプロプロセッサはsassでCompassを使う設定になっています。Gruntfileでこの指定を上書きしないと、Compassがインストールされていない環境では、スタイルガイドにCSSが反映されなくなってしまいます。
srcはスタイルガイドの元になるSCSSファイルを指定します。今回はcss/src/**/*.scssと指定することで、css/src/以下のすべてのSCSSファイルを対象にしています。
destはスタイルガイドを生成したいディレクトリ名を指定します。存在しない場合は新しく作成されます。
さらにtemplateでプレビューエリア内に任意のJSやCSSを読み込ませることができます。今回は_previews.jsを読み込ませていますが、このファイルが必要な理由は次回解説します。
cleanについて
grunt-styleguideを使った場合の不具合で、SCSSを編集して再度生成を行っても変更が反映されないことがあります。
そこでgrunt-contrib-cleanを使い、ディレクトリの削除を行っています。
...
clean: {
styleguide: '<%= styleguide.styledocco.dest %>'
}
...空にするディレクトリ名の指定は'<%= styleguide.styledocco.dest %>'を使用することで、スタイルガイドの生成先を再度入力することなく指定することができます。
スタイルガイドのためのコメントの書き方
StyleDoccoを使う環境は整いましたので、次にスタイルガイドに使うコメントの書き方について解説します。
コメントを書く場所
コメントはSCSSファイルの中に、複数行コメント/* */、もしくは行コメント//を入れ*、コメントの中にMarkdown形式で記入していきます。
*注：行コメント
行コメントが使えるのはSCSSファイルのみで、通常のCSSファイルでは当然ですが、使えません。
セクションの分割
h1見出し（#）ごとに、スタイルガイドのセクションが分割されていきます。
プレビューするHTMLの指定
プレビューしたいHTMLをコードフェンス```で囲うか、4スペースでインデントすると、スタイルガイドにプレビューとして表示されます。
プレビューするHTMLのclass属性に:hoverなどの擬似セレクタを書くことで、わざわざそのアクションをしなくても、疑似レセクタが適用された状態の見た目を確認することができます。
StyleDoccoが対応している擬似セレクタは、次の通りです。
:link:visited:active:focus:target:enabled:disabled:checked
適切にコメントを入れたSCSSファイルは、例えば、このようになります。
/*
# サイト全体で使うCSS
全ページで、このCSSを読み込む。
*/
@import 'partial/mixin';
/*
# 1.ボタン
ボタンです
## 汎用ボタン
<button class="mod-btn" href="#">ボタン</button>
<button class="mod-btn :hover" href="#">ボタン(:hover)</button>
*/
.mod-btn {
display: inline-block;
padding: 5px;
background-color: white;
&:hover {
background-color:gray;
}
}
// ## 特殊なボタン
//
// ```
// <a class="mod-btn2" href="#">ボタン</a>
// <a class="mod-btn2 :hover" href="#">ボタン(:hover)</a>
// ```
//
.mod-btn2 {
display: inline-block;
padding: 5px;
background-color: lime;
&:hover {
background-color: tomato;
}
}
/*
# 2.ナビゲーション
<nav class="mod-nav">
<a class="mod-nav-item is-active" href="#">Nav1</a>
<a class="mod-nav-item" href="#">Nav2</a>
<a class="mod-nav-item" href="#">Nav3</a>
<a class="mod-nav-item" href="#">Nav4</a>
</nav>
*/
.mod-nav {
overflow: hidden;
}
.mod-nav-item {
display: block;
float: left;
width: 25%;
text-align: center;
background: #ccc;
&.is-active {
@include pointer-events(none);
background-color: tomato;
}
}Scssファイルからスタイルガイドを生成する
あとは、以下のコマンドでgruntのタスクを実行するだけです。
$ gruntStyleDoccoにより生成されるスタイルガイドのhtmlファイル名は、SCSSのファイル名と同じになります。src内にサブディレクトリがあり、その中にSCSSファイルがある場合は、サブディレクトリ名-SCSSファイル名となります。
サブディレクトリは左上のナビゲーションにドロップダウンメニューとして追加されます。
css/src/README.mdはindex.htmlとして生成されます。
したがって、スタイルガイドを生成すると、次のようなディレクトリ構成になります。
project/
┣ package.json
┣ _previews.js
┣ Gruntfile.js
┣ docs/
┃ ┣ index.html
┃ ┣ partial-mixin.html
┃ ┗ style.html
┗ css/
┗ src/
┣ README.md
┣ style.scss
┗ partial/
┗ _mixin.scss［サンプルを新しく開く］ボタンで別ウインドウ（タブ）を開くとページ全体がわかります。
プレビューエリアに、ボタンの通常時のスタイルと、ボタンにマウスが乗った状態の（疑似セレクタ:hover）スタイルが表示されます。
h1相当の#を使うことで、ボタンとナビゲーションのセクションが分割されていることがわかります。
まとめ
今回はStyleDoccoの導入から、コメントを書き、スタイルガイドを生成するまでの一通りの作業を解説しました。
次回は、生成されたスタイルガイドが持つ機能や、コメントの書き方のTips、トラブルを起こしやすいポイントなど、細かな使いこなしについて解説します。