# Usage

# Tasks

# Start dev server
yarn dev
# or
npm run dev

# Build files for production (outputs to `dist`)
yarn build
# or
npm run build

# Create static styleguide (outputs to `dev`)
yarn build:dev
# or
npm run build:dev

# Create static styleguide without components (outputs to `proto`)
yarn build:proto
# or
npm run build:proto

# Run linting
yarn lint
# or
npm run lint

# Run unit tests (creates coverage-report) and e2e tests
yarn test
# or
npm run test

# JavaScript

JavaScript files are bundled together with webpack (opens new window) and transpiled with Babel (opens new window) and the env preset. To learn more about JavaScript modules head over to the MDN article on import (opens new window). ESLint (opens new window) checks if the code follows the Standard Style (opens new window).

Global ESLint rules (opens new window) are set in .eslintrc.json. Per-file rules can be set with comments (e.g. /* eslint no-console: "off" */). With a .eslintignore file in the project root, JavaScript files can be excluded from linting (opens new window).

# CSS

Sass (opens new window) is a CSS preprocessor supporting variables, nesting and mixins – among many other features. For a quick start jump to the Sass Basics (opens new window). stylelint (opens new window) monitors the code for errors and consistency deviations. It uses the Sass Guidelines config (opens new window) with a few additions.

Global stylelint rules (opens new window) are set in .stylelintrc.json. Per-file rules can be set with comments (e.g. /* stylelint-disable selector-max-id */). With a .stylelintignore file in the project root, CSS files can be excluded from linting (opens new window).

# HTML

Nunjucks (opens new window) is an HTML templating engine based on JavaScript. The styleguide creates static HTML from Nunjucks files. Take a look at the templating docs (opens new window) for further information on Nunjucks.

# Global variables, filters, and tags

The styleguide adds a few custom gobal variables, filters, and tags.

  • process.env
    • NODE_ENV: Returns development or production ({{ process.env.NODE_ENV }})
    • FESG_ENV: Returns dev, build, build:dev or build:proto ({{ process.env.FESG_ENV }})
  • fesg
    • head: Outputs CSS and JS links ({{ fesg.head }})
    • sidebar: Outputs the styleguide sidebar ({{ fesg.sidebar }})
    • footer: Outputs the styleuide footer ({{ fesg.footer }})
    • components: Returns the component template as a string (fesg.components)
  • relative: Custom filter to create relative URLs ({{ "assets/water.jpg" | relative }})

# Components

Component pages are reference for UI elements. They will be generated only if the component folder contains a docs.njk file. Each component documentation should follow this pattern for a styled output:

{% set page = {
  title: "Component Title",
  description: "A short description"
} %}

{% extends fesg.components %}

{% block body %}

  {% section title="Variant #1", description="A short description" %}
    <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Corporis, unde.</p>
  {% usage %}
    A short description written in markdown. For example:
    * usage instructions
    * todos
  {% code %}
    <p>HTML code block</p>
    <p>Highlighted with Prism.js</p>
  {% endsection %}

  {% section title="Variant #2", description="A short description", background="#fff" %}
    <p>Lorem ipsum dolor sit amet consectetur adipisicing elit. In est ex porro.</p>
  {% endsection %}

{% endblock %}

# Prototypes

Prototypes represent final pages. There aren't many limitations. Just go ahead and build a nice reference page by leveraging all of Nunjucks templating features.

# Assets

All files placed in src/assets are copied to the output directory. Image files are compressed with imagemin (opens new window) – a lossless compressor for JPG, PNG, GIF and SVG.