sc5-styleguideとgulp-webserverを一緒に使う

開発用WEBサーバー（gulp-webserver）とスタイルガイドのサーバー（sc5-styleguide）を一緒に使った時に共通の静的コンテンツをみる方法を試行錯誤したので紹介します。

スタイルガイドジェネレータ[sc5-styleguide](http://styleguide.sc5.io/)については、いくつか記事がすでに書かれているので、環境構築については本稿では割愛します。
次を参考にしました。

- [スタイルガイドジェネレータのsc5-styleguideがいい感じそうだったので試してみた](http://qiita.com/shwld/items/188fd8495ada8e6d3125)
- [sc5-stylgeduigeの記述方法](http://qiita.com/sygw/items/55e6a3916312c502bc4f)
- [sc5-styleguideを使用したのでまとめてみました](http://qiita.com/tatsuyankmura/items/e1ed4c67fec602e6b33d#_reference-69233094305a1bf4785d)

開発用WEBサーバー[gulp-webserver](https://github.com/schickling/gulp-webserver)も言わずと知れたgulp用のプラグインなので割愛します。

- [gulp.js その2 gulp-webserverでWebサーバー/ライブリロード](http://qiita.com/oreo3@github/items/8b3bff9aed7b10ebe757)
- [gulp-webserverで開発用WEBサーバーを立ち上げる](http://labs.septeni.co.jp/entry/2015/10/26/233737)

## 経緯

sc5-styleguideはKSSのコメント記法を受け継いだNode.js実装のスタイルガイドジェネレータです。
例えば、scssに次のような設定コメントを書いておけば

```scss:button.scss
// Button
// 
// ボタン
// 
// Markup:
// <div class="button">
//   <a href="#">Button</a>
// </div>
//
// Styleguide 1.0.0

.button {
  width: 240px;
  margin-left: auto;
  margin-right: auto;
  & > a {
    display: block;
    text-align: center;
    padding: 12px;
    color: #333;
    border: 1px solid #ddd;
    &:hover {
      color: #fff;
      background: #000;
    }
  }
}
```
次のようなスタイルガイドが作成されます。
![スクリーンショット 2016-09-22 18.13.53.png](https://qiita-image-store.s3.amazonaws.com/0/50783/bb0b9694-12f3-c293-9dd6-e68a2a07acb9.png)

このようにコメントの`MarkUp`の下部にマークアップを記述すると、スタイルガイドにはスタイルがあった状態でレンダレングされます。
さらに、下部にはレンダリングされていない状態のマークアップがあるので、理想的な使い方としては、このボタンを作りたいところにコピペすればよいことになります。

さて、このときjpgやpngなどのイメージファイルを呼び出したい場合、どうすればよいか困ったのがきっかけです。
例えば、先ほどのボタンを例に挙げるとアイコン画像を文字の前に置く場合です。

```scss:button.scss(コメント抜粋)
// Button
// 
// ボタン
// 
// Markup:
// <div class="button">
//   <img src="/images/icon.png">
//   <a href="#">Button</a>
// </div>
//
// Styleguide 1.0.0
```

上記のようにMarkupを記載したとき、スタイルガイドでもちゃんと画像が表示され、かつ、開発中のコンテンツでも同じパスで画像を表示するようにするにはどうすればよいのでしょうか。

実はsc5-styleguideのREADMEにはその場合のことが書かれていました。
https://github.com/SC5/sc5-styleguide#images-fonts-and-other-static-assets
![スクリーンショット 2016-09-22 18.38.12.png](https://qiita-image-store.s3.amazonaws.com/0/50783/d6e28f0b-ff9f-e203-d8bc-a5938ebdb821.png)

ここに書かれている対処方法はそれぞれのサーバーにコピーして置けというものです。もし資材に変更があればoutput先を両方にしとけばよいと書かれています。

しかし、私のプロジェクトでは画像ファイルが大量にあるので、この方法には賛同できませんでした。
そのため、コンテキストルートを一緒にする方法を考えました。

## 方法
結論から言うと、スタイルガイドの設定だけでは無理だったので、gulp-webserverのリバースプロキシを使って実現します。

開発用WEBサーバーのポートを3000、
スタイルガイドのサーバーのポートを4000としたとき、
スタイルガイドのページへは次のURLでアクセスするようになります。
`http://localhost:3000/styleguide/`

### ディレクトリ構成
単純に次のようになります。

```ディレクトリ構成:ディレクトリ構成
├── dist <- 開発中のソースをビルドしたものの出力先
│   ├── img
│   ├── css
│   ├── ...
│   └── styleguide <- スタイルガイドのコンテンツ
│       ├── index.html <- スタイルガイドのTOPページ
│       ├── assets <- 自動で生成されるガイドで使う画像とか
│       ├── css <- 自動で生成されるガイドのスタイルを整えるcss群
│       ├── js <- 自動で生成されるガイドで使うjs群
│       └── ...
```

### gulpfile.js
試行錯誤の結果、次のようになりした。

* gulp-webserverで  
`http://localhost:3000/styleguide/`  
にアクセスされたら次にアクセスするようにする。  
`http://localhost:4000/`
* スタイルガイドのTOPページへは次でアクセスできるようにする。  
`http://localhost:4000/`
* スタイルガイドのTOPページで定義している静的コンテンツのパスは次となるようにする。  
例えばこんな感じ  
`<link rel="icon" href="/styleguide/assets/img/favicon.ico">`  

```js:gulpfile.js
const gulp = require('gulp')
const webserver = require('gulp-webserver')
const styleguide = require('sc5-styleguide')

gulp.task('webserver', () => {
  gulp.src('./dist')
    .pipe(webserver({
      livereload: true,
      host: '0.0.0.0',
      port: 3000,
      proxies: [{
        source: '/styleguide',            //<-(1)
        target: 'http://localhost:4000/'
      }, {
        source: '/socket.io',             //<-(２)
        target: 'http://localhost:4000/socket.io/'
      }]
    }))
})

gulp.task('styleguide:generate', () => {
  return gulp.src('./src/**/*.scss')
    .pipe(styleguide.generate({
        port: 4000,
        title: 'Style Guide',
        server: true,
        rootPath: './dist/styleguide',  //<-(3)
        appRoot: '/styleguide',         //<-(4)
        overviewPath: 'README.md'
      }))
    .pipe(gulp.dest('./dist/styleguide'))
})

gulp.task('styleguide:applystyles', () => {
  return gulp.src('./src/**/*.scss')
    .pipe(styleguide.applyStyles())
    .pipe(gulp.dest('./dist/styleguide'))
})

gulp.task('styleguide', ['styleguide:generate', 'styleguide:applystyles'])

```
1. **proxies**  
gulp-webserverのプロキシの設定です。
`http://localhost:3000/styleguide/`にアクセスされたら  
`http://localhost:4000/`にアクセスする  
を実現しています。
2. トライアンドエラーで必要だとわかったので設定しました。
3. **rootPath**  
スタイルガイドのルートパスです。  
`http://localhost:4000/`でスタイルガイドのTOPページが表示できるようにするため`./dist/styleguide`にします。
4. **appRoot**  
これはルートディレクトリ以外のディレクトリからスタイルガイドをホスティングする場合に定義します。  
つまり、先ほどのスタイルガイド用静的コンテツのパスが、設定しなければ  
`<link rel="icon" href="/assets/img/favicon.ico">`  
となるのところを`/styleguide`と設定することで  
`<link rel="icon" href="/styleguide/assets/img/favicon.ico">`  
となります。

あとは[gulp-webserver](https://github.com/schickling/gulp-webserver)と[sc5-styleguide](http://styleguide.sc5.io/)のREADME通りです。

これで、共通の静的コンテンツを参照するようになりました。

# 参考
http://qiita.com/shwld/items/188fd8495ada8e6d3125
http://qiita.com/sygw/items/55e6a3916312c502bc4f
http://labs.septeni.co.jp/entry/2015/10/26/233737
http://sanooo.jp/gulp/sc5-styleguide-settings/