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>