Comment Syntax

In aigis, Documenting component's configuration and component's documentation in comment block (/* ~ */). The block is surrounded by --- is configuration (YAML) and after YAML block is a documentation (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>
```

The component's style guide wil be generated from this configuration block and documentation block.

Configuration block

The block is surrounded by --- is configuration (YAML). Documenting the configuration with YAML forms.

To be more precise, --- needs to contain at the next line of starting line of the comment block (/*).

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

Specifying config keys of components (default is category and tag) in output_collection: which is in the configuration file ( aigis_config.yml) , you can generate a components style guide grouped by the specified configuration keys.

category and tag are grouped and output by default.

Documentation block

You can use Markdown (GitHub Flavored Markdown) in documentation block of the component

Enabled syntax highlight if you specified special keyword into code block (′′′). Please see Documentation/Syntax Highlight for more details.

Aigis compiles with chjj/marked and original custom renderer named aigis-marked for syntax highlighting

Customize Code Example Renderers

Aigis generates previewed components and appends it to the style guide, using a code block (′′′) which has a language identifier.

Aigis can compile the components with a template engine, using the key / values in the configuration block.

To enable this, set compile: true in configuration block and specify the syntax of the template engine as a language identifier in the code fence.

You can write the component include the keys in the template syntax which you specify. Aigis compiles the components using the values of the keys.

If you want to enable or disable previewed components, set transform: value in configuration block. In the case of enabling only ejs, set transform: value to ejs only as follows.
transform:
  - ejs

Describe configuration to generate from sample code block by using EJS. You can set compile: value each component. By default is 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>
```

The previewed component which was generated from the above configuration and sample code block will be prepend the sample code block.

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

Jade and Handlebars also can generate compiled previewed component.

Configs

Aigis control a lot of action with a configuration file (aigis_config.yml). All path names are interpreted relative from a configuration file (aigis_config.yml) directory.

source: (`required`)

Type	Default
String or Array	undefined

Specify relative path to a source file (or directory) which is a source for generating style guide. You can specify single specified value or arrayed value.

Example

In case of setting specific file and directory name to source value, see below:
source:
  - ./css/style.css
  - ./scss

source_type: (optional)

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

In case of setting directory name to source value, Aigis will aim at source file which has an extension in source_type. By default, there are four type of extensions, .css, .sass and .scss, and .styl.

Example

If you want to filter the type of source, set source_type value you want as follows.
source_type:
  - .css
  - .less
Generate style guide with Markdown

Aigis can generate style guide from every text file which has CSS comment block (/* ~ */) and configuration block which is surrounded by --- For example, Aigis generates from Markdown file when you set source_type to .md
source_type: .md

dest: (optional)

Type	Default
String	'./style guide'

Specify destination directory. If you didn't specify it, Aigis will make a destination directory named style guide at the configuration file (aigis_config.yml) directory.

Example

dest: ./path/to/destination

dependencies: (optional)

Type	Default
String or Array	undefined

Specify dependent file and directory for the style guide. The specified file and directory is copied to the destination directory.

Example

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

template_dir: (optional)

Type	Default
String	'./template'

Specify directory of template for generating style guide. This directory needs to contain index.ejs and layout.ejs.

If you specified jade to template_engine, the directory needs to contain index.jade and layout.jade.

If you specified hbs to template_engine, the directory needs to contain index.hbs and layout.hbs.

Example
template_dir: './path/to/template_dir

component_dir: (optional)

Type	Default
String	'./html'

Specify directory of imported html file. This option value is used for resolving a path of imported file when you want to append external file using special phrase (!![](./path/to/file.html)).

template_engine: (optional)

Type	Default
String	'ejs'

Specify template engine for generating style guide. Three type of template engines can be used in aigis as follows.

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

This directory needs to contain a index.xxx (e.g. index.jade) which has an extension for the template engine you choose.

Example

If you want to use Jade, see below:
template_engine: jade

log: (optional)

Type	Default
Boolean	false

List of generated files will be displayed to the console when this log is true.

color_palette: (optional)

Type	Default
Boolean	true

Aigis generates a color palette page named color.html which has all the color that are used in your files.

Sample: color.html

If you don't need the color palette, specify false to this option and then Aigis don't generate the color palette page.

preview_class: (optional)

Type	Default
String	'aigis-preview'

Specify class name of the preview area which contains previewed component when Aigis generated a previewed component from the code block. So, This option helps to operate your component with JavaScript or add a CSS which is unaffected by CSS of style guide

Appending previewed component

For example, you wrote a code block as follows.
```html
<button>hoge</button>
```
Aigis appends the following HTML to your style guide.
<div class="aigis-preview">
  <button>hoge</button>
</div>

output_collection: (optional)

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

Specify outputted page group. If you want to output page group besides category and tag, set group name to output_collection.

For example, In the case of your components require versioning, you added version to your components configuration block as follows.

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

And then you set version to output_collection. Finally, Aigis will generate a page for the components which is grouped by same version value.

output_collection:
  - category
  - version

In the case of above specified, two type of pages (category and version) will be outputted.

transform: (optional)

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

In the case of code block has a special extension, Aigis will generate an actual HTML from the code block. It can help you to show markup example and previewed component.

html jade ejs hbs will be enabled by default.

If you don't want to generate previewed component from the code block, specify transform value which you want.

transform:
  - html
  - hbs

Compile code block with template engine

If you specify compile: true in configuration block of your component, The code block which is specify ejs or jade or hbs will be compiled by using configuration value of the configuration block.
---
name: btn
category: btn
compile: true
data:
  value1: hoge
---
```ejs  
<h2><%- name %></h2>
<button><%- data.value1 %></button>
```
In the above case, Aigis will append HTML like the following by using configuration values.
<div class="aigis-preview">
  <h2>btn</h2>
  <button>hoge</button>
</div>

highlight: (optional)

Type	Default
Boolean	true

Specify enabling or disabling syntax highlighting for the code block. If you want another syntax highlighting library, specify highlight: false and then Aigis will disable the syntax highlighting.

timestamp_format: (optional)

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

When aigis generate style guide, Aigis will path through special variable named timestamp to your template. It helps to mention about publish date of your style guide.

Please refer format of Moment.js about The format of timestamp_format value.

template_global_data: (optional) `Only Handlebars`

Type	Default
Boolean	true

⚠ This feature is only Handlebars template.

When you specify 'false', enabling handlebars include to pass contextual params.

Example

aigis_config.yml

template_global_data: false
transform:
  - html
  - hbs

your css

---
name: Button
compile: true
---
Button styles.
* Base button style.
* Use `a` or `button` tag.
```hbs
{{include './button.html' label='Buy'}}
```

button.html

<button>{{label}}</button>

Output html for style guide is below:

<div class="aigis-preview">
  <button>Buy</button>
</div>

helper_options: (optional)

renderTemplateJSON: (optional) `Only Handlebars`

Type	Default
Boolean	true

⚠ This feature is only Handlebars template.

When you specify false, Get a JSON object from css comment and build the menu according to our needs.

Example

aigis_config.yml
template_engine: hbs
template_dir: ./template-json_hbs
helper_options:
  renderTemplateJSON: true
You can customize side menu you want :) Please refer /examples/template-json_hbs/sidemenu.hbs

