gulp-hologramを導入メモ

# gulp-hologramを導入してみた

gulpのtaskを書いていたので、スタイルガイドジェネレータを導入してみました。
たまたまCodeGridで「hologram（ホログラム）」というスタイルガイドジェネレータを紹介されていたので導入してみました。

[Hologram — Style Documentation Build System](http://trulia.github.io/hologram/)

hologramは、Rubyで書かれたスタイルガイドジェネレータです。
CodeGridの記事でも書かれていましたが、若いオープンソースプロジェクトのためドキュメントが豊富ではない・気の利いたテンプレートが用意されているわけではないそうです。
今回、導入したテンプレートもCodeGridで作成されたテンプレート埋め込む形で対応しました。
のちほど、ソースを読んで自分でカスタマイズする予定です。

* [https://github.com/codegrid/hologram](https://github.com/codegrid/hologram)

## gulp-hologramをインストール

package.jsonを読みこめば `` npm install ``でインストールできるのですが、
gulp-hologramは、うまくこれだけはうまくスタイルガイドを生成させることができなかったです。

gulpが原因？・バージョンアップ等がされていたのか原因は掴めませんでした

* 原因が分かり次第、追記予定

```
npm install gulp-hologram@1.0.1
```

## gulp-hologram リポジトリ・ドキュメント

* [https://www.npmjs.org/package/gulp-hologram](https://www.npmjs.org/package/gulp-hologram)
* [https://github.com/rejahrehim/gulp-hologram](https://github.com/rejahrehim/gulp-hologram)

## ディレクトリ／ファイル構造

CodeGridの記事では、ディレクトリに分けて整理していましたので、
参考してgulpで作ったディレクトリ構成に合わせて調整してみました。

* _develop/common/css/styleGuide.css：スタイルガイド用のCSSを格納
* public_html/guide/：スタイルガイドのHTMLが出力されるディレクトリ
* hologramStuff/：hologramに必要なファイル群を格納

hologramStuff一式とstyleGuide.cssは、githubに公開されていたものをそのまま使わせていただきました。
下記のような形で、ディレクトリに分けて作りました。

* gulpのbrowser-syncを使用していたため、public_htmlの中に生成されるように調整

```
project_directory
├── _develop
│   └── common
│       └── css
│           └── styleGuide.css // スタイルガイド用のCSS
├── public_html
│   └── guide // スタイルガイドのHTMLを出力する先
└── hologramStuff // hologramに必要なファイルを格納
    ├── config.yml // hologramのコンフィグ
    ├── templateSample.html // スタイルガイドのテンプレート見本
    └── templates // スタイルガイド用のテンプレートファイル群を格納
        ├── _footer.html
        └── _header.html
```

## confug.ymlを設定

* configファイルは、YAML形式で記述

```
# Hologram config

# The directory containing the source files to parse
source: ../public_html/common/css

# The directory that hologram will build to
destination: ../public_html/guide/

# The assets needed to build the docs (includes header.html, footer.html, etc)
documentation_assets: ../hologramStuff/templates

# This is a custom markdown renderer (see Redcarpet documentation for
# how to do this)
custom_markdown: ../hologramStuff/markdown_renderer.rb

# Any other asset folders that need to be copied to the destination folder
# This where you should include your full stylesheets, component javascript,
# libraries and any other dependencies your style guide will have
# dependencies:
#   - ./build
index: block
```

### source

sourceには、パースしたいファイル（スタイルファイルなど）一式のディレクトリ先

* 分割しているsassで出力することができるが、1ページにまとめたかったのでsassで書きだしたcssを読み込むことにしました。

### destination

スタイルガイドのHTMLを出力するディレクトリ先

### documentation_assets

スタイルガイドを作るためのテンプレート一式のディレクトリ先

### custom_markdown

Redcarpetを拡張したいときに使用（Rubyの知識が必要）

## スタイルガイド用のコメント

CSSまたはSCSSファイルの中にコメントとして書かれたYAML・markdownをパースして、スタイルガイドを作成する

```
/*doc
---
title: setting style // タイトル名
name: block-setting // セクション名
category: block // カテゴリ名
---

sample

*/
```

## gulpfile.jsを記述

gulp-load-pluginsで、Gruntで同じようなpackage.jsonを読み込むように設定しています。

```
var gulp = require('gulp'),
    $ = require('gulp-load-plugins')({
        pattern: ['gulp-*', 'gulp.*'],
        replaceString: /\bgulp[\-.]/
    });

// hologramのタスク
gulp.task('hologram', function() {
  return gulp.src('hologramStuff/config.yml')
    .pipe($.hologram());
});

// watchタスク
gulp.task('default', function() {
     gulp.watch('public_html/common/css/common.css', ['hologram']);
});
```

情報が少なかったので、CodeGridの記事は本当に助かりました。
もう少し情報が出てきた時に、記事を編集していきたいと思います。

## gulp-template作成中

現在、gulpのtaskを自分用のtemplateとして作成しています。
今回は、タスクを一部に絞りましたが、Github上のリポジトリが複数のプラグインを組み合わせたものになります。

* [Github：141014_gulp-template](https://github.com/redamoon/141014_gulp-template)

## 参考サイト

* [hologramでカスタムスタイルガイド：機能概要](https://app.codegrid.net/entry/hologram-1)
* [hologramでカスタムスタイルガイド：インストールとconfig設定](https://app.codegrid.net/entry/hologram-2)
* [hologramでカスタムスタイルガイド：テンプレートとRedcarpet](https://app.codegrid.net/entry/hologram-3)
* [hologramでカスタムスタイルガイド：hologram1.2のアップデート](https://app.codegrid.net/entry/hologram-4)
* [hologramでカスタムスタイルガイド：細かなカスタマイズ](https://app.codegrid.net/entry/hologram-5)
* [gulp-hologram : 1.0.1 - VersionEye](https://www.versioneye.com/nodejs/gulp-hologram/1.0.1)