My first Jekyll site

10 min. read

Caution! This article is 10 years old. It may be obsolete or show old techniques. It may also still be relevant, and you may find it useful! So it has been marked as deprecated, just in case.

Update (2014-08-05): There is a new post on Smashing Magazine about how to create a blog with Jekyll that is very handy if you never made a site with Jekyll before.

My first Jekyll site is very simple. Is the dedicated website of my project Particle physics snippets, where I'll be uploading code snippets that I used from time to time when I was working in research.

The purpose of the site is to explain what the code is about. I also want to explain the physics behind the instructions, for which a README file is just not enough. I love images and structured text, and I also think it is more didactic and educational to present the information that way.

Check out the portfolio post.

The _includes folder

For this site I stored the contents of the head tag in a file inside the _includes folder. You can see that I used html5 boilerplate as a start, and removed anything I didn't need.

  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">

  <title>{% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %}</title>

  <meta name="description" content="{% if page.description %}{{ page.description }}{% else %}{{ site.description }}{% endif %}">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
  <link rel="apple-touch-icon-precomposed" href="apple-touch-icon-precomposed.png">

  <link href=",300italic,700,700italic" rel="stylesheet" type="text/css">
  <link href="" rel="stylesheet" type="text/css">
  <link rel="stylesheet" href="{{ '/css/main.css' | prepend: site.baseurl }}">
  <script async src="{{ '/js/vendor/pf107-r-m262.min.js' | prepend: site.baseurl }}"><<script>

  <link rel="canonical" href="{{ page.url | replace:'index.html','' | prepend: site.baseurl | prepend: site.url }}">

Then, I placed the navigation in a different file, which is very similar to the default site generated by Jekyll when you first run jekyll new <sitename>. The menu is responsive with only CSS. All the icons are in SVG format. I am trying to find some basic structure that I could use in future Jekyll projects as well.

<!--[if lt IE 7]>
  <p class="browsehappy">You are using an <strong>outdated</strong> browser. Please <a href="">upgrade your browser</a> to improve your experience.</p>

<nav role="navigation" class="zigzag">
  <a href="#" class="menu-icon">
    <img src="{{ site.baseurl }}/img/hamburger.svg" width="18" height="15" alt="Hamburger icon">

  <ul class="navigation">
    <li><a href="{{ site.baseurl }}/">Home</a> <span>|</span> </li>
{% for page in site.pages %}{% if page.menuname %}
    <li><a href="{{ page.url | prepend: site.baseurl }}">{{ page.menuname }}</a> <span>|</span> </li>
{% endif %}{% endfor %}

Another file in this folder is the footer, where I load the prismjs and MathJax JavaScript files, but only if they are used in the page. MathJax is used to show math equations and prismjs is Lea Verou's syntax highlighter.

<div class="wrapper">
  <p class="footnote"><a href="">Particle Physics Snippets</a> site is coded and maintained by M. E. Stevens. <br />
  You can also find the code on <a href="">BitBucket</a> and <a href="">GitLab</a>.</p>
{% if page.prism %}
<script src="{{ site.baseurl }}/js/vendor/prism.js"></script>{% endif %}{% if page.mathjax %}
<script async src=""></script>{% endif %}
{% include stats.html %}

To check this I make use of the YAML Front Matter variables in the top of each page. If the page has code in it that must be highlighted, I add prism: true in the Front Matter. Same if the page uses MathJax. For example, the page about dosimetry includes both:

layout: default
title: Stopping Power Simulation
menuname: Dosimetry
description: Explanation of the physics behind this macro that calculates the stopping power of a particle entering a material.
permalink: /dosimetry/
prism: true
mathjax: true

Layouts folder

I kept it simple and used only one layout, default.html:

<!DOCTYPE html>
<!--[if lt IE 7]>	   <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]>		   <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]>		   <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]-->

{% include head.html %}


{% include header.html %}

{{ content }}

{% include footer.html %}



It's very basic as well. In the _config.yml file, I use the exclude command to prevent certain files from appearing on the final generated site. I also define custom variables to store repeated stuff like social media urls. Their values can then be retrieved by using the liquid syntax {% site.varname %}

In the Front Matter of my pages, I use permalink: /name/ in order to strip the .html extension from the URL. This generates a folder called name with the HTML file inside it. It's one of those Jekyll things that is not very elegant, but you have to live with it. This can be avoided if, instead of hosting the site on GitHub, you hosted it in a server that allowed you to use an .htaccess file with the relevant configurations.

For some Greek letters, I used HTML entities, for the equations I used MathML. Internet Explorer and Google Chrome can't read it, which is the reason why I have to make an extra http request to load the MathJax javascript library. Sorry, mobile phone users :-(

I really see no point in writing vendor prefixes or keeping up to date with them, so I just dropped Lea Verou's fantastic prefix-free JavaScript library in. She is also the author of prismjs. However, this two files can not be concatenated if you want to use async loading, since prismjs won't work in async mode and needs to be loaded alone at the end of the page.

Apart from that, I went through my typical testing work-flow: syntax, performance, image optimization, responsiveness, SEO, usability, analytics/stats, etc.

To do

If I ever stop being a busy bee in the future, I'd like to try some things:

  • Load MathJax only if the browser does not support MathML (and hope the browser doesn't lie).
  • If you use only MathML, the size of the numerator and denominator in fractions can be increased with CSS. But the moment you throw MathJax in, you have no more control over that. They look very small with MathJax, so I'll have to find the time to search some solution to this.
  • Check that the site is truly accessible.

Or you can give it a try. You can find the code at GitHub.