Skip to content
This repository

A minimal Jekyll theme utilizing Compass and built from the HTML5 Boilerplate. Many common patterns found in Jekyll sites are implimented here to get you started with your own site in no time. This theme is meant to be easy for you to add your own design, but this is optional. All you have to do is provide your content.

branch: master
README.md
layout
default

Bloggyll

Bloggyll is a minimal Jekyll theme utilizing Compass and built from the HTML5 Boilerplate. Many common patterns found in Jekyll sites are implimented here to get you started with your own site in no time. This theme is meant to be easy for you to add your own design, but this is optional. All you have to do is provide your content.

Flattr this git repo

Features

  • Learn by example with the included posts
  • Category pages
  • Archive page
  • Tag cloud and list page
  • Atom feed
  • Pagination
  • Disqus support
  • Google Analytics support
  • Code highlighting with SyntaxHighlighter
  • Post excerpts
  • Associate files with a post

Themes

This is a list of known themes that derive from the base boilerplate theme. Let me know if you make a public theme and I'll add it to the list.

  • Bauble - A light-hearted and bubbly theme that is loosely reminiscent of the colored glass ornaments (baubles).
  • Shadow Play 1 - Based off the Shadow Play 1 design from HTML5webtemplates.co.uk.
  • War Room - Inspired by the interface to the ficticious game called Global Thermonuclear War from the 1983 film WarGames.

Getting started

Using Bloggyll is relatively simple. In these instructions I refer to the Bloggyll as the template. Also, I assume you have a command line interface or terminal open in the directory where you have placed your copy of the template.

Installing

First you need to install Jekyll.

Next, install Bundler by running the following from your command line:

gem install bundler

Now you can either clone this template or download and extract it to a folder. Preferably name the folder after your website.

Then, from your command line interface, change directories to the folder with this template. Then run the following command:

bundle install

This will install any gems that this template depends on.

Installing with RVM

If you're a Linux or Mac OS X user, you can use RVM to manage your Ruby environments. Bloggyll comes with an .rvmrc that automatically sets up an isolated environment for itself. All you need to do is open a terminal window and change your directory to where you have placed the template.

Viewing the site

Run the following command:

jekyll --serve --auto

Then open up your favorite browser and point it to the url: http://localhost:4000

It's important to note that while Jekyll is running with the option --auto any changes you make to your site will automatically be regenerated for you. The option --serve will start a webserver so you can view your site locally from your browser.

Configuration

In the template's base directory you'll find the file _config.yml. Open this file with your favorite text editor.

Some generic settings for your site are included. You'll want to change these to suit your site. It's okay to comment out any of these settings except for the url and name.

Here's what each setting means:

  • url - Full public url without trailing slash.
  • name - Site name/title.
  • tagline - Site tagline/subtitle.
  • author - Site author (most likely you).
  • email - Site author's email.
  • ga - Google Analytics ID. Put your analytics account id from Google here. Uncomment to activate.
  • disqus - Disqus shortname. Disqus allows you to enable commenting on your site. You need to create an account before you can use this. Uncomment to activate.

The other settings are Jekyll specific and will change how your site gets generated. Refer to Jekyll's configuration documentation if you would like to change these settings.

Writing a post

Posts are kept in the _posts folder.

To create a post, create a file with the pattern:

YEAR-MONTH-DAY-title.MARKUP

Your post's extension should typically be either .markdown or the shorter .md to specify that your post is formatted using Markdown. Markdown is a text format syntax that gets converted to html. You can think of Markdown as similar to wiki text or bbcode, but Markdown's goal is to make both the text and html representations clean and easy to read.

To get started, create a new text file and name it:

2012-01-01-Happy_New_Year.md

Open the text file you just created and add the following text to the top:

---
layout: post
title: Happy New Year!
---

The --- encapsulates your post's metadata, which is formated with YAML. This little bit of information tells Jekyll that we want to use the post layout (found in the _layouts folder) and specify the post's title as Happy New Year!.

After the last ---, the body of your post begins. Since we gave it a .md extension our content will be parsed as Markdown. A Markdown quick reference will help you get started, but for now let's start with something simple like:

---
layout: post
title: Happy New Year!
---

It's the new year!  My new year's resolution is to blog with the Jekyll
using Bloggyll for my website.

Now that your post is created, run jekyll --serve --auto and view your site at http://localhost:4000/. You should find your post on the front page and if you click on the title, you'll notice that the url is something like:

/2012/01/01/Happy_New_Year/

The specific url is determined by Jekyll's permalink configuration.

We can specify other things in the metadata too, like categories and tags. Let's go ahead and change the metadata to:

---
layout: post
title: Happy New Year!
category: Holiday
tags:
    - New year
    - Celebration
    - Party
---

[...]

This will place our post in the category of Holiday and add some tags. This template works best when you specify at least one category per post.

When you specify a category, it changes the post's url. In this case the new url will be:

/Holiday/2012/01/01/Happy_New_Year/

To learn more about how Jekyll uses your page metadata, you can look at Jekyll's documentation on YAML front matter.

Launching your site

Run the following command:

jekyll

Without any options, the jekyll command will generate your site. By default your generated site is created in a folder named _site.

The simplest method to launch your site is to upload the contents of the _site folder to wherever your site is being hosted.

More detailed solutions can be found in Jekyll's documentation on deployment.

Styling

Bloggyll uses Sass and Compass to generate it's CSS. Do not edit the css/style.css file directly.

Sass is a stylesheet that gets converted to CSS. Sass adds features that make styles easier to maintain and develop. If you are new to working with Sass, you should visit the Sass website to familiarize yourself.

Compass is a framework that provides you with a library of common Sass mixins. The Compass reference is a great source of information while styling your site.

To begin styling, you need to first install Compass:

gem install compass

Next, start Compass with the watch command in the template base directory via:

compass watch

Then use your favorite text editor to edit the files in the sass directory.

Here's a brief description of some key files to get you started:

  • style.sass - Includes all the partial Sass scripts for your site. This ensures only one CSS file gets generated to cut down on requests while keeping your styles organized into separate files by function.
  • _base.sass - Includes the libraries required for our Sass scripts and specifies global variables. This comes recommended by Compass as part of their best practices.
  • _layout.sass - Defines the main shape of your site.

License Info

Copyright (c) 2011 Ryan Seto mr.werewolf@gmail.com Licensed under the MIT license (http://www.opensource.org/licenses/mit-license.php)

Contributing

Feel free to fork this project, send me pull requests, and issues through the project's github page.

This project is intended to be forked to create new themes.

Something went wrong with that request. Please try again.