Fractal デザインスタイルガイド 導入

#Fractalとは
「styledocco」や「sc5-styleguide」などのスタイルガイドジェネレーターの仲間。
スタイルガイドジェネレーターといえば、ドキュメントを作成するためにCSS内にコメントで記述するものが多いですが、fractalはスタイルシート内ではなく、Handlerbarsファイルに記述するようになっています。（設定により`json` `yaml` `pug`などで記述することも可能です）
CSSファイルとは別ファイルで管理できるので、CSSファイルを綺麗に保つことができます。



公式ガイドも比較的わかりやすい記述になってますので、カスタマイズなどしないのであればすぐに利用できると思います。（[参考](http://fractal.clearleft.com/index.html)）

<img width="100" alt="fractal_logo.png" src="https://qiita-image-store.s3.amazonaws.com/0/239855/3d0f525c-d0b1-f2f9-ed00-513a9c5b3dd4.png">　

##画面の説明

各種デザインパーツをまとめていく `コンポーネント` と `ドキュメント` の２つに別れている。
コンポーネントは画面下に `HTML` `View` `Context` `Info` `Notes`のタブが表示される。
![fractal.jpg](https://qiita-image-store.s3.amazonaws.com/0/239855/375291e5-dcd0-b575-6ef1-9f62a17385a3.jpeg)

##準備

###フォルダを作成
```
% mkdir guide
```
ターミナルを立ち上げて、上記コマンドを入力

###npm initでプロジェクトを開始
```
% npm init
```
`cd guide`でguideフォルダ内に移動し、上記コマンドを入力しpackage.jsonを作成


###Fractalをインストール

```
% npm install --save @frctl/fractal
```
Fractalをインストールします。--saveのオプションでpackage.jsonにバージョン付きでdependenciesが書き込まれます。（[参考](https://fractal.build/guide/installation.html#installing-fractal-in-your-project)）

###Fractalをグローバルインストール

```
% npm i -g @frctl/fractal
```
ターミナルのどこからでもFractalが開始できるように、グローバル領域にFractalをインストールします。

##初期設定

###ディレクトリ構成
```
guide
 ├── src
 │    ├── components 
 │    └── docs
 │
 ├── fractal.js
 └── package.json
```
一旦、上記構成でフォルダを作成。
components ⇒　デザインパーツ（コンポーネンツ）を入れるフォルダ
docs ⇒　ガイドの説明などドキュメントを記載するフォルダ
fractal.js ⇒　fractal内の各種設定を記載

###fractal.jsの作成
```
'use strict';

/* Fractalのインスタンスの作成とエクスポート */
const fractal = module.exports = require('@frctl/fractal').create();

/* プロジェクト・タイトルの設定 */
fractal.set('project.title', 'デザインガイド');

/* componentsディレクトリの指定 */
fractal.components.set('path', __dirname + '/src/components');

/* documentationディレクトリの指定 */
fractal.docs.set('path', __dirname + '/src/docs');
```

##コンポーネントを入れてみる
テキストエディタで `header.hbs` というファイルを作って先ほどの `components` ディレクトリに保存します。ファイルには以下のようなHTMLを入れてみてください。

```
<header>
    <div>タイトル</div>
</header>
```

##Docsのトップページを設置する
Documentationのトップページの内容を追加します。テキストエディタで以下の内容のファイルを作って`docs`ディレクトリに`index.md`として保存します。`Markdown`と[YAML front-matter](https://jekyllrb.com/docs/front-matter/)を使って記述します。

```
---
title: ドキュメントページ
---
説明を記述します。
```
ここまでのフォルダ構成

```
guide
 ├── src
 │    ├── components
 │    │    └── header.hbs
 │    └── docs
 │         └── index.md
 │
 ├── fractal.js
 └── package.json
```

##ローカル環境で確認
```
% fractal start --sync
```
ターミナルを立ち上げ上記のコマンドを実行すると、 下記のメッセージが表示され`http://localhost:3000` にて画面が確認できるようになります。

```
┌───────────────────────────────────────────┐
│ Fractal web UI server is running!         │
│───────────────────────────────────────────│
│ Local URL:      http://localhost:3000     │
│ Network URL:    http://10.21.180.184:3000 │
│ BrowserSync UI: http://localhost:3002     │
│───────────────────────────────────────────│
│ Use ^C to stop the server.                │
└───────────────────────────────────────────┘
```
自動でブラウザが立ち上がるようにするには、`fractal.js`に下記2行を追加します。（[参考](https://fractal.build/guide/web/development-server.html#browsersync-integration)）

```
// browsersync設定
fractal.web.set('server.sync', true);
fractal.web.set('server.syncOptions', { open: true});
```

##静的ファイルを書き出し
ローカル環境で確認が済んだら、静的ファイルに書き出します。`fractal.js`に下記の記述を追加します。

```
/* 静的ファイルの書き出し場所 */
fractal.web.set('builder.dest', __dirname + '/dist');
```
下記コマンドを入力すると`dist`フォルダが作成されます。

```
% fractal build
```

##参考記事
・[公式ガイド](https://fractal.build/guide/)
・[スタイルガイドジェネレーターの「Fractal」がかなり良さそう](https://parashuto.com/rriver/tools/getting-started-with-fractal)
・[Fractalを使ったスタイルガイドの作成（中級編）。このジェネレーターかなりいいですよ](https://parashuto.com/rriver/tools/fractal-detailed-settings)