How to create a living style guide using hologram

Documenting a website's style scheme, also known as ‘Style guide Driven Development’ or SDD, has now become an essential part of web projects today. SDD involves creating containable and reusable components or patterns, rather than designing a website page by page.

While there are many different style guide tools available, this article will cover the benefits of using the Hologram style guide by Trulia. I recently discovered this style guide and instantly appreciated its flexibility. In this article, I’ll explain how best to use Hologram to create your own living style guide.

Why use hologram?

The main objective of Hologram is to write your style documentation directly into the CSS files. Some of the benefits of doing this include:

Better organisation of your design elements and components

Your CSS files are the only source required to maintain your style guide. This forces you to structure them in a way that best reflects the goals of SDD and the goals you want for your project.

Write your documentation alongside your CSS

This will act as reference in immediate view of the code and will help remind you to update the style guide, as well as your code base, if tweaks or changes to design occur at a later date.

How to install hologram

Hologram is a Ruby gem that you can install on your machine by running `gem install hologram` on the command line. Once installed, it can be added to any project by running `hologram init` from within the project's root directory. Alternatively, I would recommend running `hologram init` in a new directory (or maybe even in a specific theme directory) to keep the style guide separate from other files.

For example:

$ cd ~/Sites/my-website/styleguide
$ hologram init

This will create the following files and directories:

Author’s note: Hologram may be used with CSS and any other preprocessor variety. However, the remainder of this article will refer to Sass specifically.

Configuring your hologram style guide

The next step in the process is to set up the desired configuration for your style guide, using the `hologram_config.yml` file that is generated during the install process.

Below is an example of the `hologram_config.yml` file as it is created initially:

# Hologram will run from same directory where this config file resides
# All paths should be relative to there
# The directory containing the source files to parse recursively
source: ./sass
# The directory that hologram will build to
destination: ./docs
# The assets needed to build the docs (includes header.html,
# footer.html, etc)
# You may put doc-related assets here too: images, css, etc.
documentation_assets: ./doc_assets
# The folder that contains templates for rendering code examples.
# If you want to change the way code examples appear in the style guide,
# modify the files in this folder
code_example_templates: ./code_example_templates
# The folder that contains custom code example renderers.
# If you want to create additional renderers that are not provided
# by Hologram (i.e. coffeescript renderer, jade renderer, etc)
# place them in this folder
code_example_renderers: ./code_example_renderers
# Any other asset folders that need to be copied to the destination
# folder. Typically this will include the CSS that you are trying to
# document. May also include additional folders as needed.
dependencies:
- ./build
# Mark which category should be the index page
# Alternatively, you may have an index.md in the documentation assets
# folder instead of specifying this config.
index: basics
# To additionally output navigation for top level sections, set the value to
# 'section'. To output navigation for sub-sections,
# set the value to `all`
nav_level: all
# Hologram displays warnings when there are issues with your docs
# (e.g. if a component's parent is not found, if the _header.html and/or
# _footer.html files aren't found)
# If you want Hologram to exit on these warnings, set the value to 'true'
# (Default value is 'false')
exit_on_warnings: false

We will look at some of these settings in more detail later in this article.

For now, we will update the `source` setting. Please direct this to your site's theme Sass directory. Then go ahead and generate your style guide!

Run the following from the style guide directory:

$ hologram

It's that simple!

You should then see something similar to the following file structure below:

These are the build files for the style guide that you will see in the browser.

Next, we will cover how to add documentation to your Sass files and start building up that style guide with your custom styles.

Add documentation to your Sass files

Now that you have the setup out of the way, it's on to the fun part - writing your documentation!

Hologram accepts documentation written in a combination of Yaml and Markdown at the beginning of a Sass file.

The top block within the three hyphens is the Yaml configuration settings. We have title, name and category. These are all required and define how the style guide is put together.

Below the settings and within the closing `*/`, you can include any kind of information that you think will be useful, such as explanatory text, data tables, links and more. This will all be written in Markdown.

