ペパボテックカンファレンスで知った Hologram をさっそく試してみた.Hologram を一言で表現すると「CSS のスタイルガイドを自動生成するツール」のこと.Ruby で書かれてるので,困ったら直せそうだし良さそう.
Hologram 以外にも
結構イロイロある.最近よく使われてるのはどれなんだろう.
背景
サービスを育てていくと CSS が肥大化してカオスになるっていうのはよくある話で,UI 改善などで既に使わなくなったスタイルも CSS には残ったままっていうのも多いと思う.常に影響範囲を洗い出しながら精査をすれば良いんだけど,そこまでの時間はないし,無理に消して影響が出るなら残しておこうという判断になったりもする.ペパボテックカンファレンスで「2万行になった CSS」の話があって,単純にデカイ!と思った.
あとスタイルを本来意図した使い方ではなく,求めているデザインになるから流用してしまうこともあって,そうすると「この機能は無くなったから消そう」ってすると「なぜ別の機能の要素にも影響が出るの!」みたいになる.あるある.
サービスのコンセプトに特化する
全ての CSS にドキュメントを書く必要はないと思っていて,サービスのコンセプトに沿った重要な要素だったり,ユーザーのシナリオによって標準化されている要素に特化してドキュメントを書くだけで十分だと思う.単純な例で言うと「警告は黄」で「エラーは赤」など.そこで Hologram が有用だと感じた.
Hello Hologram
試してみた.コードは Playground に置いておいた.
バージョン
最新の 1.4.0 にした.ただ最近はリリースが行われて無くて master にマージされたまま止まってるものもある.
➜ gem install hologram ➜ hologram -v hologram 1.4.0
初期化
➜ 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
文字化け対策
自動生成した HTML が文字化けしてしまうため doc_assets/_header.html
に mata を追加する.ただ既に master にはマージされているので,リリースしてくれれば良いのになぁ,なんて思ってしまう.あと必要に応じて title
や h1
の文言も変更しておく.
<meta charset="UTF-8">
コードを CSS にする
デフォルトだと Sass から自動生成するようになっているため hologram_config.yml
の source
を更新する.
-source: ./sass +source: ./css
CSS を追加する
ここで CSS を追加する.既に稼働しているアプリケーションに適用する場合は不要.今回はカレントディレクトリに ./css
を作ってそこに CSS を配置するので,以下のサンプルを書いてみた.
$ mkdir css $ touch css/button.css
ドキュメントは markdown で書く.GitHub のサンプル参照で!
(markdown の中に markdown をプレーンテキストとして書く方法がわからなくて…)
実行する
自動的に docs/base_css.html
が生成される.サンプルの例が良くないかもしれないけど,こういう形でスタイルガイドが標準化されていたら良いね!
➜ hologram
スタイルガイドをカスタマイズする
デフォルトのままだとあまりにシンプルなので,スタイルガイド用の CSS を書いて,以下のファイルをカスタマイズすることができる.
- doc_assets/_header.html
- doc_assets/_footer.html
以下のサンプルは凄く良いなと思う.
今後
正直 Hologram の README を見てもよくわからなくて,ちゃんと生成できるまで試行錯誤してしまった.Hologram には他にも機能があるので,試してみようと思う.あと最近 Middleman を使ってるので,Middleman + Hologram も良さそう.