styleguideジェネレータ「aigis」を使ってみた


スタイルガイドジェネレータ「aigis」というものがあるらしく、ちょっと触って見るついでにメモを残しておきます。

exampleを触ってだいたいの感触を掴むというのがこのエントリの趣旨です。

aigisとは

株式会社ピクセルグリッド謹製のスタイルガイドジェネレータです。

以下、日本語ドキュメントより引用。

aigisでは、メンテナブルなスタイルガイドを作成することができます。 aigisを使えば以下の様なことが可能です。

  • テキストファイルであれば、.scss .styls .mdなど、どのような形式からでもスタイルガイドを作成できます。
  • Markdownを使用してドキュメントを記述することができます。
  • スタイルガイドのテーマをカスタマイズすることができます。またテーマでは、JadeやHandlebarsといったテンプレートエンジンを利用できます。

なお、このエントリは割と 黒い画面こわい人向け の記事です。

黒い画面怖くない人は、適宜読み飛ばしてください! (とか言っておきながら、npmコマンドとgitコマンドが動く環境になっていることが前提です!)

作業用フォルダをつくる

そういえば、いつも作業するときホームディレクトリに「Works」とか「Practice」とか作ってその中でやってるんですけど、なんかディレクトリ作るのに参考になるサイトないですかね〜。

とりあえずホームディレクトリに練習用フォルダを作っちゃいましょう。

cd ~でホームディレクトリに戻れます。

ちなみに、ホームディレクトリとはMacintosh HD > ユーザ > ***(あなたのユーザ名) ←ココ

$ cd ~            //ホームディレクトリへ移動
$ mkdir practice  //practiceというフォルダを作る
$ cd ./practice   //practiceへ移動

($マークよりも右側を記述してくださいね)

aigisを落としてくる

$ 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に関連するファイルをインストールします。

$ cd ./aigis/examples                //サンプルフォルダへ移動
$ npm install --save-dev node-aigis  //aigisをインストール
$ ./node_modules/.bin/aigis -v       //aigisのバージョンチェック
1.1.5                                //バージョン

$ npm install --save-dev node-aigisが動かねーよっていう方は多分npmだのnode.jsだのが入っていないので頑張っていれてください。

記事書いてる時点では1.1.5でしたがまあこの辺の数字は随時かわるかもしれません。

aigisのテンプレートを生成

$ ./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を起動

$ ./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.cssfooter.css・・・などのように。

ちなみに、今回はexamples/styleguideの中にファイルが吐き出されましたが、フォルダ名なんかはaigis_config.yml内のここで変えられますよ。

# The directory that aigis will build to
dest: ./styleguide

このdest:以降を任意のパスに書き換えることで好きな階層の好きなフォルダ内に吐き出させることができます。

また、更新があった場合は随時 ./node_modules/.bin/aigis run -c ./aigis_config.yml を叩いて生成しなおしてください。

まとめ

さて、これで、aigisを使って自由にメンテナブルなstyleguideを作ることができますね!

スニペット管理にもなりますし、これでスタイル管理することで迷子にならないサイト制作をしていきましょう!

気が向いたら、gulpにaigisを組み込んで、変化があったら自動で生成されるようにしたりする方法も書きたいなと思います!

またこの記事は何か気づきがありしだい追記していく予定なのでどうぞよろしくおねがいします!