Code Monkey home page Code Monkey logo

wren's Introduction

Wren

Jekyll CI Status CodeFactor Rating Download Count MIT Licensed

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.

wren's People

Contributors

dependabot[bot] avatar foggalong avatar

Stargazers

 avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

wren's Issues

Config Merge on `wren_social_data` with Remote Theme Fails

Describe the bug
The wren_social_data YAML in the theme's config isn't merged into the user's config when they're using Wren through jekyll-remote-theme remotely.

To Reproduce
Steps to reproduce the behaviour:

  1. Set remote theme: jekyll-wren
  2. Remove wren_social_data from _config.yml
  3. Scroll down to footer
  4. See broken social buttons

Expected behaviour
Would expect Jekyll to pick up the wren_social_data YAML from the theme's config so that the user doesn't have to have the data saved in theirs. This happen if using Wren's gem but not when using the theme remotely.

Error Pages Not Included

When the theme is accessed either using the gem or the jekyll-remote-themes the prebuilt error pages don't go with it, meaning pages like 404.html 404. Unsure if this is a technical limitation with Jekyll/gemspecs like _data being inaccessible was

Use alongside existing website

I'd love an option to use Wren alongside an existing website. This would involve:

  • making home button link back to base site
  • moving the blog page to the main page
  • turning the 'about me' page into an 'about this blog' page

Fix SVG Cacheing

The method used to recolour SVGs live is preventing them to cache, meaning they flicker every time a new page is loaded. Need to investigate whether this can be done directly with CSS rather than using HTML's <use>.

Improvements to Meta

The meta include has already been given a spruce up from what it was in stock Minima, but could extra features I'd like to get in:

  • Liquid reading_time which rounds to the nearest minute (rather than down)
    • BUG: in GitHub pages, the reading_time overflows and displays page content
  • Reddit-style 'Last modified at...' title text, rather than appending ~ YYYY-MM-DD

Better Navbar Icons

The current navigation icons are taken from Wren v0.2, themselves taken from various Numix designs which are now 7-8 years old. Reckon I can do a lot better now and it'll give the site a more modern feel. Small filesize should still be prioritised.

As part of this it would also be nice to expand the range of fallback icons beyond just page, e.g. portfolio, videos, etc.

Multiple of any Social Link

It's possible to have multiple GitLab, Mastodon, and extra-links because of the way they're generated, but can only have one link for everything else. Would be cool to enable that behaviour for any of the links

Categories, Tags, and Home

I know that Jekyll has categories and tags natively, but this doesn't seem to be a feature that Minima exposed as a theme. Will have to do some digging as see if/how it could be utilised.

Wren 0.2 had tags, each of which had their own post list pages and RSS feeds, and then the main "all posts" page also had a tag cloud like was seen on a lot of early 2000s blogs. That also means fixing this issue is sufficient to make the final scraps of Wren 0.2 code redundant.

Fixing this will also be an opportunity to shift away from "home" still being referenced as the blogs/posts page in some of the behind the scenes code.

Paginator Implementation

The only big feature from Minima which hasn't been given any attention at all is the support for Paginator. All the CSS and Liquid needed is there, but when I tried switching it on even with stock Minima it just didn't work. Will need some investigation.

Switch from Categories to Tags

Wren uses categories as the labelling system for posts. I've just learned, contrary to documentation I read a couple weeks ago, there are in fact a difference between categories and tags in Jekyll. The big two:

  1. Categories are hierarchical, so if multiple labels are specified latter labels are treated as subsets of the former. Tags on the other hand are structurally flat.
  2. Categories appear in post URLs, tags don't.

The first doesn't affect stock Wren because it's not an exposed feature but the second does; Wren's labels are designed to be fluid over time but as is this will result in a heckin' number of broken links. This could be fixed by specifying the permalink structure in _config.yml but that effectively kills the category hierarchy feature if a user did want to expose it through a plugin.