You will also notice the `html_example`, a block of code using the Markdown syntax but also a Hologram specific feature. This demonstrates how HTML markup and class attributes should be implemented and can be edited for your own purpose.

There are also other layout types that come as part of Hologram. These are:

html_example_table

haml_example

haml_example_table

js_example

jsx_example

The individual templates are found in the `code_example_templates` directory, seen below:

More information on how to use and customise these can be found on the Hologram GitHub page here.

Configuration explained

There are a few settings that come in handy for customising Hologram. I've listed here, in order of importance, the ones you're most likely to update in every instance.

Destination of documentation

Destination is where you set the directory that Hologram will store your complete style guide files.

# The directory that hologram will build to
destination: ./docs

This can simply be left as is, and you could use a symlink or redirect to ensure you have a nice URL, such as 'mywebsite.com/styleguide'.

It could also be set to build directly to a `styleguide/` directory in your project root, or to any other location that works for the project or framework being used.

Documentation assets

The `documentation_assets` setting is simply the name of the directory where assets for the style guide are to be found.

You can customise the header and footer to your needs, and add any additional images, stylesheets or scripts you may require for functionality and design of the style guide itself. More information on this can be found under 'Style the style guide' later in this article.

Documented CSS to create your style guide

You will need to tell Hologram where your documented Sass files reside. This is what the `dependencies` setting is for. Include the directory of your Sass files and any other directories containing assets needed for the final style guide.

# Any other asset folders that need to be copied to the destination
# folder. Typically this will include the css that you are trying to
# document. May also include additional folders as needed.
dependencies:
- ./build

Style the style guide

In terms of design, Hologram doesn't come with any styling or functionality. It is down to you to add it. This would have to be the biggest drawback I see with Hologram.

The demo website is a good place to begin. It's perfectly functional and suits basic requirements. There is also plenty of room for you to alter the design or apply a completely new one.

Below is an example of what Hologram gives you to start with, which is the header and footer:

It is really easy to implement your own custom design to a Hologram style guide. You can also include any number of stylesheets or scripts you would like to alter functionality and, indeed, style the style guide itself.

The idea may be a rather appealing and fun task for any designer. However, at the same time it can be the exact opposite.

As well as the example website, there are a couple of themes available to help you save time and get your style guide built quicker, if need be. These can be found on the Hologram GitHub page here.

Include in Gulp or Grunt

If you are using Gulp or Grunt in your workflow, there are plugins available for Hologram so you can automate the style guide build.

Retrofit a style guide

Our ultimate goal will always be to begin each and every project by implementing an SDD approach. However, in the real world, other factors such as time restraints, budget, legacy code, team resource, or experience, mean that this is not always the case.

One of my favourite aspects of Hologram and this type of style guide is that retrofitting is entirely possible. Because documentation is included directly in your Sass files, minimum effort is required to detail your existing website's styles.

When considering a retrofit, you will need to take into account what you already have. Do you have Sass partials separated out in categories, and a reasonable pattern that would welcome documentation?

If refactoring is considered possible, please go ahead. It may be that you find areas that need improvement and refining. Take a look at SMACSS or Atomic Design for guidance on this.

However, it is important to ensure you have a balance and don't overdo it. Minor tweaks could probably be accommodated. However, full-scale refactoring may have to be reconsidered as a feature update down the line.

In summary

The Hologram style guide has several pros and cons to its use. The pace with which you can get set up and start documenting your styles is impressive. The small overhead in applying a functional design can be seen as a setback at first, however it can be levied by applying a basic theme from either the example website or other themes available.

By structuring your Sass partials in a manner similar to SMACSS or Atomic Design, combined with having your style documentation preceding your CSS in the same file, you may find that maintenance, project scaling and team-member onboarding should be less painful overall.

Categories

Links

About us

Inviqa is a technology partner and consultant trusted by leading brands to meet strategic goals through digital solutions. A specialist in ecommerce, content solutions, and custom software development, we help pioneering businesses engage, convert, and retain their audiences.