layout: post

title: "Jekyll 201: Beyond Hello World"

categories:

- blog

There is [plenty of material][j1] [online showing you][j2] how to

[setup a Jekyll blog][j3], [write your first post][j4] and

[add a custom domain][j5]. But rarely do these tutorials go past

the ["Hello World" stage][j6].

[j1]: http://benhowdle.im/2013/06/02/jekyll-in-15-minutes/

[j2]: http://destroytoday.com/blog/hello-world-im-jekyll/

[j3]: http://danielmcgraw.com/2011/04/14/The-Ultimate-Guide-To-Getting-Started-With-Jekyll-Part-1/

[j4]: http://ianreah.com/2012/12/27/An-introduction-to-Jekyll.html

[j5]: https://help.github.com/articles/setting-up-a-custom-domain-with-pages

[j6]: https://github.com/burkemw3/Heroku-Jekyll-Hello-World

So it's time for Jekyll 201!

I've been using Jekyll for blogs, meetup groups, prototyping, and microsites for

nearly 3 years so I wanted to share some more advanced techniques that aren't

covered in the docs.

The basics of partials (`includes` in Jekyll parlance) are covered in the

docs: [http://jekyllrb.com/docs/templates/#includes](http://jekyllrb.com/docs/templates/#includes)

If you are coming from a traditional web development background, you might want

to know how to pass in data to a partial. Maybe you have some book

recommendations in your sidebar, like so:

{% highlight html %}

<ul id="book-recommendations">

<li class="recommendation">

<img src="/img/pragmatic-programmer.png" />

<a href="http://pragprog.com">Pragmatic Programmer</a>

<span>My favorite book about programming pragmatically</span>

</li>

<li class="recommendation">

<img src="/img/getting-real.png" />

<a href="http://gettingreal.37signals.com">Getting Real</a>

<span>A book about Getting Real and stuff...</span>

</li>

</ul>

{% endhighlight %}

You can make a partial (e.g. `_includes/recommendation.html`) so you aren't

copy-pasting HTML code:

{% highlight html %}{% raw %}

<li class="recommendation">

<img src="{{ img_url }}" />

<a href="{{ url }}">{{ name }}</a>

<span>{{ summary }}</span>

</li>

{% endraw %}{% endhighlight %}

And then use it like so:

{% highlight ruby %}{% raw %}

<ul id="book-recommendations">

{% assign img_url = "/img/pragmatic-programmer.png" %}

{% assign url = "http://pragprog.com" %}

{% assign name = "Pragmatic Programmer" %}

{% assign summary = "My favorite book about programming pragmatically" %}

{% include recommendation.html %}

{% assign img_url = "/img/getting-real.png" %}

{% assign url = "http://gettingreal.37signals.com" %}

{% assign name = "Getting Real" %}

{% assign summary = "A book about Getting Real and stuff..." %}

{% include recommendation.html %}

</ul>

{% endraw %}{% endhighlight %}

We can re-use the HTML template but this is still not so great. Liquid doesn't

have the ability to pass in a hash of local objects (like in Rails), instead we

have to rely on essentially global variables.

A better way to handle the above case of book recommendations is to store the

underlying data in `_config.yml`. This file is typically used to store configuration

options for Jekyll, but any extra YAML data you put in `_config.yml` will be

accessible in templates via the `site` variable.

So the `_config.yml` would look like this:

# General Jekyll Config

auto: true

pygments: true

exclude: [".gitignore", "readme.md", "Gemfile", "Gemfile.lock"]

# Book recommendations

recommendations:

- img_url: /img/pragmatic-programmer.png

url: http://pragprog.com

name: Pragmatic Programmer

summary: |

My favorite book about programming pragmatically

- img_url: /img/getting-real.png

url: http://gettingreal.37signals.com

name: Getting Real

summary: |

A book about Getting Real and stuff...

Caveats: changes to this file are not picked up when running Jekyll locally with

the `--auto` flag, so you need to regenerate the site manually for changes to

take effect (several hours of my life I will never get back).

Make sure all of your data is valid YAML (here is a good [linter][yl]).

Then in your template, you can loop over all the book recommendations.

{% highlight ruby %}{% raw %}

<ul id="book-recommendations">

{% for recommendation in site.recommendations %}

{% include recommendation.html %}

{% endfor %}

</ul>

{% endraw %}{% endhighlight %}

And update the partial to use properties on `recommendation`...

{% highlight html %}{% raw %}

<li class="recommendation">

<img src="{{ recommendation.img_url }}" />

<a href="{{ recommendation.url }}">{{ recommendation.name }}</a>

<span>{{ recommendation.summary }}</span>

</li>

{% endraw %}{% endhighlight %}

Much better! And now, when you want to add a new book, just add it to the list

in `_config.yml` and it will get rendered when you regenerate the site.

I've used this technique several times with success, here are a few examples:

* [Indy Startup Lab][isl]: listing the members and projects, [repo here][islc]

* [Let's Work Happier][lwh]: microsite with app directory, [repo here][lwhc]

Pages have some default attributes that you can set in the [Front-matter][fm];

these include the basics like permalink, title, categories, and tags.

But you are not limited to just these fields. You can add any arbitrary data to

the Front-matter (it is just a block of YAML after all) and they will be exposed

on the `page` variable.

Let's say you write reviews on your blog sometimes and use Amazon Affiliates. Per

the affiliate guidelines, you need a disclaimer on your post stating that you

are participating in the program or the FCC will get mad.

You could copy and paste it to the bottom of each Markdown post &mdash; but a better

way would be to set a custom attribute in the Front Matter.

---

layout: post

title: "My Favorite Gadgets Reviewed"

disclaimer: true

---

By adding `disclaimer` to the Front-matter, we can use `page.disclaimer` in the

`post` layout to display our affiliate text at the bottom of the post when

necessary.

{% highlight html %}{% raw %}

{% if page.disclaimer %}

<div class="disclaimer">

<p>

Disclaimer: Matt Swanson is a participant in the Amazon Services LLC

Associates Program, an affiliate advertising program designed to provide

a means for sites to earn advertising fees by advertising and linking

to amazon.com

</p>

</div>

{% endif %}

{% endraw %}{% endhighlight %}

This technique is pretty powerful, here a few other ideas you can use it for:

* [Author attribution][aa]: useful for multiple author blogs/sites

* Enable/disable Disqus/LiveFyre comments on a per-post basis

* Add summary, subtitles, per-post header images

* Display a banner for your new startup at the bottom of posts

A little trick I picked up from the [DevelopmentSeed blog][ds] &mdash; you can use

`includes` to concatenate your CSS files.

Move your CSS files into the `_includes` folder (I like to put them in a `css`

sub-folder). Then make an `all.css` file with an empty Front Matter, here is the

one from the blog you are currently reading.

{% raw %}

---

---

{% include css/font-awesome.css %}

{% include css/base.css %}

{% include css/skeleton.css %}

{% include css/screen.css %}

{% include css/layout.css %}

{% include css/syntax.css %}

{% endraw %}

Voilà! Six asset requests down to one!

The new Jekyll docs have a great section on [writing plugins][plugin] with several

examples so I won't dive into it here.

Be warned &mdash; you cannot use custom plugins with GitHub pages. I am of the opinion

that GitHub pages is a huge benefit to using Jekyll, so be careful about relying

on plugins.

Often times you can reproduce the functionality with Javascript or a Modular

Component (see below). Personally, whenever I reach for a custom plugin I step

back and evaluate whether I really need the functionality at all &mdash; usually the

answer is no.

Static sites, by design, are very limited. In a world where you can build an

entire business on a WordPress blog, Jekyll seems very simplistic.

For the most part, I think this is good &mdash; I believe in putting the emphasis back

on content. But there are times when you miss some of the conveniences of heavier

content platforms.

You can add some of this functionality back by using Modular Components. The

basic concept is to write smaller services that your blog can interact with. By

offloading the backend work to other apps you can get around some of the limits

of a static site.

The most discussed example is using a 3rd party comment system &mdash; so I will skip

that. Two other use cases that I think are more interesting are an email form

and a web-based post editor.

For the email form, I created a simple [Ruby app][mailer] that accepts

cross-domain POSTs and sends emails to the officer list for a local meetup. The

Jekyll site just serves up the form with the action pointing to the mailer

app. Not perfect, but certainly better than setting up a whole CMS.

[Prose][prose] is an app that allows you to edit and create posts on GitHub

pages with a web interface by connecting to the GitHub API. I personally still

stick with the command line and SublimeText for writing my posts, but those of

you that miss having a WYSIWYG web editor for your content should check out

Prose.

Are there more Jekyll topics you want to see covered? Hit me up on

[Twitter](https://twitter.com/_swanson).

[fm]: http://jekyllrb.com/docs/frontmatter/

[plugin]: http://jekyllrb.com/docs/plugins/

[isl]: http://indystartuplab.org

[islc]: https://github.com/IndyStartupLab/indystartuplab.org

[lwh]: http://letsworkhappier.com

[lwhc]: https://github.com/sep/letsworkhappier.com

[aa]: http://www.lostdecadegames.com/blog-author-attribution-using-jekyll/

[yl]: http://yamllint.com/

[ds]: http://developmentseed.org/blog/2011/09/09/jekyll-github-pages/

[mailer]: https://github.com/indy-software-artisans/jekyll-mailer

[prose]: http://developmentseed.org/blog/2012/june/25/prose-a-content-editor-for-github/