Working with the style guide

Documenting a component

To document a component within Bedrock, create a folder with the component category/content/templates/_components folder.

Then, create a and a .pug file with the component name in said folder. Put your template code in there and the component will show up in the style guide within Bedrock.

Humanized component names

Since Bedrock 1.10, we automatically try to prettify the component name based on the folder structure.

You can categorize components with a prefix, for example c-my-component.

Within Bedrock’s configuration you can then define the meaning of a custom prefix:

componentCategories: {
  oc: 'Official components',
  cc: 'Custom components'
}

This prefix defines how the category shows up in your style guide.

Component descriptions

To make the documentation prettier, you can use a markdown (.md) file with the same filename as the .pug file in the folder.

Use YAML front matter to give the component a title and content.

Here is a template:

---
title: My component
---

[Description of my component in markdown]

Documenting typography

To document typography, create a new component and use a template like this.

This example is the one from Material design – you can adapt it to your needs by changing the types of headings that get included.

Note that some of the classes in there are hooks for automatically documenting the font size of components in pixels using Javascript.

Documenting icons (SVG)

You can put SVG files in the content/icons directory.

We also support 1 level of folders here, e.g. content/icons/16 and content/icons/128 . For example when you have small icons and large “illustrative” icons.

Within your pug file, use a loop like this to loop over all your icons in their respective folders:

[Code for loop here – Work in progress]

Documenting icons from a Bedrock generated icon font

Make sure icon fonts are enabled. See configuration.

Put SVG files into the content/icon-font-source folder.

Then use a loop like this in any component to document the icons:

[Code for loop here – Work in progress]

To style the component documentation, we recommend writing a little bit of custom code scoped to the styleguide. You will find example code in our Bedrock bases e.g. the Material design base.

Documenting colors from SCSS variables

Use code like this gist to loop over colors.

We are supposing you have defined a reference to a colors.scss file in your config, that follows a very specific syntax, see this template for an example.

Since we depend on regular expressions to parse the colors, you should use exactly this syntax. Don’t use SCSS variables in this file – only HEX values.