Hologram とは
Hologram は Ruby 環境で動くスタイルガイドジェネレータです。
.css
、.scss
、.sass
、.less
、.styl
などの多様な形式のファイルに書かれたコメントから、自動でスタイルガイドを作ってくれます。
スタイルガイドは、静的な HTML ファイルとして出力され、独自のテンプレートを使ってスタイルガイドをカスタマイズすることもできます。
作業環境
Hologram のインストール
プロジェクトの Gemfile
に gem "hologram"
を追記します。
source "https://rubygems.org" gem "sass" gem "hologram"
追記したら bundle install
しましょう。
$ bundle install
インストールが完了したので、バージョンを確認してみましょう。
$ hologram -v hologram 1.4.0
Hologram の始め方
hologram init
コマンドで hologram の設定ファイルなどが作成されるので、hologram init
を実行してみます。
$ 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
色々とファイルが作成されましたが、hologram_config.yml
の中身を見てみましょう。
- hologram_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 source: ./sass # The directory that hologram will build to destination: ./docs # 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: - ./build # 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: basics # 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
source
.css
、.scss
、.sass
、.less
、.styl
などのスタイルガイドを作成する元になるファイルが置かれているディレクトリを指定します。destination
作成されたスタイルガイド(HTML ファイル)を出力するディレクトリを指定します。documentation_assets
出力されるスタイルガイドのテンプレートを置くディレクトリを指定します。ここで指定したディレクトに置かれた_header.html
と_footer.html
を使用して HTML ファイルが作成されるので、独自のテンプレートを作成したい場合は、_header.html
と_footer.html
を編集するようなかたちになります。code_example_templates
CSS などでスタイルガイド用にコードを記述する時にフォーマットを指定できるのですが、例えばmarkup_example
と指定した場合はここで指定したディレクトリのmarkup_example_template.html.erb
を元にスタイルガイドを出力します。
指定したファーマットのファイルが存在しない場合はデフォルトのテンプレートが使用されます。code_example_renderers
coffee_example
などcode_example_templates
で指定できるフォーマット以外のフォーマットを使用したい場合は、ここで指定したディレクトリにcoffee_example_template.html.erb
などというかたちでファイルを作成します。dependencies
ここで指定したディレクトリのファイルはスタイルガイドを作成する際にdocumentation_assets
で指定したディレクトリにコピーされます。index
スタイルガイドの TOP に表示するカテゴリーを指定することができます。nav_level
section
またはall
を指定することでナビゲーションのレベルを変更することができます。all
を指定すると sub-section まで表示することができます。exit_on_warnings
documentation_assets で指定したディレクトリに_header.html
がない時など、エラーが発生して Hologram が終了する時に Warning を表示したい場合は true を指定します。
Hologram のサンプルを動かしてみる
Hologram には公式のサンプルがあるので、今回はそちらを動かしてみます。
まずは先ほどの hologram init
コマンドで自動生成されたファイルを削除します。
$ rm -rf ./*
公式のサンプルを git clone します。
$ git clone git@github.com:trulia/hologram-example.git .
ビルドします。
$ hologram config.yml Adding renderer for haml examples Adding renderer for html examples Adding renderer for js examples Adding renderer for jsx examples Adding renderer for react examples Adding renderer for slim examples Build completed. (-:
これで docs
ディレクトリに HTML 形式でスタイルガイドが出力されたのでブラウザから確認してみます。
スタイルガイドの TOP を変更する
Hologram では source
で指定したディレクトリ(.css
や .scss
ファイルなどが置いてあるディレクトリ)直下に index.md
を置くと、それをスタイルガイドの TOP として表示するようです。
index.md
を削除して、Base CSS カテゴリーを TOP に設定してみましょう。
まずは index.md
と先ほど作成した docs
ディレクトリを削除します。
$ rm -rf components/index.md docs/
次に config.yml
に追記して、『Base CSS』カテゴリーを TOP にするよう宣言します。
- config.yml
...(略) index: base_css
再度、ビルドします。
$ hologram config.yml Adding renderer for haml examples Adding renderer for html examples Adding renderer for js examples Adding renderer for jsx examples Adding renderer for react examples Adding renderer for slim examples Build completed. (-:
ブラウザから確認してみます。
TOP にアクセスすると『Base CSS』カテゴリーがきちんと表示されました。
まとめ
Hologram はテンプレートを編集することによってスタイルガイドを自由にカスタマイズすることが可能です。
Hologram は .css
、.scss
ファイル内のコメントから自動で HTML を出力するので、wiki でよく見られる更新が滞りがちになるといったことも回避できるのではないかと思います。
Web制作者のためのSassの教科書 改訂2版 Webデザインの現場で必須のCSSプリプロセッサ
- 作者: 平澤隆,森田壮
- 出版社/メーカー: インプレス
- 発売日: 2017/09/15
- メディア: 単行本(ソフトカバー)
- この商品を含むブログを見る