Only solution I can see is to switch from categories to tags as the exposed labelling feature.

Video Embedding

I've added a Liquid template for video embedding on my own blog but think the feature is useful enough that it should live in stock Wren.

Fallback Icon for Navigation Bar

Unlike with the social link list, it's currently possible to add arbitrary pages to the navigation bar. This is good except there's no fallback icon to go to; thinking "page" and just a default document icon.

Wiki Revamp

All the wiki documentation is entirely outdated, all talking about how to use Wren 0.2 ⚰️ The main sections which need updating are:

  • Explaining how to use Wren with GitHub pages
  • Explaining how to use Wren not on GitHub pages
  • Explanation of some philosophical choices (e.g. no comments)
  • Walkthrough of the Liquid files (since commenting them is messy)
  • Example of how to change the style parameters Wren exposes
  • Update contributing guidelines

Add-Back Minima's Code Inclusions

Minima has files in place to allow the user to include custom HTML in the header, footer, etc without having to modify the main files responsible for them. I initially ripped these out but already can see how they would be useful for me using Wren for more than one project, much less anyone else needing to use it.

Author Lists

I don't see myself ever using this for a multi-user blog, but it should be fairly trivial (famous last words) to add an authors list similar to the categories list in d4ffeb9.

LaTeX over Nav Bar

LaTeX with MathJax appears over the navbar when in mobile mode. Noticed it when looking at the ellipse blog.

Icons Don't Resize with Navbar

There's a setting to resize the navbar like so

$nav-bar-height: 48px !default;

However going larger than 48 will not increase the size of the icons in the navbar accordingly and going lower than 48 will actually start to crop parts of the icons away. My guess is this is to do with the height and width being specified in the <svg element itself but I'm not certain.

TODO: v0.2 Beta

Before I'm happy to start using Wren for my own blog (and others) the following things need completing. When these are done I'll release the beta, v0.2 Bewick.

Bugs

  • Reading time calculator needs integrating
  • Crash if no catagories given with first blog
  • Catagory Cloud doesn't stick to the limits given
  • Catagory is spelt wrong everywhere

Features

  • Switch to included HTML, CSS, XML, & PHP setup
  • Limit recent blogs to 5 items
  • Limit RSS feeds to 25 items

Enhancements

  • Make comments system optional
  • Remove link text decorations
  • Needs testing with another URL
  • Dates still look out of place on recent blogs list
  • Recolour <h4> and <h4.a>
  • Using non-html5 'align' property

Inline Attributes Disable Image Centring

When adding an inline attribute to an image to control its width, as in

![polyyolks]({{ 'path/polyyolks.jpeg' | relative_url}}){: style="max-width: 300px;" }

the automatic centring of the image by markdown is turned off and it aligns to left. This can be fixed by adding display: block; into the style of images as standard (which can be overridden in Wren by using the left or right image class).

Arbitrary Social Links

An anti-feature inherited from Minima is that it's not possible to include either:

  1. arbitrary social links in the footer, for services not covered,
  2. multiple links for one service (except Mastadon and GitLab).

Both these would be nice features to have.

How Do Gemspec

Even if I don't have capacity to package it as a Gem right now, it would be good practice if the repo is vaguely structured such that it could be in future. I think as is now, things like having variables in the _config.yml just directly in site.X rather than site.wren.x could cause problems and similarly with the SASS files just being in _sass.

Also, how do gemspec?

First Published on X

An optional 'first published on' icon feature, see it a lot on blogs that've moved around different hosts. Idea would be a YAML header entry like:

first_published on: Wordpress

which Jekyll then turned into an icon for that service to display as part of meta.html.

Image Improvements

Would be nice to improve images, making it so white images don't blend into the white background, their centring works more reliably (seems #35 isn't the only trigger there), and that alt text also appears as image title text.

Reading Time Wrong

I have no idea why - the code is the same code from before (which worked) just integrated into the main script.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.