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>