Wren

A paper-style theme for Jekyll. Check out the GitHub pages deployment to see what the default looks like and read on for information on usage and customisation. Be aware that this beta software so will contain bugs; use it at your own risk.

Features

• 🎨 Responsive, customisable design
• 🕔 See post reading time
• 🗄️ 'First published on' icons
• 🏷️ Browse posts by tags
• 🧑 Browse posts by author
• 📺 Embedded YouTube, Twitch, etc
• 🦶🏼 Extendable head, foot, and post meta
• 📃 Optional pagination
• 📰 Atom/RSS feed of posts
• 📈 In-built search engine optimization

Installing

Whether you fork this repo or start from scratch there are two supported options for using Wren as your theme. Which works better for you will depend on your personal priorities.

Theme Gem

Use the jekyll-wren gem, fetched automatically from RubyGems or downloaded from the releases page and installed locally. Either way you'll need to add

theme: jekyll-wren

to your config and

gem "jekyll-wren", "~> 0.4"

to your Gemfile plugins list.

The upsides are that builds will be quicker and you'll have more control over the version through the Gemfile. The downside is that it will prevent building with GitHub Pages' builder since Wren isn't on the whitelist (though you'll still be able to build locally and push to a GitHub pages branch/repo).

Remote Theme

It's possible to use the theme directly from this repo. You'll need to add

plugins:
  - jekyll-remote-theme

remote_theme: foggalong/[email protected]

to your config and then

gem "jekyll-remote-theme", "~> 0.4"

to your Gemfile plugins list.

The upside is that this will work with GitHub Pages' builder (Jekyll Remote Theme is on the whitelist). The downsides are that builds will be slower and your version control is slightly weaker; you're tied to HEAD or a specific version.

Config Options

The config.yml in this repo can be used as a template for your own Wren instance. The file is thoroughly commented so it's worth having a read to know all the options available.

Custom Templates

Minima has a feature which allows users to create a _includes/custom-head.html file which is then included with the rest of the head. This is a useful feature if, for example, you want your website to cover favicons for more browsers than the default setup does.

Wren keeps this feature and extends it so that custom-foot.html (displayed above the copyright notice) and custom-meta.html (displayed at the end of a post's meta line) can also be specified.

Custom Styling

Like Minima (on which Wren's SASS is built) there are a whole bunch of variables which you can change to personalise the theme. To do this you just add lines such as

$background-color: #3d9da3;

to assets/style.scss and you're good to go. The list of what's customisable is slightly different (and longer!) than Minima so have a look at the full list of style variables.

Pagination

If the following two config.yml lines aren't commented, Wren will use Jekyll Paginate to split the posts page into multiple pages of paginate many posts with url paginate_path.

paginate: 5
paginate_path: "/blog/:num"

Note that due to Paginate's technical limitations this will only happen on the main posts page, not other post lists such as the tags page. It's generally quite limited in how it works compared to Paginate v2, but the latter isn't on the whitelist.

Another caveat is that, if you're using Paginate, the main post list page must have filename index.html; that's why in this repo it's blog/index.html. If you're not using Paginate though, Wren allows you to put that file anywhere and called whatever you like without problems.

Error Pages

Wren includes error.html, a layout for formatting error pages; they're centered, have different spacing, and slightly different <h1> formatting. In errors/ there are some examples; those aren't in the theme-gem (see #25) but to use them just copy to your website's repo. See this tutorial for configuring error pages on GitHub pages, Apache, and Nginx.

Philosophy

I ❤️ Wrens. They're smol, quick, and rotund. When I was little we had a family of them come nest in our garden and they sang the most brilliant songs. Oh wait? You're saying this was supposed to be the project's philosophy? Let's just just say it's to be small, fast, and round.

Licenses

Wren is released under the MIT License and is built with Jekyll and a whole host of other MIT licensed projects.

In order to remain compatible with GitHub Pages Wren only uses plugins from the whitelist. Massive props to Remote Theme, Feed, Paginate, and SEO for doing their thing in the background without me needing to worry about it. Further features are achieved through Liquid templates, some of which are based on existing Ruby plugins. These include Reading Time, Embed Video, Tag Cloud.

Style wise, Wren's SASS is forked from Minima which proved crucial in knowing what did and didn't need to be covered by Jekyll themes. The icons (apart from are based on designs from Font Awesome, redrawn for the smaller form factor. Credit also to Antoine Boulanger's guide on SVG Favicons.

The only part of Wren not MIT licensed is the default profile image, a CC-BY-NC licensed photo of a Bewick Wren taken by Minette Layne.