gulp-hologramを導入してみた
gulpのtaskを書いていたので、スタイルガイドジェネレータを導入してみました。
たまたまCodeGridで「hologram（ホログラム）」というスタイルガイドジェネレータを紹介されていたので導入してみました。
Hologram — Style Documentation Build System
hologramは、Rubyで書かれたスタイルガイドジェネレータです。
CodeGridの記事でも書かれていましたが、若いオープンソースプロジェクトのためドキュメントが豊富ではない・気の利いたテンプレートが用意されているわけではないそうです。
今回、導入したテンプレートもCodeGridで作成されたテンプレート埋め込む形で対応しました。
のちほど、ソースを読んで自分でカスタマイズする予定です。
gulp-hologramをインストール
package.jsonを読みこめば npm installでインストールできるのですが、
gulp-hologramは、うまくこれだけはうまくスタイルガイドを生成させることができなかったです。
gulpが原因？・バージョンアップ等がされていたのか原因は掴めませんでした
- 原因が分かり次第、追記予定
npm install gulp-hologram@1.0.1
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上のリポジトリが複数のプラグインを組み合わせたものになります。