Project Showcase with YAML and Liquid

When I remade my website with Jekyll last week, I made a project showcase page (check it out in the sidebar!). In under twenty lines of code, I built a system for programmatically display a list of projects with descriptions, and look nice doing it.


Jekyll uses YAML, a human readable data format like JSON, for configuration. My system reads the data to display from a file projects.yml, stored in _data/.

The syntax is pretty self explanatory:

- name: "Project 1"
  description: "A short description"

- name: "Project 2"
  description: "
  Descriptions can span
  several lines and
  include <b>HTML</b>
  prize: "Best Example of YAML"


Jekyll also uses Liquid Templating for compile-time HTML generation, allowing for some pretty powerful stuff. I use GitHub Pages for hosting, which means on every push, the project page (and everything, really) is regenerated.

Liquid Templates provides conditional logic through the {% %} tags, and text-resolving markup with the {{ }} tags.

The relevant source for the page in question:

{% for project in %}
	<div class="box css3-shadow">
		{% if project.image %}
			<a href="{{project.url}}">
				<img class="image-rounded" src="{{project.image}}">
		{% endif %}
		<h3><a href="{{project.url}}">{{}}</a></h3>
		{% if project.prize %}
			<br><i class="fa fa-trophy fa-lg"></i> {{project.prize}}
		{% endif %}
{% endfor %}

For each entry in the YAML file, I make a div (styled with the first CSS I found – I’m not great at CSS). If we defined an image, insert that image, linking to the URL. A title linking to the URL and the description follow. If a prize was defined, display a Font-Awesome trophy icon followed by the text.