スタイルガイドジェネレータ「aigis」というものがあるらしく、ちょっと触って見るついでにメモを残しておきます。
exampleを触ってだいたいの感触を掴むというのがこのエントリの趣旨です。
aigisとは
日本語ドキュメントより引用。
どうやらあのpixelgridによって生み出されたようですね。
aigisでは、メンテナブルなスタイルガイドを作成することができます。 aigisを使えば以下の様なことが可能です。
- テキストファイルであれば、.scss .styls .mdなど、どのような形式からでもスタイルガイドを作成できます。
- Markdownを使用してドキュメントを記述することができます。
- スタイルガイドのテーマをカスタマイズすることができます。またテーマでは、JadeやHandlebarsといったテンプレートエンジンを利用できます。
なお、このエントリは割と黒い画面こわい人向けの記事です。
黒い画面怖くない人は、適宜読み飛ばしてください！
(とか言っておきながら、npmコマンドとgitコマンドが動く環境になっていることが前提です！)
作業用フォルダをつくる
そういえば、いつも作業するときホームディレクトリに「Works」とか「Practice」とか作ってその中でやってるんですけど、なんかディレクトリ作るのに参考になるサイトないですかね〜。
とりあえずホームディレクトリに練習用フォルダを作っちゃいましょう。
cd ~でホームディレクトリに戻れます。
ちなみに、ホームディレクトリとはMacintosh HD > ユーザ > ***(あなたのユーザ名) ←ココ
nayucolony:~ yuki$ cd ~ //ホームディレクトリへ移動
nayucolony:~ yuki$ mkdir practice //practiceというフォルダを作る
nayucolony:~ yuki$ cd ./practice //practiceへ移動
（あ、$マークよりも右側を記述してくださいね。左側は人によって違いますよ。）
aigisを落としてくる
nayucolony:practice yuki$ git clone https://github.com/pxgrid/aigis.git
これは、今いるディレクトリにaigisの中身をダウンロードしてくるコマンド。
gitコマンドねーよ！みたいなことを言われた人はがんばってgitをインストールしてください。
Cloning into 'aigis'...
remote: Counting objects: 4360, done.
remote: Total 4360 (delta 0), reused 0 (delta 0), pack-reused 4360
Receiving objects: 100% (4360/4360), 933.49 KiB | 246.00 KiB/s, done.
Resolving deltas: 100% (2229/2229), done.
Checking connectivity... done.
まあなんかこんな感じになったらokです。
aigisをインストールする
落としてきたのは、aigisに必要なファイルのダウンロード指示書だと思ってください。
（ほら、いろんなプログラムを組み合わせて動いてるから、全部詰め込むと重いんだよ）
ここで、追加でaigisに関連するファイルをインストールします。
nayucolony:practice yuki$ cd ./aigis/examples //サンプルフォルダへ移動
nayucolony:examples yuki$ npm install --save-dev node-aigis //aigisをインストール
nayucolony:examples yuki$ ./node_modules/.bin/aigis -v //aigisのバージョンチェック
1.1.5 //インストール成功していればバージョン情報が出る
nayucolony:examples yuki$ npm install --save-dev node-aigisが動かねーよっていう方は多分npmだのnode.jsだのが入っていないので頑張っていれてください。
記事書いてる時点では1.1.5でしたがまあこの辺の数字は随時かわるかもしれません。
aigisのテンプレートを生成
nayucolony:examples yuki$ ./node_modules/.bin/aigis init
こうなったらokです
Created the following files and directories:
Cowardly refusing to overwrite existing: aigis_config.yml
aigis_assets
aigis_assets/css/highlight/okadia.css
aigis_assets/css/theme.css
template_ejs
template_ejs/components.ejs
template_ejs/index.ejs
template_ejs/sidemenu.ejs
aigisを起動
nayucolony:examples yuki$ ./node_modules/.bin/aigis run -c ./aigis_config.yml
こんな感じになります。
意味的には、今いるファイルにあるaigis_config.ymlをaigisに読み込ませるような感じです。
[Info] Config File: /Users/yuki/practice/aigis/examples/aigis_config.yml
[Info] Start: Generate Styleguide
[Info] Output: /Users/yuki/practice/aigis/examples/styleguide
[Info] Finish: Generate Styleguide
はい、これでok。
スタイルガイドを見てみる
では、Finderでホームディレクトリ内に作ったpracticeフォルダの中のaigisフォルダを開いてみましょう。
styleguideといフォルダがあると思いますが、これが先ほどaigisを起動させることで生成されたスタイルガイドです。
index.htmlを開くと、スタイルガイドが生成されていることがわかると思います。
index.html
基本的には、全てaigis_config.ymlがどのファイルをどうするのかという管理をしています。
# Index page created from markdown file
index: ./index.md
index.htmlは、aigis_config.ymlと同階層にあるindex.mdから生成しますよ、とのこと。
その他ページ
サイドバーのbaseをクリックするとbase部分に関する記述が出てきます。
（なんか最後にスラッシュついてないのでちょっとおかしな遷移しますが）
他ページも同様です。
このあたりもaigis_config.ymlに書いています
#The directory containing the source files to parse recursively
source:
- ./css
- ./demo.md
つまり、今いるexamplesフォルダ内のcssフォルダ内のテキストファイル(今回だとstyle.css)、もしくはdemo.mdから生成しますよということですね。
他にも対象ファイルを増やしたければここに追記していきましょう。
ちなみに、最初の「aigisとは？」の部分に書いたように、拡張子はかなりいろんな部分をサポートしているみたいです。
ただし、aigis_config.ymlの以下の部分で「どの拡張子のファイルを対象にするのか」は書いておくこと。
# The types that aigis will scan to document comment
source_type:
- .css
- .sass
- .scss
- .styl
# If you want to generate documents from markdown
# source_type: .md
また、.mdがリストにないのにdemo.mdが対象になっているのは、ファイル名と拡張子を指定しているからです。
./cssのように、フォルダを指定した場合はフォルダ内にある上記リストの拡張子を持つファイルのみが生成対象になります。
ファイル名と拡張子まで指定しなくても.mdを生成対象にしたい場合、一番下の行の#を消してコメントアウトを解除するか、リストに.mdを追加してしまいましょう。
(//で始まる部分は説明用に私が記述したものです。)
//以下、メタ情報。カテゴリやタグの情報を書くとサイドバーとメインに自動反映してくれる。
/*
---
name: Button
category:
- mod/btn
- base
- mod
tag:
- latest
- base
compile: false
---
//以下、メインセクション記述。markdownで書くこと。
Button styles.
* Base button style.
* Use `a` or `button` tag.
//以下シンタックスエリア。ファイル形式を書くと自動でシンタックスハイライトがかかる。
```html
<a class="ag-btn">Button</a>
<button class="ag-btn ag-btn--primary">Button</button>
```
```ejs
<a class="ag-btn"><%- name %></a>
<button class="ag-btn ag-btn--primary"><%- name %></button>
```
```jade
a.ag-btn
!= name
button.ag-btn.ag-btn--primary
!= name
```
```hbs
{{include './button.html'}}
<hr>
<a class="ag-btn">{{name}}</a>
<button class="ag-btn ag-btn--primary">{{name}}</button>
```
*/
//以下、コンポーネントのCSS
.ag-btn {
-webkit-appearance: none;
display: inline-block;
border: none;
background-color: #3DB680;
color: #fff;
padding: 10px 20px;
text-align: center;
line-height: 40px;
min-width: 200px;
font-size: 20px;
box-sizing: border-box;
}
.ag-btn--primary {
color: black;
background-color: #FFEA3A;
}
:の後に半角スペースが空いてないとエラー吐いたりするなど割とシビアなので注意。
あんまり縦長になるとつらそうなので、1スタイル1ファイルとかでいいかもしれませんね。
今回だと、header.css、footer.css・・・などのように。
ちなみに、今回はexamples/styleguideの中にファイルが吐き出されましたが、フォルダ名なんかはaigis_config.yml内のここで変えられますよ。
# The directory that aigis will build to
dest: ./styleguide
このdest:以降を任意のパスに書き換えることで好きな階層の好きなフォルダ内に吐き出させることができます。
また、更新があった場合は随時
nayucolony:examples yuki$ ./node_modules/.bin/aigis run -c ./aigis_config.yml
を叩いて生成しなおしてください。
まとめ
さて、これで、aigisを使って自由にメンテナブルなstyleguideを作ることができますね！
スニペット管理にもなりますし、これでスタイル管理することで迷子にならないサイト制作をしていきましょう！
気が向いたら、gulpにaigisを組み込んで、変化があったら自動で生成されるようにしたりする方法も書きたいなと思います！
またこの記事は何か気づきがありしだい追記していく予定なのでどうぞよろしくおねがいします！