A hugo style guide/pattern library for theme dev & demo


#1

I’m contemplating a style guide for Hugo themes. By that I mean a collection of html elements and page components so you can see how they’re rendered, browser test etc without adding lots of random content to your own site.

For examples Style Guide boilerplate and Adactio’s Pattern Primer. Forking and adapting the former would be my likely path.

I’m mostly contemplating the ‘how’ right now. First thought was a page or pages as part of the theme. Second thought was that they’re essentially content and ought to be in the content folder. Third thought was that it should really be part of hugoBasicExample.

Suggestions and thoughts welcome.


#2

I’ve been thinking along similar lines, perhaps adopting https://bradfrost.github.io/style-guide-guide/

Open to collaboration!


#3

I hadn’t seen these style guides before, but have been listing content components that I want to use for myself in this page: https://brunoamaral.eu/page/elements/

Slideshows, Content Highlights, image alignment and photo galleries.


#4

Just when I thought no one was interested and decided to do my own thing two people reply :slight_smile:

I think what I really want is usually called a pattern library. Most of these ‘style guides’ seem to require configuration and documentation added before a generation step. If possible I’d like to get everything working through Hugo. And I really just want code examples I can theme with CSS whilst building a site, not some high falutin’ corporate style-guide - most of the time I’m the only person who’ll ever look at them.

What I had in mind is adding a content/style-guide folder to my base theme/starter site containing a page or pages of standard html elements, common ‘components’ and examples of Hugo shortcode output as @brunoamaral shows.

I’d also like to bring in something like Palx github/single page app and related projects. Where we’d define a brand colour in theme.toml or wherever and a whole palette of harmonious colours gets output in a page.

Because of the shortcodes, maybe other things, I feel like this needs tied fairly closely with a base theme/starter site. (I’m working on updating mine right now.) But I’m certainly open to collaboration, discussion, moving parts out to a different project or whatever.

Want to elaborate on what you had in mind @easherma?

Hopeful I can post back some working code later today…


#5

I think it’s important to make a distinction between style guide, which is mostly color, type and fonts to what are Components/Elements or Content Formats.

A component will be something that is included in the content and part of the storyline that the author is building. Like a gallery, caroussel, or paragraph call-out. Shortcodes are a good implementation for these elements and mine are based on bootstrap. I am more than happy to share them with others who might want to use the same logic.

In short, a style guide ensures brand coherence and elements enrich the content while following the style guide.


#6

Yep, but in effect what you - and half the web - call a style-guide is more of a Brand guide. That said go and look at some of these style-guide boilerplates, pattern libraries, Pattern Lab etc and you’ll find they all mung pattern/component libraries in with a style guide anyway. At the end of the day it’s useful to see how those brand elements affect html components.

I want a pragmatic ‘styling’ or ‘themeing’ guide if you like.

In fact I’d say they opposite. It’s not important to make a distinction between these things. I’m much more interested in a pragmatic approach of what’s useful.

But these things do get very personal.


#7

@brunoamaral I should also add: Thanks for sharing your shortcode/compentents. They look useful :slight_smile:


#8

Also adding - I think what I’m after is also referred to as a Living style guide. In the sense that it’s part of the site and updates as you update CSS.


#9

Very, very early work in the context of my site starter/theme starter combo.

Make sure you’re on the ‘version2’ branch.
(Project name will probably change, starting to think I should have started a new project!)

Went with html over markdown.