Tools for building a content style guide

Thinking and research about the best tools and technical setup

We wanted to find a simple, solid method for creating an online content style guide, a bit like MailChimp’s. We’re big fans of the integrated (design, development and content) approach of Polaris, made by Shopify, but for this we were concentrating purely on the content.

Styleguides.io list 142 tools for making style guides. A search for the word “content” returns a grand total of 0.

Our criteria were:

1. Simple set-up

We wanted a technical setup that wasn’t too involved, to allow us to focus our efforts on creating the guidelines.

2. Minimal technical debt

A style guide isn’t usually something that gets updated daily, but it’s important that updates are possible. We definitely didn’t want a PDF that would sit gathering digital dust on a shared drive and not get edited for years.

On the other hand, we didn’t want anyone to have to check for security updates and be worrying about plug-ins.

A static site generator rather than a content management system (CMS) seemed like a good fit for this reason. Most other online style guides seem to take this approach.

3. Minimal hosting complications

We wanted something that could be easily hosted on an existing web server or for free somewhere like GitHub or GitLab. We knew that would make life simpler for future editors.

4. A good template for documentation

We wanted a template specifically (and well) designed for style guides, or at least for online documentation, in order to make the final result easy to use.

A lot of online documentation is really ugly; we believe in beautiful things, for internal users as well as external ones.

5. Personalisation

Tweakability (of colours and typography, for example) was important to us in order to help make the style guide feel as if it belonged to its parent organisation. We knew that this would encourage staff to use it. Which is vital.

6. Editability

Our solution needed to be straightforward for an editor to maintain in the future, even if they didn’t have too many technical skills. We’re happy using Markdown, and even, sometimes, the command line. But we didn’t want to assume that editors of our style guide would be.

7. Speed

The output needed to be fast to load. Again, a static site generator seemed like a good approach for this reason.

What we looked at

PatternLab

PatternLab is an excellent tool for developers to build atomic design elements. But it isn’t widely used as a basis for content style guides. We decided that it would require too much retrofitting.

Docusaurus

An open-source solution, Docusaurus templates seemed more suitable for technical documentation than a content style guide.

GitBook

GitBook is quick and easy, but it’s not possible to tweak the standard template. The output is clean, but it wouldn’t feel like it belonged to a client.

Jekyll

As a static site generator, Jekyll seems pretty well suited to something like this, but we decided it was probably a bit too technical for future editors to update content after we’d gone.

JekyllStyleGuide

JekyllStyleGuide looks good. It’s a template specifically designed for the creation of style guides so has some advantages over other Jekyll templates. But, as with other uses of Jekyll, it would mean editors working with Markdown and the command line.

Forestry and Siteleaf

We looked at Forestry.io and Siteleaf, which are both graphic user interfaces for Jekyll. Both look promising but aren’t free, and setting up Forestry with a Jekyll template would need extra development time and effort.

Siteleaf came a close second to our final choice: it looks like a good solution that ticked all of our criteria. It only missed out because the solution we went for in the end was open source.

Frontify

Frontify gives organisations a neat, off-the-shelf product that’s designed specifically for brand and content guidelines. Designed and made in Switzerland, Frontify guides look great but there’s limited scope for personalisation, and it comes with a price tag.

Conversations with content strategists

Content strategists recommended Contentful and Webflow, but both seemed overly complex for what we needed.

The MailChimp approach

MailChimp generate theirs using Middleman. Their approach seemed more bespoke and technical than we needed. Given their creative commons licence, it would be possible to clone what they have, adapt it and maintain the content using a text editor and FTP. But that would mean it would be possible for an editor to accidentally break something, and rolling things back wouldn’t be straightforward. For us that wasn’t a robust enough solution.

What we eventually chose

Publii

Publii has a nice balance of flexibility and ease of editing, and does most of what Jekyll does without needing to touch the command line, or edit Markdown files. It also allowed us to easily tweak the fonts, colours and typography by editing the template and the CSS. It has a good base documentation theme and is a simple way of generating a static site.

The tool can publish directly to GitHub, GitLab, Amazon or Google Cloud. Or it can use FTP to publish to a web server.

One downside for the time being is that multi-editor access is clunky, but that wasn’t a deal-breaker for us.

We’ve now used Publii for two content style guide projects. Read more about how we created the Greenpeace UK style guide.

More Contentious ideas

Making good

You can’t achieve much if you don’t have compelling, high-quality content. But what makes content good? These 10 aspects are crucial.

Useful tools for creating amazing content

Content management systems, despite the name, are not great for content planning, content creation or content editing. These are our favourite tools for content creators and editors.

The content manifesto

Ten principles that can bring about better, more strategic content. And change the world.

Subscribe

Our content tips emails signpost the way to happier, smoother, more efficient content. Some tips will be simple, some more involved; we hope they'll all be useful.

We'll send you one each week until we run out of ideas. We won't spam you or pass your details on to anyone else.

Subscribe

Our content tips signpost the way to happier content.

Thanks, you've subscribed. You should get a confirmation email in your inbox.

Subscribe

Our content tips emails signpost the way to happier, smoother, more efficient content. We'll send you one each week until we run out of ideas. We won't pass your details on to anyone else and you can unsubscribe at any time.

Thanks, you've subscribed. You should get a confirmation email in your inbox.