Skip to content

A Minimalist Jekyll Style Guide

You cannot get a simple system by adding simplicity to a complex system. - Richard O’Keefe

This is a style guide for clean and lean Jekyll websites. Its primary goal is to foster simplicity, performance, and maintainability. The contained guidelines are highly opinionated, totally biased, and somewhat radical. Nevertheless, I hope you’ll find some useful bits and pieces.

No External Dependencies

Don’t depend on external services or content delivery networks (CDNs). Bundle all resources locally so that you can still build, develop, and use your website while being offline.

Benefits:

No CSS Frameworks

Modern CSS Grid Layout and Flexbox are powerful enough to create highly usable and responsive layouts with a few lines of code. No need to rely on heavy frameworks such as Bootstrap.

Benefits:

No JavaScript

A website as simple as mine does not really need JavaScript. Yours maybe neither. Less code to maintain, less to transfer over the wire. In addition, the site remains accessible for users with JavaScript disabled.

Benefits:

Exception: MathJax for typesetting math. Only include it when you need it, see this post for details. I’m not happy with this exception, but I don’t see an alternative for the moment.

No Tracking

I had to remind myself why I’m writing this blog at all: First and foremost, I write for myself. For the pleasure of writing, to keep notes and to structure thoughts. If any of this turns out to be useful for others, great, glad I could help. No need to spy on my visitors.

Benefits:

No Comments

Let’s face it: Static site generators are simply not made for this. Sure, there are workarounds, I used to use one myself, but they are hackish at best and typically rely on some external service. Feedback via e-mail is fully sufficient.

Benefits:

RSS over E-Mail Subscription

Provide an RSS feed to allow users to get notified of new posts. Let your website be part of a better web that doesn’t constantly ask for e-mail addresses or personal information.

Benefits:

No Favicons

I simply refuse to give in to the craziness today’s favicons. This used to be a single, simple, small image file added to your website. Nowadays, you are supposed to generate half a dozen images at different resolutions and formats plus some obscure, non-standard XML and text files. In addition, you need to include half a dozen <link> and <meta> tags in your HTML header to make those work. Heck, you need an external service to generate all this cruft for you. Just stop it.

Benefits:

No Pre-Built Theme

Jekyll themes are great to get you started, but most of them come with a lot of boilerplate code. Ironically, some of the most bloated ones carry the word “minimal” in their name. It’s in the nature of a theme to provide a highly generic solution. Instead, build your own site from scratch. Only include what you need and understand.

Benefits:

Hint: set theme: null in your _config.yml to avoid generating default CSS styles.

No Web Fonts

This is the hardest part for me. I’m a confessing typophile, and I just adore a beautiful and well-crafted typeface. I used to waste a lot of time switching back and forth between different fonts and tweaking their settings. Enough of that. The performance impact is non-negligible, and so is the implementation and maintenance burden. Therefore, I finally settled with a simple system font stack.

Benefits:

Plain Markdown

Use plain Markdown whenever possible. No inline HTML or Liquid language in blog posts. This ensures your content can easily be converted to another format if needed. Use a linting tool to check your Markdown files.

Benefits:

Minimal Liquid Code

Keep Liquid code to a bare minimum. It’s tempting to add more and more features with a few lines of code, but it only gets harder to maintain over time.

Benefits:

Minimal Plugins

I use GitHub Pages, so I’m restricted to the officially supported plugins. I keep it down to a few essential ones:

No Syntax Highlighting

Sounds crazy, but in fact many syntax highlighting color schemes are more than sub-optimal in terms of accessibility. Think of bad contrast ratios and color-blindness. Choose whatever you like in your IDE, but I’ll keep it plain and simple on my site. Bonus points: No superfluous CSS required. No excessive DOM size due to the huge amount of <span> elements being generated by the Jekyll default syntax highlighter.

Benefits:

Hint: Disable syntax highlighting in your _config.yml:

kramdown:
  syntax_highlighter_opts:
    disable: true

No Responsive Images

Generating and serving responsive images is sort of a science on its own. You eventually end up generating a dozen files in different resolutions, versions, and file formats. This is certainly doable using additional plugins, custom Liquid code, or external web services. However, none of those approaches is simple and all of them violate some other guideline above. Therefore, I stick to simple compressed and optimized JPEG images for the moment.

Benefits:

No Embedded Videos

Embedding videos from external sources is convenient but comes with a cost: Lots of JavaScript and CSS gets pulled from an external domain. In addition, this approach can be problematic in terms of data privacy (cookies, tracking). Also requires inline HTML or custom Liquid as well as additional CSS for embedding. For now, I just use a good old link with an optional image.

Benefits:

Closing Remarks

Obviously, these guidelines are not for everyone and not for every situation. That being said, I still hope I got you thinking about wether all the bells and whistles on your website are really worth it.

Finally, I’m curious how long it’ll take before I break one of the rules. Subscribe via RSS and check the next post for fancy web fonts. ;-)

In the meantime, here’s some food for thought: