0.2.0 • Public • Published

Piedmont Build Status

Generate a Living Styleguide based on a Frontend Prototype.

Getting started

npm install piedmont --save-dev

Create Living Styleguide

var piedmont = require('piedmont');
piedmont(options, callback);

While the callback function isn't really used for now, you can omit the argument.



Type: String Default value: __dirname

dest, src and styles are relative to the base path.


Type: String Default value: './test/result/styling-guidelines'

Destination path of the generated living styleguide. Path is relative to cwd.


Type: Boolean, String Default value: ./test/fixtures/docs

Source path of markdown files that will be parsed and converted to content pages. Piedmont uses a glob pattern to get the files: ./test/fixtures/docs/*.md.

Path is relative to cwd. See the Documents section for further details.

Set to false if creating a styleguide is not required.


Type: Boolean Default value: true

Building a component inventory based on the frontend prototype in the src directory. Set to false if creating a component inventory is not required.


Type: String Default value: './test/fixtures/build'

Path of the built frontend prototype. Path is relative to cwd.


Type: Boolean, String Default value: './test/fixtures/styles'

Path to the annotated stylesheet files. Currently only Sass files are supported, so you have to specify the path only. Piedmont uses a glob pattern to get the files: ./src/sass/**/*.scss.

Path is relative to cwd.

Set to false if creating a styleguide is not required.


Type: String Default value: './theme/default'

Path to the theme directory.


Type: String Default value: './tmp'

Temporary files directory.

Component Inventory

The component inventory (or interface inventory) is built on top of extracted partials. Partials are representations of components as markup.
Partials need to be wrapped in specific HTML comments. Where <!-- extract:Name of the partial --> intrduces a partial, <!-- endextract --> defines the end.

<!-- extract:Figure -->
  <img src="http://placehold.it/640/480" alt="Unknown image content" width="640" height="480">
    <p>Random picture</p>
<!-- endextract -->

Properties (Options)

Properties are part of the introducing comments. Property name and value are separeated by colons: property:value. While colons are protected characters, property values must not contain them.
Most properties are single value properties, some properties have multiple values. Multiple values are separated by colons too: property:value A:value B.


Single value property. Sets the partial category.

<!-- extract:News teaser category:Teaser -->
<!-- endextract -->
<!-- extract:Event teaser category:Teaser -->
<!-- endextract -->


Single value property. Sets the partial name explicitly. Overrides the value of the extract property.

<!-- extract:A common partial name:A special partial -->
<!-- endextract -->

The partial name will be A special partial.


Multiple value property. For rendering purposes in the component inventory you might wrap the partial code in additional markup. While components should be independent of their context, it is necessary to show how they behave in several contexts, e.g. content sections in grid layout.

<!-- extract:Teaser wrap:<div class="row"><div class="col-8-of-12">:</div></div> -->
<article class="teaser">
  <h3 class="teaser__title">Arthurs Towel</h3>
<!-- endextract -->
<!-- extract:Teaser in Sidebar wrap:<div class="row"><div class="col-4-of-12">:</div></div> -->
<article class="teaser">
  <h3 class="teaser__title">Arthurs Towel</h3>
<!-- endextract -->

In both cases the partial code is the same. The markup that is used to render the component in the component inventory differs.


<div class="row">
  <div class="col-6-of-9">
    <article class="teaser">
      <h3 class="teaser__title">Arthurs Towel</h3>

Teaser in Sidebar

<div class="row">
  <div class="col-3-of-9">
    <article class="teaser">
      <h3 class="teaser__title">Arthurs Towel</h3>


The styleguide section is based on annotated stylesheets.

General annotations


Override the value that is extracted by the parser. This should be an option if the value is an expression or the value is not a digestable CSS property value.

/// @color Overlay background   
/// @value rgba(0, 0, 0, 0.6)   
$transparent-dark: transparentize($dark, 0.4);  

Specific annotations


/// @boxShadow Dropshadow   
$dropshadow: 1px 2px 9px rgba(30, 30, 30, 0.3);   


Color value. Use the optional @group to group colors. Groups might be Main, Decoration, Notice, Buttons, Transparencies, etc.

/// @color Primary 
/// @group Main 
$color-primary: rebeccapurple;   


Single font name. Use @fontWeight to specify the available font weights.

/// @font FFDin 
/// @fontWeight 300 
/// @fontWeight 400 
/// @fontWeight 700 
$font-ffdin: FFDin;   


Font family cascade.

/// @fontFamily Headline 
$font-family: Times"Times New Roman"serif;   


Font size value.

/// @fontSize Small 
$font-size-meta: 1.4rem;


Gradient type is specified in @type. Valid values are linear and radial.

/// @gradient Purple fade 
$gradient-purple: linear-gradient(to bottom, rgba(102,51,153,1) 12%,rgba(102,51,153,0.5) 54%,rgba(222,71,172,0) 100%);


Line height value.

/// @lineHeight Base 
$base-line-height: 1.5;


Spacing value. Use the optional @group to group spacings. Groups might be Layout, Component, Form, etc.

/// @spacing Base 
/// @group Layout 
$spacing-layout: 2rem;   


Duration of animations and transitions.

/// @timing Sluggish 
$duration-sluggish: 1.4s;


Transition value.

/// @transition Fade 
/// @value opacity 0.6s 0s ease 
$transition-fade: opacity $duration-slow 0s ease;


Additional pages besides styleguide and component inventory will be created based on markdown files in the docs directory. The markdown documents will be converted to HTML via marked. These files will be converted to handlebars templates digestable by Assemble. While Piedmont does some parsing, you can override the poster data of the handlebars page template right in the markdown document. Possible values are

  • title: Document title and navigation label
  • class: Classname of the <body>
  • parent: Set another document as parent. The value equals the parents filename without extension.

An example of a poster is shown below. Assume the following page structure.

- engines.md
- rocket.md
- steam.md

The content of docs/rocket.md looks like:

title: Rockets are looking for the stars
parent: engines
# Those Rockets Are Looking For The Stars

Release History

(Nothing yet)


Copyright (c) 2015 Tilman Justen. Licensed under the MIT license.


npm i piedmont

DownloadsWeekly Downloads






Last publish


  • tilmanjusten