Skip to content

Latest commit

 

History

History
136 lines (109 loc) · 5.25 KB

README.md

File metadata and controls

136 lines (109 loc) · 5.25 KB
Raw

PostCSS Xcom Styleguide

Creates a styleguide from YAML-structured CSS-comments. Supports Twig, Jade/Pug, HTML and PHP templates.

Background

Although there are plenty styleguide generators available, they all seem to only parse markup files. This creates an extra layer of abstraction when used in an environment that relies heavily on templating systems. We don't want to end up having to maintain multiple templates for the same output, so we thought it might be good to have the template function as input for the styleguide. So there it is: PostCSS Xcom Styleguide

Installation

PostCSS

This is a plugin for PostCSS so make sure to have PostCSS installed in your product before using this plugin. There are different usages for PostCSS depending on your build tool or workflow.

PostCSS plugin

You can install the plugin directly from the NPM registry

npm install postcss-xcom-styleguide --save

Getting started

The plugin extracts comments inside your stylesheets which have to be structured as valid YAML-documents. For instance:

/*
---
section: Buttons
title: Primary buttons
demo: styles/modules/buttons/buttons.php styles/data.json
---
There is a description for primary buttons.
It can be cool and even cooler
*/

.button--primary {
    display: inline-block;
    padding: 10px;
    background: blue;
    color: #fff;
    transition: background 250ms;

    &:hover {
        background: red;
    }
}

A section is actually a single page inside the styleguide. Different modules from different css-files can still belong to the same sections; they are automatically being aggregated by the plugin. This allows for pages being created that display single modules but could potentially contain full page mockups.

Parameters

section (required)

The name of the section the comment-block belongs to. Specify the same name (case insensitive) across blocks to group them under the same section.

title (required)

The title to be displayed for the block inside the section

demo (optional)

The demo attribute consists of two parts: relative/path/to/demo/file and relative/path/to/data/object (optional)

The first argument of the attribute is the path to te actual demo that should showup in the styleguide. Input formats supported are: Twig, Jade/Pug, HTML and PHP. Twig and PHP templates are actually generated by a PHP parser. This parser is mounted by the styleguide once it detects Twig or PHP-templates.

The second argument is the path to a JSON-object that contains mock-data which can feed template data. This is particular useful to recreate data that is not yet available in the styleguide but will be once the templates are used inside a CMS-like environment. The objects can also mock functions that are provided externally by, for example, Processwire. For instance:

{
    "button": {
        "title": "go There"
    },
    "page": {
        "cropImages": [{
            "alt": "image 01",
            "getThumb()": "http://placehold.it/400x300.jpg"
        }, {
            "alt": "image 01",
            "getThumb()": "http://placehold.it/400x300.jpg"
        }]
    },
    "pages": [{
        "title": "page one"
        },{
        "title": "page two"
        }
    ],
    "tree": {
        "build()": "<ul><li>test</li></ul>"
    }
}

In the data-object above there are a few mocked function objects that can be used inside templates, e.g. $page->cropImages->getThumb() and $tree->build().

Notice: While the demo attribute is optional, the block will obviously not show up under the styleguides' section while it's empty.

description (optional)

Anything outside of the YAML-delimiters (---) is considered a description for the comment block. Github-flavoured markdown is supported inside these descriptions.

Options

The following options are available inside the plugin

option default description example
title '' The title for the styleguide My Awesome Styleguide
src file processed by PostCSS Optionally specify a file that should be processed (might be handy when compiling multiple files) wireframes.css
dest styleguide Output path for the styleguide styles
twig.extensions(*) null File path (relative to root) pointing to Twig-extensions extensions.php
php.extensions(*) null File path (relative to root) pointing to PHP-extensions functions.php
include null Array with either javascript files or stylesheets that will be included in the styleguide ['css/master.css', 'js/main.js']

(*) Both PHP and Twig are instantiated without any plugins or function installed. To still make them available during styleguide compilation, they can be provided externally.

Twig extensions example:

<?php
function myTwigExtension(\Twig_Environment &$twig) {
	$twig->addFunction(new \Twig_SimpleFunction('__', function($data){
    	return $data;
  	}));

	$twig->addFilter(new \Twig_SimpleFilter('strftime',function($item1,$item2){
    	return strftime($item2,$item1);
  	}));
}

PHP extensions example:

<?php
function __($text) {
    return $text;
}

Roadmap

  • Write functional and unit tests
  • Only parse changed comment blocks to improve speed
  • Accept array inside options src