Jekyll file structure

Jekyll uses the Liquid ( https://github.com/Shopify/liquid/wiki ) templating language to process templates

Jekyll file starts with a triple dash - - - , to define a Jekyll header

The header part is in Yaml syntax, until closing - - -, then there is the body part

---
layout: post
title: "My Page"
otherVar1: value1
---
<h1>Sample Jekill body file</h1>
my file body text (.md, .html, ...)
goes on several line

... interpreted then by Jekill Liquid template engine
... using
   expanded _layouts/{ { page.layout } }.html layout file
   contextual page header variable  ... example: { { page.title } }
 + contextual parent variable       ... example: { { site.url } } 
 + Liquid tags { %for ...} { %if} ..{ %endif %}{ % endfor %}
...

cf next

The body content is itself evaluated by Jekyll using the Liquid template engine, and passing a contextual list of variables=value.

This context inherits parent context values: page -> parent _config.xml layout fragment -> parent page -> parent _config.xml

Jekyll directory project structure

files and dirs starting with underscores (“_”) are interpreted by Jekyll

typical directory structure:

./_config.yml

./_layouts
./_layouts/default.html
./_layouts/page.html
./_layouts/post.html

./_includes
./_includes/footer.html
./_includes/head.html
./_includes/header.html

./css
./css/main.scss

./_posts
./_posts/2014-10-27-welcome-to-jekyll.markdown
./_posts/2014-10-28-jekyll-edit-markdown-samples.markdown

./assets/image1.png
./assets/image2.png

./data/file1.json
./data/file2.json

./_collection1/file1.json
./_collection1/file2.yaml
./_collection1/file2.csv

./_collection2/file1.json
./_collection2/file2.yaml
./_collection2/file2.csv

./about.md
./index.html
./feed.xml

./.gitignore
./_site/** ... gitignored generated files

Liquid templating engine overview

Liquid https://github.com/Shopify/liquid
defines itself as “ Liquid markup language. Safe, customer facing template language for flexible web apps. http://liquidmarkup.org/”

See documentation : http://docs.shopify.com/themes/liquid-documentation/basics See video http://www.youtube.com/watch?feature=player_embedded&v=tZLTExLukSg (which last 6 minutes only)

It is a kind of text pre-processor in Ruby (like Velocity or ThymLeaf in Java, T4 in C#, Angular expression/directives in JavaScript, etc..)

Like AngularJS, it has a mustach-like syntax for variable, and like Velocity, it has begin-tag / end-tag for macros

A picture is worth a thousands words:

 
<ul id="products">
  {% for product in products %}
   {% if product.enabled %}
    <li>
      <h2>{{ product.name }}</h2>
      Only {{ product.price | price }}
      {{ product.description | prettyprint | paragraph }}
    </li>
   {% endif %}
  {% endfor %}
</ul>

More in details:

  • replaces variables by their value
 {{ variable }}
  • filter expression and format
 {{ variable | filter1 | filter2 | formatter }}
  • execute tag macro
{% macro arg1 arg2.. %}
body text
{% endmacro %}

Tag macro can be developped as plugin and added

  • loops tag
{% for product in products %}
  .. {{ product.name }}
{% endfor %}
  • if tag
{% if product.enabled %}
  .. {{ product.name }}
{% endif %}
  • Include a file content, from _includes/subdir/file
{% include subdir/file %}

( notice: work only with path as variable:

{% include {{pathVar}} %}
  • Include a file content, relative to the current file :
{% include_relative subdir/file %}

Jekyll > Liquid > Pygments : adding code snippets with syntax hilight in Jekyll pages

see http://jekyllrb.com/docs/templates/

Jekyll uses python Pygments librairy: http://pygments.org/

install using

$ sudo apt-get install python-pip
$ sudo pip install Pygments

and also edit your Jekyll _config.yaml to add

highlighter: pygments

Pygments has itself tons of supported lexer for langages: http://pygments.org/languages/

( detailed list: http://pygments.org/docs/lexers/ )

  • Java
{% highlight java %}
public class Foo implements IFoo {
   @Arg(name="test")
   private boolean test;

   public static void main(String[] args) {
   }
}
{% endhighlight java %}
public class Foo implements IFoo {
   @Arg(name="test")
   private boolean test;

   public static void main(String[] args) {
   }
}
  • Ruby (Liquid is itself written in Ruby… so cited here)
{% highlight ruby %}
def foo
  puts 'foo'
end
{% endhighlight ruby %}
def foo
  puts 'foo'
end
  • Xml (with tons of &lt;tag/&gt; for escaping <tag/> in rendered html…)
{% highlight xml %}
<tagA attr="1">
	<tagB/>
	&c;
</tagA>
{% endhighlight %}
<tagA attr="1">
	<tagB/>
	&c;
</tagA>
  • Html (with tons of &lt;tag/&gt; for escaping <tag/> in rendered html…):
{% highlight html %}
<div>
   <A href="mylink.png">lylink.png</A>
</div>
{% endhighlight %}
<div>
   <A href="mylink.png">lylink.png</A>
</div>
  • Liquid
{% highlight liquid %}
{% raw %}

... {%if %} bla bla {{ var }} {% endif %}

{% endraw %}
{% endhighlight %}

This is a Meta-headache : Formating Liquid text to escape from Liquid code… (containing {% raw %} …)

  • Liquid Blog explained in blog … Meta-Meta headache (for Advanced curious developpers only)

Note: You may have noticed that to write it myself in this blog (Meta-Meta-Headake), I should myself double the wrapping with highlight/raw ../endraw/endhighlight !!! But I also had to cheat by adding a space (invisible <span/> in html) between { and % to disable the first endraw that was doubled ! Then finally, I took up the intermediate generated html, copy&pasted it in this blog by wrapping it by raw..endraw !!

{% highlight liquid %}
{% raw %}

{% highlight liquid %}
{% raw %}

... {%if %} bla bla {{ var }} {% endif %}

{<span/>% endraw %} // <== Meta-Meta-Headake : cheating by adding an empty space or span  
{% endhighlight %}

{ % endraw %}
{% endhighlight %}

You may browse the real source page in this Blog github: raw source code… https://github.com/Arnaud-Nauwynck/Arnaud-Nauwynck.github.io/blob/master/_posts/2014-10-28-jekyll-edit-markdown-samples.markdown”