Jasper

Jekyll port of Casper, the Medium-like Ghost default’s theme.

Jasper Screenshot

Demo

Features

Customization


Installation

$ git clone https://github.com/Pym/Jasper.git
$ bundle install
$ bundle exec jekyll serve

Dependency versions :

  • jekyll 3.0.3
  • jekyll-paginate 1.1.0

Match GitHub Pages as of 03/20/2016.

Philosophy

Jasper doesn’t introduce anything new. It’s a DRY port from Casper to Jekyll/Liquid templates.

The main idea is to mimic Casper as much as possible while dealing with Jekyll’s limitations.

Original files from Casper used by Jasper:

.
 └── assets
    ├── css
    │   └── screen.css
    ├── fonts
    │   ├── casper-icons.eot
    │   ├── casper-icons.svg
    │   ├── casper-icons.ttf
    │   └── casper-icons.woff
    └── js
        ├── index.js
        └── jquery.fitvids.js

The only add-on so far is the addition of the GitHub icon – grabbed from GitHub Octicons – to the casper-icons font. This was possible thanks to the IcoMoon App!

Jasper Features

Atom Feed

Jekyll’s default theme has already its RSS 2/Atom feed.xml, but why are they trying so hard? Atom is just a better format.

Let’s KISS with Jasper’s atom.xml, based on this Wikipedia example.

Code Snippet Highlighting

Documentation: Templates - Code Snippet Highlighting (Jekyll)

Made possible with _syntax-highlighting.scss from Jekyll’s default theme.

Covers

Just like the original Casper, you can use covers easily with Jasper too!

A responsive menu, showing from the right and featuring a subscribe button. Easily configurable in _config.yml .

Pagination

Documentation: Pagination (Jekyll)

Customizable pagination system thanks to jekyll-paginate.

Limitations

Pagination only works on the index. This is a limitation of jekyll-paginate. We could use octopress-paginate – which is basically a drop in replacement – but it’s not part of GitHub Pages yet (issue on the subject).

Multiple Authors

Thanks to Jekyll Data Files, Jasper let you add as much authors as you want!

Gravatar Integration

Your Gravatar will be displayed every time your author’s name will show up. Choose it wisely!

Author Page

A page, with author information – name, bio, pictures and links – listing the author’s posts.

The not-so-nice part: you have to create one page for every author.

Disqus Comments

Documentation: JavaScript configuration variables (Disqus)

You must set the disqus variable in _config.yml to turn on that feature.

By default, Disqus comments are visible on every post, you can disable comments for a specific post by adding disable_comments and setting it to true.

---
layout: post
title:  "Welcome to Jekyll!"
categories: jekyll update
author: jasper
disable_comments: true
---

Facebook Open Graph

Documentation: The Open Graph protocol

Facebook metas from header.html:

<meta property="og:url" content="{{ page.url | prepend: site.baseurl | prepend: site.url }}" />
<meta property="og:type" content="article" />
<meta property="og:title" content="{{ title }}" />
<meta property="og:description" content="{{ description }}" />
{% page.image %}<meta property="og:image" content="" />{% endif %}

Twitter Summary Card

Documentation: Summary Card (Twitter)

You must set the twitter variable in _config.yml to turn on that feature.

Twitter metas from header.html:

{% if site.twitter %}
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@{{ site.twitter }}">
<meta name="twitter:title" content="{{ title }}">
<meta name="twitter:description" content="{{ description }}">
{% page.image %}<meta name="twitter:image" content="">{% endif %}
{% endif %}

Jasper Customization

Site Cover

To replace the default cover, which only appears on the index, edit index.html and modify the cover variable:

---
layout: default
cover: /images/covers/jasper.jpg
---

Post Covers

Posts can have covers too!

You just have to add the cover variable and set it to an image path:

---
layout: post
title:  "Welcome to Jekyll!"
categories: jekyll update
author: jasper
cover: /images/covers/welcome.jpg # Header cover [optional]
---

Full Config Example

# _config.yml

# Site settings
title: Jasper
logo: /images/logo.png
description: Jasper National Park, the largest national park in the Canadian Rockies.
baseurl: "/Jasper" # the subpath of your site, e.g. /blog
url: http://pym.me # the base hostname & protocol for your site

# Main header
header:
  text_shadow: 0 0 20px rgba(28, 47, 53, .8) # CSS text-shadow

# Navigation
navigation:
  - slug: /README.html
    label: Jasper

# Services (all are optional)
analytics: UA-1234567-8 # Google Analytics tracking ID
disqus: jasper-theme    # Disqus shortname
facebook_l10n: en_US    # Your locale (en_US, fr_FR, etc.)
twitter: JasperTheme    # Website's Twitter username (without the '@')

# Build settings
exclude: [CNAME, Gemfile, Gemfile.lock]
markdown: kramdown
kramdown:
  input: GFM # Enable GitHub Flavored Markdown

# Plugins
gems: [jekyll-paginate]
paginate: 5 # Post excerpts by page
paginate_path: "/page/:num" # Default was "/page:num/"

Add an Author

This will guide you trough the process of adding an author (or editing the default one).

#1 Open _data/authors.yml and add your author:

jasper: # Author key. Must be the same as the slug (next line)
  slug: jasper # Must be the same as the author key (previous line) [required]
  name: Jasper # Doesn't need an explanation [required] [views: all]
  bio: Hi! I'm Jasper, a National Park and also a Jekyll theme! # Short bio [optional] [views: post, author]
  location: Alberta, Canada # [optional] [views: post, author]
  twitter: JasperTheme # Twitter username (without the '@') [views: post, author]
  github: Pym/Jasper #GitHub username or username/repository (without any '@'!) [optional] [views: post, author]
  gravatar: 2483fd8c9446700e4dc7c2b26c2dd790 # MD5 hash of your Gravatar email [optional (but it's cool)]

#2 Generate Gravatar’s MD5 Hash

To generate the MD5 hash for your author, run this in your terminal:

$ php -r 'echo md5(strtolower(trim("your.author@email.com")));'

#3 Create the corresponding author file

We must name our new author’s page the same way. For our example’s author, jasper is the author key that we defined earlier in _data/authors.yml. So in this this case the file will be author/jasper.html:

---
layout: author
title: Jasper's Posts
author: jasper
---
{% assign posts = site.posts | where: 'author','jasper' %}
{% include loop.html posts=posts %}

Replace every Jasper and jasper occurrences with your own author name and slug… and you are done!

Thanks

TODO

  • [ ] Category/Tag Page: I don’t use those, feel free to work on it if you think it can be usefull! 😄

Contributing

  1. Fork it (https://github.com/Pym/Jasper/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

License

See the LICENSE file.

Fork me on GitHub