Syntax Highlight

Aigis using Prism for highlighting. So you can download color theme from prismjs.com/download.

Basic Usage

Write codeblock with keyword like below (use html):

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

See the following list: Prism#language-list, you can highlight from listed languages.

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

You are free to make your style guide look however you would like. If you don't feel like going through this process yourself, you can take a look at the templates in our examples and this document's assets, and use the assets defined there instead.

Aigis require HTML templates. You can choose template engine from the following list.

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

You have to create index.xxx. (xxx is ejs or jade or hbs)

Index Template

Aigis needs index.xxx (e.g. index.jade) for generating a style guide.

Naming for template file of index page

If you specified template_engine: ejs, aigis will need index.ejs.

If you specified template_engine: jade, aigis will need index.jade.

If you specified template_engine: hbs, aigis will need index.hbs.

Please refer Documentation/Configs about more details for template_engine option.

Sample Template

This is EJS sample template. Aigis pass referenced values to template when aigis generated style guide.

<!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>

Pass values

When style guide was generated, aigis will pass the following values.

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

components

component value is Array which contains Object. The Object has HTML of the component.

For example, you wrote the following component in your CSS.

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

## component

this is component!

components[0] contains the following Object.

{
  md: '## component\n\nthis is component!', // Document for this component
  html: '<h2>component</h2><p>this is component</p>', // Parsed html of document
  config: { // Configurations for this component
    name: 'component name',
    category: ['mod', 'btn'] 
  },
  sourcePath: '/css/style.css' // File path for this document
}

html

html value contains HTML result of the parsed Markdown.

In index.ejs, you can write a template for rendering a page of index and component on the same page as follows.

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

root

root value contains a relative path is the dest directory in your configuration file from generated page This value is used to write a relative path which is interpreted a css file in <head>. If you want to use an absolute path, you don't need to use this value.

Example

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

config

config value contains an Object which has a detail of a configuration file (aigis_config.yml) For example, you can refer config.name in your template file if you want to use name in your configuration file.

Example

config:

name: styleguide!

template:

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

output:

<header>
  styleguide!
</header>

timestamp

timestamp value contains a time from the execution end time of aigis run. The format of this value can be specified timestamp_format in configuration file. Please refer Moment.js format for the format of timestamp_format

Example

config:

timestamp_format: YYYY/MM/DD HH:mm

template:

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

output:

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

helper

helper value has a lot of template helper for a complicated process in your template.

helper.createCollectionTree(collection_name)

Aigis outputs grouped components by output_collection value in configuration file. By default, Specify category and tag. コレクションは次のように/を使うことで階層表現をすることができます。

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

In the above case, This component belongs child category in the parent category. スタイルガイドの出力はこの階層情報を持ちながら出力されます。こういった階層をサイドメニューなどとして表現するのはとても面倒ですので、用意されていたヘルパーを使って簡単に行えるようにしてあります。

(The sidebar for this document was outputted by this helper.)

Example

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

Comment Syntax

Configuration block

Documentation block

Customize Code Example Renderers

Configs

source: (required)

Example

source_type: (optional)

Example

Generate style guide with 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)

Appending previewed component

output_collection: (optional)

transform: (optional)

Compile code block with template engine

highlight: (optional)

timestamp_format: (optional)

template_global_data: (optional) Only Handlebars

Example

helper_options: (optional)

renderTemplateJSON: (optional) Only Handlebars

Example

Syntax Highlight

Basic Usage

Example

JSX

Keyword: jsx

EJS

Keyword: ejs

Jade

Keyword: jade

Stylus

Keyword: stylus

Templates

Index Template

Naming for template file of index page

Sample Template

Pass values

components

html

root

Example

config

Example

timestamp

Example

helper

helper.createCollectionTree(collection_name)

Example

source: (`required`)

template_global_data: (optional) `Only Handlebars`

renderTemplateJSON: (optional) `Only Handlebars`

Keyword: `jsx`

Keyword: `ejs`

Keyword: `jade`

Keyword: `stylus`