Getting Started
How to setup and configure this Jekyll-based style guide boilerplate.

# Installation

To start you’ll need to download and install Jekyll (3.1 or higher) and the source code from Github.

> Sample UI patterns and documentation have been included in this tool to indicate what a finished Style Guide could look like. You can remove the files from `src/` and the `CNAME` file to start from scratch.

To serve the files locally run the following code in terminal:

    $ cd /path/to/local/folder/
    jekyll serve

Once your style guide is complete you can publish it to Github Pages like any other Jekyll website.

# Configuration

    jekyll-style-guide/
    ├── _config.yml
    ├── index.md
    ├── README.md
    │

All settings are contained in the `_config.yml` file. To use this tool out of the box, you only need to adjust the `pattern settings`.

## General Settings

These are standard Jekyll configuration settings, check the documentation for information on how to use this.

## Style Guide Shell Settings

These settings control the default variables used in the shell, check the Editing the Styleguide section for help on how to use them.

## Collection Settings

These settings control how documentation and pattern files are generated, and where they are located. Check the Editing the Styleguide section for help on how to use them.

## Pattern Settings

These settings are used in all patterns and should be updated based on your needs.

    ## Pattern Settings

    pattern_author: AUTHOR NAME             ## sets the author in the <head></head> tag
    pattern_description: DESCRIPTION        ## sets the description in the <head></head> tag
    pattern_language: en                    ## sets the language in the <html></html> tag
    pattern_favicon: /src/assets/images/icon.ico

    pattern_styles:                         ## (list) add style locations here
      - /src/assets/css/style.css

    pattern_scripts:                        ## (list) add script locations here
      - /styleguide/js/libs/jquery-2.1.4.min.js

    sass:
      sass_dir: src/assets/_scss            ## sets the location of the stylesheet
      style: :compressed                    ## minifys the stylesheet

> Remember you need to `$jekyll build` or `$jekyll serve` your site in terminal after changing any of the config files.

# Adding Patterns

## What is a Pattern?

A ‘Pattern’ is any part of the user interface, by default there are 3 types:

- Foundations
  - Foundations are global constraints that define the basic parameters of parts of the UI.
  - Example, a Typeface, Primary or Secondary Colors, Icons.
- Components
  - Components are stand-alone UI patterns that can be directly used in the interface.
  - They can include Foundations, or can be constructed with uniques styles.
  - Example, Primary Button, Secondary Button, Card, Card Group, Table, etc.
- Templates
  - Templates are pre-determined page layouts.
  - They can include components and foundations, or can be constructed uniquely.
  - Examples, Full-Width Content Page, Sidebar Page, Two Column Page

    │
    └── src/
        ├── assets/
        │   ├── _scss
        │   ├── css
        │   ├── fonts
        │   └── images
        │
        └── patterns/
            ├── foundations/
            │   ├── ...
            ├── components/
            │   └── ...
            └── templates/
                └── ...

## Uploading Patterns

- Write your HTML pattern in a Markdown file.
- The pattern must start with Front Matter.
- Set the `title`, `maturity`, and the location of the corresponding `styles`.
- Optional: Turn off the Pattern Controls by using `control: exclude` - this is particularly useful for foundation patterns.

    ---
    title: Default Button
    styles: base/button.scss
    maturity: ready
    control: exclude
    ---
    <a href="javascript:void(0)" class="button">Click Me!</a>

- Upload your pattern to the corresponding folder in `src/patterns`.
- You need to make sure your pattern is 4 folder levels deep to ensure they get linked correctly from the navigation and roadmap, so group you patterns in sub folders

    #Example 1: Primary Colors stored in a /color sub folder.
    /src/patterns/foundations/color/primary-colors.md

    #Example 2: Disabled Card stored in a /cards sub folder.
    /src/patterns/components/cards/disabled-card.md

## Editing Pattern Assets

- Pattern assets are stored in the `src/assets` folder.
- You can add additional styles/scripts to a pattern via the Pattern Settings in the `_config.yml` file - styles will automatically be included in the `<head>`, scripts will automatically be included before the `</body>` tag in all patterns.

> Keep your styles organised. Try this simple SCSS playbook.

# Adding Documentation

## What is Documentation?

‘Documentation’ is used to store information relating to a pattern (or group of patterns), as well as information about the style guide itself - this page is an example of a document.

By default, documentation is stored in the `_docs` folder and grouped in directories that correspond to the pattern directories. An additional `/about` directory is also provided, this can contain general/non-pattern specific contents (like this page).

Patterns are always loaded into a document via an iFrame, so any style guide related styles will not interfere with your pattern.

    │
    ├── _docs/
    │   ├── about/
    │   │   └── ...
    │   │
    │   ├── components/
    │   │   └── ...
    │   │
    │   ├── foundations/
    │   │   ├── color.md
    │   │   ├── typography.md
    │   │   └── ...
    │   │
    │   └── templates/
    │       └── ...
    │

> Adding any document into these folders will automatically make it appear in the style guide navigation.

## Documentation Settings

These settings are defined in the `config.yml` file and ensure that each document outputs with the correct Jekyll layout and meta data.

    ## Collection Settings

    ## Outputs the _docs collection !Required
    collections:
      docs:
        output: true

    ## Sets the default attributes for the Documentation and Pattern Files !Required
    defaults:
      -
        scope:
          path: "_docs"
        values:
          layout: doc
          type: doc
      -
        scope:
          path: "_docs/about"
        values:
          layout: doc
          type: about
      -
        scope:
          path: "_docs/foundations"
        values:
          layout: doc
          type: foundation
      -
        scope:
          path: "_docs/components"
        values:
          layout: doc
          type: component
      -
        scope:
          path: "_docs/templates"
        values:
          layout: doc
          type: template

## Adding Documentation

- Create your document file in Markdown format.
- Your filename can match the pattern URL, but it does not have too.

    #Pattern Location.
    /src/patterns/foundations/color/primary-colors.md

    #Corresponding document file option 1:
    /_docs/fondations/color.md

    #Corresponding document file option 2:
    /_docs/fondations/palette.md

- The document must start with Front Matter.
- Set the title.
- Optional: add info which will be displayed at the top of the document page.
- Optional: add `nav: true` into the Front Matter if you would like to display a mini contents menu at the top of the page (like this page).
- You can use any Markdown in the page content area.
- To include a pattern in the document page you must include the pattern block and specify a `url` variable in the include. By repeating this process you can include multiple patterns on the page. See the sample below taken from the `button.md` file.
- Note that the pattern controls and maturity are set in the pattern file.

> The contents menu will automatically generate a table of contents based on any `h1` items on the page.

    ---
    title: Button
    info: Use buttons to signal actions.
    nav: true
    ---

    # Basic Buttons

    A button can contain text. Although any tag can be used for a button, it will only be keyboard focusable if you use a `button` tag or you add the property `tabindex="0"`.

    {% include pattern_block.html url='/src/patterns/components/button/default_button.html' %}

    {% include pattern_block.html url='/src/patterns/components/button/disabled_button.html' %}

# Sample Pages

Coming Soon

# Editing the Style Guide

Coming Soon