Grunt ではじめるタスクランナー シリーズGruntでhologramを使う

Jekyllのブログにhologramを使ってスタイルガイドを作ることにしたのでとりあえずgrunt-hologramについて調べてみた。jekyllに組み込んでみたサンプルがこちら。

準備

grunt-hologramを使うにはhologram本体とgrunt-hologramをインストールします。

hologramのインストール

今回rbenvとbundlerを使っている前提で進めます。hologramをGemfileに追記します。

gem "hologram"

grunt-hologramのインストール

公式の通りにgrunt-hologramをインストールします。

$ npm install grunt-hologram --save-dev

テンプレートを作る

スケルトンを使ってテンプレートを用意します。適当にディレクトリを用意してコマンドを実行します。

$ bundle exec hologram init
Created the following files and directories:
  hologram_config.yml
  doc_assets/
  doc_assets/_header.html
  doc_assets/_footer.html
  code_example_templates/
  code_example_templates/markdown_example_template.html.erb
  code_example_templates/markdown_table_template.html.erb
  code_example_templates/js_example_template.html.erb
  code_example_templates/jsx_example_template.html.erb

これでコンフィグファイルを含むテンプレートが作られます。コンフィグファイルの名前や書き出し先のディレクトリ名は編集しても問題ありません。

タスクの設定

タスクには特に細かな記述は行わずconfigファイルへのパスだけ設定します。

hologram.js

私の環境ではタスクファイルを分割しているので下記のような指定にしています。

module.exports = {
  generate: {
    options: {
      config: 'src/_hologram/config.yml'
    }
  }
}

config.yml

スケルトンから作られたコンフィグファイルをベースに環境に合わせてコンフィグを調整します。

# Hologram will run from same directory where this config file resides
# All paths should be relative to there

# The directory containing the source files to parse recursively（対象のCSSやSCSS）
source: ../_scss

# The directory that hologram will build to（書き出し先）
destination: ../styleguide

# The assets needed to build the docs (includes header.html,
# footer.html, etc)
# You may put doc related assets here too: images, css, etc.
documentation_assets: ./doc_assets

# The folder that contains templates for rendering code examples.
# If you want to change the way code examples appear in the styleguide,
# modify the files in this folder
code_example_templates: ./code_example_templates

# The folder that contains custom code example renderers.
# If you want to create additional renderers that are not provided
# by Hologram (i.e. coffeescript renderer, jade renderer, etc)
# place them in this folder
code_example_renderers: ./code_example_renderers

# Any other asset folders that need to be copied to the destination
# folder. Typically this will include the css that you are trying to
# document. May also include additional folders as needed.
dependencies:
  - ../assets/css

# Mark which category should be the index page
# Alternatively, you may have an index.md in the documentation assets
# folder instead of specifying this config.
index: index

# To additionally output navigation for top level sections, set the value to
# 'section'. To output navigation for sub-sections,
# set the value to `all`
nav_level: all

# Hologram displays warnings when there are issues with your docs
# (e.g. if a component's parent is not found, if the _header.html and/or
#  _footer.html files aren't found)
# If you want Hologram to exit on these warnings, set the value to 'true'
# (Default value is 'false')
exit_on_warnings: false

あとはhologramの指定通りにCSSにスタイルガイドを書いていきます。 テンプレートはerbを使ったカスタマイズが可能です。ただし、テンプレートでは調整できない要素もあるため調整できる範囲に限界がありました。たとえば自動的に書き出されるh1要素や、ループするブロックの前後をタグで囲むような指定ができません。今後のアップデートで改善されると良いですね。

シリーズ

1. Gruntでhologramを使う