Comment Syntax

aigisではコメントブロック(/* ~ */)にコンポーネントのコンフィグと、コンポーネントのドキュメントを合わせて記述します。次のコードの---で囲まれているブロックがコンフィグ(YAML)、それ以下がドキュメント(Markdown)になります。

---
name: component name
tag:
  - base
  - latest
category:
  - component
  - component/button
---

## This is a component document

* Base button component.
* Use `a` or `button` tag.

Here's an example code.

```html
<a class="btn">Button</a>
```

このコンフィグとドキュメントをセットに、コンポーネントのスタイルガイドを生成します。

コンフィグブロック

---で囲まれた部分がコンポーネントのコンフィグです。コンフィグはYAML形式で記述します。

より正確に言うとコメントブロックの開始行(/*)の次の行に---がある必要があります。

---
name: component name
tag:
  - base
  - latest
category:
  - component
  - component/button
---

コンフィグファイル(aigis_config.yml)のoutput_collection:に、コンポーネントのコンフィグの項目名(categoryやtag)を指定することで、その項目ごとにコンポーネントをグルーピングしてスタイルガイドを生成することができます。

デフォルトではcategoryとtagをグルーピングして出力します。

ドキュメントブロック

コンポーネントのドキュメントではMarkdown(GitHub flavored markdown)を使うことができます。

コードブロック(′′′)では特定のキーワードを指定することでシンタックスハイライトが有効になります。詳しくはDocumentation/Syntax Highlightを参照してください。

aigisではchjj/markedを使ってMarkdownをコンパイルします。また、Highlightなどの処理を行うために、aigis-markedというカスタムレンダラを使用しています。

コンフィグの値を使ってプレビューを生成する

aigisはコードブロック(′′′)に特定のキーワードをつけることでプレビューを生成し挿入します。EJSやJadeのようなテンプレートエンジンからプレビューを生成したい場合、コンフィグにcompile: trueを指定することでコンフィグに書かれた値をもとにプレビューを生成できます。

プレビュー挿入の有効/無効の切り替えはコンフィグファイルのtransform:で指定できます。ejsのときだけプレビューを有効にする場合には、次のようにtransform:にejsだけを指定します。
transform:
  - ejs

EJSのコードブロックからHTMLのプレビューを生成するには、次のようなコンフィグを記述します。compile:の項目はコンポーネントごとに切り替えることができます。(Defaultではfalse)

---
name: component name
tag:
  - base
  - latest
category:
  - component
  - component/button
data:
  value1: hoge
  value2: fuga
compile: true
---

```ejs  
<div>
  <h2><%- name %></h2>
  <p><%- data.value1 %></p>
  <p><%- data.value2 %></p>
</div>
```

上記のコンフィグとコードブロックから次のようなHTMLがコードブロックの手前に挿入されます。Jade、Handlebarsも同様にコンパイルしたプレビューを生成することができます。

<div>
  <h2>component name</h2>
  <p>hoge</p>
  <p>fuga</p>
</div>

Configs

aigisは動作の多くをコンフィグファイル（aigis_config.yml）で制御します。全てのパスはコンフィグファイル（aigis_config.yml）が置かれている場所から相対的に解決されます。

source: (`required`)

Type	Default
String or Array	undefined

スタイルガイドを生成するソースとなるファイル（またはディレクトリ）への相対的なパスを指定します。単一の指定と配列による複数指定のどちらも行えます。

Example

ソースとして特定のファイルとディレクトリを指定したい場合には次のように指定します。
source:
  - ./css/style.css
  - ./scss

source_type: (optional)

Type	Default
String or Array	['.css', '.sass', '.scss', '.styl']

sourceにディレクトリが指定された場合、aigisはsource_typeに記述されている拡張子のファイルをソースの対象にします。デフォルトで.css .sass .scss .stylの4種類を対象とします。

Example

ソースとするファイルのタイプを減らしたい場合、次のように対象とするタイプだけを指定します。
source_type:
  - .css
  - .less
Markdownからスタイルガイドを生成する

CSSのコメントブロック（/* ~ */）と---で囲まれた設定の記述があれば、どんなファイルからでもスタイルガイドが生成できます。例えば、次のように.mdを指定すればMarkdownファイルからスタイルガイドを生成できます。
source_type: .md

dest: (optional)

Type	Default
String	'./styleguide'

スタイルガイドを出力するフォルダを指定します。指定がない場合、aigis_config.ymlのあるフォルダにstyleguideフォルダを作成して出力されます。

Example

dest: ./path/to/destination

dependencies: (optional)

Type	Default
String or Array	undefined

スタイルガイドに必要なファイルやディレクトリを指定します。指定されたファイルやディレクトリはスタイルガイドの出力先にコピーされます。

Example

dependencies:
  - ./path/to/css
  - ./path/to/images
  - ./path/to/style.css

template_dir: (optional)

Type	Default
String	'./template'

スタイルガイドの生成に必要なテンプレートファイルが格納されているディレクトリを指定します。このディレクトリにはindex.ejsとlayout.ejsの2つが含まれている必要があります。

template_engineにjadeを指定している場合にはindex.jade layout.jadeを、hbsを指定している場合にはindex.hbs layout.hbsが必要になります。

Example
template_dir: './path/to/template_dir

component_dir: (optional)

Type	Default
String	'./html'

外部ファイルからHTMLをドキュメントコメント内に挿入したいときに使える!![](./path/to/file.html)という構文で、インポートするファイルのパスを解決するときに使われます。

template_engine: (optional)

Type	Default
String	'ejs'

スタイルガイドを生成する際に利用するテンプレートエンジンを指定します。aigisでは次の3つのテンプレートエンジンが利用できます。

EJS（ejs）
Jade（jade）
Handlebars（hbs）

このディレクトリには、利用するテンプレートごとに決められた拡張子でindex.xxxというファイルが格納されている必要があります。

Example

Jadeを利用したい場合
template_engine: jade

log: (optional)

Type	Default
Boolean	false

logがtrueの場合、スタイルガイド生成の際に出力されるファイルの一覧などをコンソールに出力します。

color_palette: (optional)

Type	Default
Boolean	true

aigisは、スタイルガイドのソースとなるファイルから全ての色を収集し、一覧できるようにcolor.htmlという特別なページを出力します。

サンプル: color.html

カラーパレットが必要ない場合、falseを指定することでカラーパレットの出力を止めることができます。

preview_class: (optional)

Type	Default
String	'aigis-preview'

aigisがコードブロック(```htmlなので始まるブロック)からHTMLのプレビューを生成する際に、プレビューの外側の要素につくCSSのクラス名を指定できます。コンポーネントがスタイルガイドの影響を受けないようにスタイルを付けたり、JavaScriptから操作したい場合などに役に立ちます。

プレビューの挿入

例えば、次のようなコードブロックを記述した場合
```html
<button>hoge</button>
```
次のようなHTMLが挿入されます。
<div class="aigis-preview">
  <button>hoge</button>
</div>

output_collection: (optional)

Type	Default
String or Array	['category', 'tag']

出力するページのグループを指定します。categoryやtag以外にグルーピングして出力したい項目がある場合はoutput_collectionに追加します。

例えばバージョニングを行っている場合には、コンポーネントの設定に次のようにversionを追加し、output_collectionにversionを追加することでversionの値が同じコンポーネントがグルーピングされて出力されます。

---
name: btn
category:
  - base
  - btn
version: 1
---

output_collection:
  - category
  - version

上記の指定の場合、categoryとversionでまとめた2種類のページが出力されます。

transform: (optional)

Type	Default
String or Array	['html', 'ejs', 'jade', 'hbs']

コードブロックに特定のタイプが指定されている場合、aigisはそのコードブロックを実際のHTMLとしてドキュメントに追加します。これによってマークアップの例を示すとともにプレビューの表示も手軽に行なえます。デフォルトではhtml jade ejs hbsのプレビューが有効になっています。

もしプレビューとして表示したくないタイプがある場合には、表示したいタイプだけをtransformに指定します。

transform:
  - html
  - hbs

テンプレートエンジンのコンパイル

ejs jade hbsのコードブロックは、コンポーネントの設定にcompile: trueを指定することで、コードブロックに設定の値を渡してコンパイルを行えます。
---
name: btn
category: btn
compile: true
data:
  value1: hoge
---
```ejs  
<h2><%- name %></h2>
<button><%- data.value1 %></button>
```
上記の場合、次のように値が反映された状態のHTMLが挿入されます。
<div class="aigis-preview">
  <h2>btn</h2>
  <button>hoge</button>
</div>

highlight: (optional)

Type	Default
Boolean	true

コードブロックのシンタックスハイライトを有効にするかを指定します。別のハイライトライブラリを使う場合ときなどはhighlight: falseとすることでaigisのハイライトをオフにできます。

timestamp_format: (optional)

Type	Default
String	'YYYY/MM/DD HH:mm'

スタイルガイドを生成する際、aigisはtimestampという特別な変数をテンプレートに渡します。ドキュメントの更新日を記述したい際などに役にたつかもしれません。

timestamp_formatに指定する形式はMoment.jsのformatを参照してください。

Syntax Highlight

aigisはシンタックスのハイライトにPrismを利用しています。シンタックスのカラーリングにはhttp://prismjs.com/download.htmlにあるテーマをダウンロードして利用できます。

使い方

ハイライトしたいコードブロックに次のようにキーワードを指定してください。

```html  
<div class="awesome-class" data-awesome-attribute>
  <p>The quick brown fox jumps over the lazy dog</p>
</div>  
```

ハイライトできる言語は次のリストに入っているものです。

Prism#language-list

Example

JSX

Keyword: `jsx`

Write codeblock with jsx keyword then you get highlighted codeblock:

var CommentBox = React.createClass({
  render: function() {
    return (
      <div className="commentBox">
        Hello, world! I am a CommentBox.
      </div>
    );
  }
});

EJS

Keyword: `ejs`

<div class="awesome-class" data-awesome-attribute>
  <p><%- text -></p>
</div>

Jade

Keyword: `jade`

.awesome-class(data-awesome-attribute)
  p The quick brown fox jumps over the lazy dog

Stylus

Keyword: `stylus`

border-radius()
  -webkit-border-radius: arguments
  -moz-border-radius: arguments
  border-radius: arguments

body
  font: 12px Helvetica, Arial, sans-serif

a.button
  border-radius: 5px

Templates

スタイルガイドの生成にはテンプレートが必要になります。aigisではテンプレートとして次の3種類のテンプレートエンジンから選択して利用することができます。

利用できるテンプレートエンジンと拡張子

EJS: .ejs
Jade: .jade
Handlebars: .hbs

選択するテンプレートエンジンごとに決められた拡張子でindex.xxxというファイルを作成してください。

GitHubのリポジトリにはテーマを含めたexamplesがありますので、参考にしてみてください。このドキュメント自体もaigisで生成されたものなので、合わせて参考にしてみてください。

aigis/examples

aigis/gh-pages/src

インデックステンプレート

スタイルガイドの生成にはテンプレートファイルとしてindex.xxxが必要になります。

インデックステンプレートのファイル名

template_engineにejsをしている場合にはindex.ejsが、jadeを指定している場合にはindex.jadeが、hbsを指定している場合にはindex.hbsが必要になります。テンプレートエンジンの指定についてはDocumentation/Configsを参照。

テンプレートのサンプル

EJSのテンプレートの例です。テンプレートで参照している値は、スタイルガイド生成用にaigisがコンパイルした時に渡す値です。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <link href="<%= root %>aigis_assets/css/doc.css" rel="stylesheet">
  </head>
  <body>
    <header>
      <%- config.name %>
    </header>
    <nav>
      <%- helper.renderCollectionTree('category') %>
    </nav>
    <main>
      <%- html %>
      <% if(components.length) { %>
        <% components.forEach((component) => { %>
          <%- component.config.name %>
          <%- component.html %>
        <% }) %>
      <% } %>
    </main>
    <footer>Last updated: <%- timestamp %></footer>
  </body>
</html>

テンプレートで使える値

aigisはコンパイル時につぎの値を元にテンプレートに渡しスタイルガイドを生成します。

Name	Type
components	Array
html	String
root	String
config	Object
timestamp	String
helper	Object

テンプレートでこの値を使ってスタイルガイドを構築します。

components

コンポーネントのHTMLなどが入ったオブジェクトの配列。

たとえば./css/style.cssに次のようなコンポーネントを記述した場合:

---
name: component name
category:
  - mod
  - btn
---

## component

this is component!

components[0]には次のようなコンポーネントが格納される:

{
  md: '## component\n\nthis is component!', // コンポーネントのドキュメント部分
  html: '<h2>component</h2><p>this is component</p>', // ドキュメント部分をパースしたHTML
  config: { // コンポーネントのコンフィグ部分
    name: 'component name',
    category: ['mod', 'btn'] 
  },
  sourcePath: '/css/style.css' // ドキュメントが記述されているファイルへのパス
}

html

インデックスページ用のMarkdownファイルをパースしたHTMLが格納されている。

index.ejsでは次のようにすることで、インデックスページとコンポーネントページを同一のテンプレートでレンダリングすることができます。

<main>
  <%- html %>
  <% if(components.length) { %>
  ...
  <% } %>
</main>

root

出力されるページから見た、コンフィグファイルのdestで指定されたフォルダへの相対パスが格納されています。<head>要素などにCSSファイルへの参照を相対パスで書く際に利用できます。ファイルの参照を絶対パスで行う場合には使う必要はないでしょう。

Example

<link href="<%= root %>aigis_assets/css/doc.css" rel="stylesheet">

config

コンフィグファイル(aigis_config.yml)の内容が格納されたオブジェクトです。例えばコンフィグファイルのnameという項目をテンプレートで使いたい場合、次のようにconfig.nameとすることで参照できます。

Example

config:

name: styleguide!

template:

<header>
  <%- config.name %>
</header>

output:

<header>
  styleguide!
</header>

timestamp

aigis runが実行された時間が格納されています。形式はコンフィグファイルのtimestamp_formatで指定できます。

timestamp_formatに指定する形式はMoment.jsのformatを参照してください。

Example

config:

timestamp_format: YYYY/MM/DD HH:mm

template:

<footer>
  <%- timestamp %>
</footer>

output:

<footer>
  2016/04/07 17:11
</footer>

helper

複雑な処理が必要な場面で役に立つテンプレートヘルパーの集まりです。

helper.createCollectionTree(collection_name)

aigisはコンフィグファイルのoutput_collectionにある値でコンポーネントをグルーピングして出力します。デフォルトではcategoryとtagが設定してあります。コレクションは次のように/を使うことで階層表現をすることができます。

---
name: component
category:
  - parent/child
---

このコンポーネントの場合、parentカテゴリの下のchildカテゴリに所属しています。スタイルガイドの出力はこの階層情報を持ちながら出力されます。こういった階層をサイドメニューなどとして表現するのはとても面倒ですので、用意されていたヘルパーを使って簡単に行えるようにしてあります。

(このドキュメントのサイドメニューもこのヘルパーを使って出力されたものです。)

Example

<nav>
  <%- helper.renderCollectionTree('category') %>
</nav>

Comment Syntax

コンフィグブロック

ドキュメントブロック

コンフィグの値を使ってプレビューを生成する

Configs

source: (required)

Example

source_type: (optional)

Example

Markdownからスタイルガイドを生成する

dest: (optional)

Example

dependencies: (optional)

Example

template_dir: (optional)

Example

component_dir: (optional)

template_engine: (optional)

Example

log: (optional)

color_palette: (optional)

preview_class: (optional)

プレビューの挿入

output_collection: (optional)

transform: (optional)

テンプレートエンジンのコンパイル

highlight: (optional)

timestamp_format: (optional)

Syntax Highlight

使い方

Example

JSX

Keyword: jsx

EJS

Keyword: ejs

Jade

Keyword: jade

Stylus

Keyword: stylus

Templates

利用できるテンプレートエンジンと拡張子

インデックステンプレート

インデックステンプレートのファイル名

テンプレートのサンプル

テンプレートで使える値

components

html

root

Example

config

Example

timestamp

Example

helper

helper.createCollectionTree(collection_name)

Example

source: (`required`)

Keyword: `jsx`

Keyword: `ejs`

Keyword: `jade`

Keyword: `stylus`