はじめてのaigis 第1回 aigisの基本
まずはaigisがどういったものか、その特徴と基本的な機能を解説します。Node.jsのみで構築できる環境、YAMLとMarkdownで簡単に記述できるスタイルガイド記述、スタイルガイドの分類を簡便に行えるカテゴリーなど多くの特徴があります。
はじめに
この記事では、スタイルガイドジェネレーターaigis（アイギス）の基本的な機能を、サンプルを交えながら紹介していきます。
「自作ツール作成から学ぶノウハウ - 第1回 aigisの作成と公開」*で筆者が作成したaigisというスタイルガイドジェネレータの技術的な背景や紹介しました。
本シリーズではaigisの特徴や使い方を解説していきます。
*注：v1.0.0のリリース
前述の記事のあと、aigisのバージョン1.0.0をリリースしました。利用しているライブラリなどが変更され、機能などにも変更があります。v0.2系を利用している方はこの記事と合わせて、後述するドキュメントにも目を通してみてください。
第1回の今回は、aigisがどういったものかを、サンプルを交えながら紹介していきます。第2回で実際にaigisを使うための環境構築や設定などを解説していきますので、今回はまずaigisの概要を掴んでください。
なお、紹介するサンプルは次のリポジトリからダウンロード、またはクローンできます。併せて参照してください。
はじめてのaigisサンプルリポジトリ
このシリーズは、次の環境にて動作を確認しています。環境や各ソフトウェアのバージョン違いにより、本シリーズで解説している内容がそのまま動作しない可能性がありますので、その点ご留意ください。
- OS X 10.11.4
- Node.js v4.4.4
- npm 3.8.9
aigisの特徴
aigisは次のような特徴を持っています。
- MarkdownとYAMLからスタイルガイドを生成する
- 階層構造を持ったカテゴリーごとのスタイルガイドが生成できる
- シンタックスハイライトを行う
aigisはCodeGridで過去に紹介したhologramに似た機能や特徴を持っていますが、hologramよりも柔軟に使えるような作りになっています。aigisの柔軟性を表す特徴として、次の2点が挙げられます。
- スタイルガイドを生成する元になるファイルのタイプを問わない
- 3種類のテンプレートエンジンから選んで利用できる
スタイルガイドを生成する書式に沿っていれば、どのような形式のファイルからでも（たとえばMarkdownファイルなどから）スタイルガイドが生成できます。テンプレートにはEJS、Jade、Handlebarsから1つを選んで使うことができるので、プロジェクトで使っているものに合わせたり、使い慣れているテンプレートエンジンを利用することができます。
それではこうした特徴を交えながら、aigisの基本的な使い方について解説します。実際の環境構築は次回行いますので、まずはaigisの概要を眺めてみてください。
MarkdownとYAMLからスタイルガイドを生成する
aigisはコメントブロックに書かれたYAML*とMarkdownをもとにスタイルガイドを生成します。
*注：YAMLとは？
YAML（ヤムル）とは、XMLやJSONと同様に階層的にデータを表現できる形式のひとつです。XMLやJSONよりもシンプルな書式が特徴です。
次のコードはCSSに書いたシンプルなコメントブロックの例です。---で囲まれたブロックがYAMLで書かれたコンポーネントの設定です。その下の部分はMarkdownを使って自由にドキュメントを記述できます。
style.css
/*
---
name: ボタン
category:
- component
- component/button
---
## 見出し
1. 番号付きリスト
1. 番号付きリスト
1. 番号付きリスト
## コードブロック
以下のコードブロックはシンタックスハイライトが効いた状態になります。
合わせてプレビュー用のHTMLが挿入されます。
```html
<a class="btn">Button</a>
<button class="btn">Button</button>
```
*/
.btn {
color: red;
}このコメントブロックから次のようなスタイルガイド用のHTMLが生成されます。
<h2>見出し</h2>
<ol>
<li>番号付きリスト</li>
<li>番号付きリスト</li>
<li>番号付きリスト</li>
</ol>
<h2>コードブロック</h2>
<p>以下のコードブロックはシンタックスハイライトが効いた状態になります。<br>
合わせてプレビュー用のHTMLが挿入されます。</p>
<div class="aigis-preview">
<a class="btn">Button</a> <button class="btn">Button</button>
</div>
<pre><code class="lang-html"><pre class="editor editor-colors"><div class="line"><span class="text html gohtml"><span class="meta tag inline any html"><span class="punctuation definition tag begin html"><span><</span></span><span class="entity name tag inline any html"><span>a</span></span><span> </span><span class="entity other attribute-name html"><span>class</span></span><span>=</span><span class="string quoted double html"><span class="punctuation definition string begin html"><span>"</span></span><span>btn</span><span class="punctuation definition string end html"><span>"</span></span></span><span class="punctuation definition tag end html"><span>></span></span></span><span>Button</span><span class="meta tag inline any html"><span class="punctuation definition tag begin html"><span></</span></span><span class="entity name tag inline any html"><span>a</span></span><span class="punctuation definition tag end html"><span>></span></span></span></span></div><div class="line"><span class="text html gohtml"><span class="meta tag inline any html"><span class="punctuation definition tag begin html"><span><</span></span><span class="entity name tag inline any html"><span>button</span></span><span> </span><span class="entity other attribute-name html"><span>class</span></span><span>=</span><span class="string quoted double html"><span class="punctuation definition string begin html"><span>"</span></span><span>btn</span><span class="punctuation definition string end html"><span>"</span></span></span><span class="punctuation definition tag end html"><span>></span></span></span><span>Button</span><span class="meta tag inline any html"><span class="punctuation definition tag begin html"><span></</span></span><span class="entity name tag inline any html"><span>button</span></span><span class="punctuation definition tag end html"><span>></span></span></span></span></div></pre>
</code></pre>このHTMLにスタイルを当ててブラウザで表示すると、次のようなスタイルガイドを出力できます。
階層構造を持ったカテゴリーの出力
先述した例の設定で次のような指定をしました。
---
name: ボタン
category:
- component
- component/button
---aigisはこの**categoryに同じ名前が指定されているコンポーネントをグルーピングして、ページの出力を行います**。この名前に/が含まれている場合、aigisはこれを階層構造として扱います。たとえばcomponent/buttonのように指定した場合、componentの下のbuttonページに出力されます。上記のようにcomponentとcomponent/buttonの2つを指定すると、次のようにcomponentとbuttonの両方のページに同じコンポーネントを出力することができます。
ページ出力の階層
styleguide/
┗ category/
┗ component/
┣ index.html // => ここに出力される
┗ button/
┗ index.html // => ここに出力されるこのコレクションの機能をうまく使うことで、コンポーネントの属性や関係性を持たせたスタイルガイドの生成が行えます。
テンプレートのヘルパー
aigisでは先述した階層構造を持ったカテゴリーのコレクションから、ツリーメニューを生成するためのヘルパーが用意されています。ヘルパーを使うことで、次のような見た目の階層メニューを簡単に作れます。
ヘルパーの使い方はとてもシンプルで、次のようにテンプレートの中でhelper.renderCollectionTreeを呼び出すだけです。このとき、引数としてツリーを生成したいコレクションの名前を指定します。
ツリーヘルパーの利用
<%- helper.renderCollectionTree('category') %>このヘルパーは次のようなHTMLを生成して出力します。
ツリーヘルパーの出力するHTML
<ul data-path-depth="0">
<li data-path-depth="0">
<a href="../category/component/index.html" data-tree-current>component</a>
<ul data-path-depth="1">
<li data-path-depth="1">
<a href="../category/component/button/index.html">button</a>
</li>
</ul>
</li>
<li data-path-depth="0">
<a>layout</a>
<ul data-path-depth="1">
<li data-path-depth="1">
<a href="../category/layout/footer/index.html">footer</a>
</li>
<li data-path-depth="1">
<a href="../category/layout/header/index.html">header</a>
</li>
</ul>
</li>
</ul>ツリーの要素にはdata-path-depthという属性に階層ごとの値が付与されます。また、出力されたページが対応するツリーの要素にはdata-tree-currentという属性が付与されます。この属性値を利用して、たとえば次のようなCSSでスタイルガイド生成を行うと、先述したようなサイドメニューを表現できます。
ツリーのスタイリング例
li[data-path-depth] a:before {
content: "└";
margin-right: 10px;
}
li[data-path-depth="1"] a:before
{
margin-left: 1em;
}
li[data-path-depth="2"] a:before {
margin-left: 2em;
}
[data-tree-current] {
background-color: #8C8C8C;
color: #fff;
}まとめ
aigisの基本的な機能と使い方を紹介しました。本記事を読んでみて、スタイルガイドが簡単に作れそうだなと思ってもらえたら嬉しいです。
hologramはRubyフレンドリーなスタイルガイドジェネレータですので、Ruby on Railsを利用するプロジェクトなどであれば採用に躊躇しないと思います。ですが、そうでないプロジェクトの場合には依存する環境が増えてしまうことになります。その点、aigisはNote.jsに依存するだけで、RubyにもPythonにも依存しません。プロジェクトの環境をNode.jsで完結させたい場合には、aigisの利用を候補に入れてみてください。
次回は、実際にaigisを使うための環境構築とあわせて、もう少し細かい機能の紹介と、カスタマイズの方法について解説します。