Usage #

Tasks #

# Start dev server
npm run dev

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

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

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

# Run linting
npm run lint

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

JavaScript #

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

Global ESLint rules 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.

CSS #

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

Global stylelint rules 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.

HTML #

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

Global variables, filters, and tags #

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

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. 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 – a lossless compressor for JPG, PNG, GIF and SVG.