Jekyll

Creating web sites (like this one) on github-pages using Markdown

More on Jekyll

Jekyll

Jekyll is a software package that can be used in conjunction with github.com to publish web pages easily.

The web site you are looking at now is created via Jekyll.

Creating pages

Example of minimal front matter:

---
---

If you want your pages to have an html <title> element, you need to specify at least one default layout (explained below), and the specify this layout along with the title:

---
layout: default
title: Jekyll
---

Nested lists

* First level item 1
 - Second level item a
 - Seond level item b
* First level item 2

In Kramdown, you must indent four spaces to get a second level of list:

* First level item 1
    - Second level item a
    - Second level item b
* First level item 2

Configuration

Layouts

In Jekyll a layout specifies the common features of a category of pages on your site. For example, for a course web site, you might have different layouts for:

Strictly speaking, layouts are optional. It is possible to create a minimally functional site without providing layouts. However, it is recommended to provide at least one default layout. If you don’t, while the pages produced will work in most browsers, pages will not be compliant HTML. For example it is the layout that provides the template for putting in the <head></head> section that contains the page <title></title> element. Thus, without a layout, specifying a title: my title in the front matter will have no effect.

Layouts are created in the _layouts subdirectory of the root of the site repository.

The jekyll documentation provides a good tutorial on creating a default.html layout. This is a good place to start, though your default.html layout can likely be much simpler than the one shown on that site. Here is a much simpler example. Here is some insight into what it contains:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Jekyll</title>
  </head>
  <body id="page-top">
    <h1 id="why-should-i-set-up-continuous-integration-for-a-jekyll-site-on-travis-ci">Why should I set up continuous integration for a <a href="/topics/jekyll/">Jekyll</a> site on Travis-CI</h1>

<p>Setting up a <a href="/topics/jekyll/">Jekyll</a> site on Github Pages is super convenient.</p>

<p>But one thing Github Pages didn’t provide is <em>access to the error messages</em> that you get when your site is set up 
incorrectly.   Instead, you just get a “404 unavailable” message, or your site doesn’t update (your changes don’t 
seem to have any effect.)</p>

<p>The best way to remedy this—in fact its Github Pages own suggestion—is to set up continuous integration for
your Jekyll site via Travis-CI.</p>

<p>Doing so has these advantages:</p>

<ul>
  <li>
    <p>If you are using github pages, you won’t see the error messages if/when the site build is broken.   TravisCI is the
  one of two ways that Github Pages suggests for making these error messages visible.  (The other way is to run Jekyll locally
  on your own machine (setting up the site on localhost:4000).</p>
  </li>
  <li>
    <p>When the site is broken, TravisCI will send you emails until the site is fixed.</p>
  </li>
</ul>

<p>Here’s how to do it:</p>

<ol>
  <li>
    <p>Add a .travis.yml file to the root of your repo, with the following contents:</p>

    <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>language: ruby
rvm:
  - 2.1.7
script: "bundle exec jekyll build"
</code></pre></div>    </div>
  </li>
  <li>
    <p>Make sure this line is in your _config.yml:</p>

    <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>exclude: [vendor]
</code></pre></div>    </div>
  </li>
  <li>
    <p>Visit https://travis-ci.org/ and login with your github.com credentials—the same ones you use to maintain the github repo where the github pages site is stored.</p>
  </li>
</ol>

<p>…</p>

<p>Eventually, the page you’ll visit is the same page as for your github.com repo, except with github.com replaced with travis-ci.org</p>

<p>For example:</p>

<p>For the repo:</p>

<p>https://github.com/ucsd-cse-spis-2016/ucsd-cse-spis-2016.github.io</p>

<p>Access:</p>

<p>https://travis-ci.org/ucsd-cse-spis-2016/ucsd-cse-spis-2016.github.io</p>

  </body>
</html>

Specify default layout in _config.yml

Put this in your _config.yml to specify that default is the default layout for all .md files that don’t specify a different layout. That way, you can just use a minmal front matter that contains only the page title.

defaults:
  -
    scope:
      path: "" # an empty string here means all files in the project
    values:
      layout: "default"

Includes

You can factor out what are sometimes called “partials” in other web frameworks, i.e. something like a #include in C/C++. To do that, you create a directory in the root of the repo called _includes.

The Jekyll documentation contains a tutorial example of doing this, but again it is a bit complex. So, here is a simpler example of creating some common navigation for a site. This provides a link to the root of the site, and a link to the github repo where the site is hosted.

Under _includes, create the file nav.html. This example uses absolute links, but it would be possible to use relative links also.

<nav id="mainNav">
<table border="1" style="width:auto;">
 <tr>
  <td><a href="https://UCSB-CS56-pconrad.github.io">home</a></td>
  <td><a href="https://github.com/UCSB-CS56-pconrad/UCSB-CS56-pconrad.github.io/">github repo</a></td>
 </tr>
</table>
</nav>

Then, edit the _layouts/default.html as shown to include this file:

<body id="page-top">
  <div data-role="header">
 <nav data-role="navbar" data-grid-"d">
  <ul>
   <li><a href="/" class="ui-btn-active">home</a></li>
   <li><a href="https://github.com/pconrad-webapps">pconrad-webapps on Github</a></li>
   <li><a href="https://www.cs.ucsb.edu/~pconrad">P. Conrad home page</a></li>
  </ul>
 </nav>
</div>

  <h1 id="why-should-i-set-up-continuous-integration-for-a-jekyll-site-on-travis-ci">Why should I set up continuous integration for a <a href="/topics/jekyll/">Jekyll</a> site on Travis-CI</h1>

<p>Setting up a <a href="/topics/jekyll/">Jekyll</a> site on Github Pages is super convenient.</p>

<p>But one thing Github Pages didn’t provide is <em>access to the error messages</em> that you get when your site is set up 
incorrectly.   Instead, you just get a “404 unavailable” message, or your site doesn’t update (your changes don’t 
seem to have any effect.)</p>

<p>The best way to remedy this—in fact its Github Pages own suggestion—is to set up continuous integration for
your Jekyll site via Travis-CI.</p>

<p>Doing so has these advantages:</p>

<ul>
  <li>
    <p>If you are using github pages, you won’t see the error messages if/when the site build is broken.   TravisCI is the
  one of two ways that Github Pages suggests for making these error messages visible.  (The other way is to run Jekyll locally
  on your own machine (setting up the site on localhost:4000).</p>
  </li>
  <li>
    <p>When the site is broken, TravisCI will send you emails until the site is fixed.</p>
  </li>
</ul>

<p>Here’s how to do it:</p>

<ol>
  <li>
    <p>Add a .travis.yml file to the root of your repo, with the following contents:</p>

    <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>language: ruby
rvm:
  - 2.1.7
script: "bundle exec jekyll build"
</code></pre></div>    </div>
  </li>
  <li>
    <p>Make sure this line is in your _config.yml:</p>

    <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>exclude: [vendor]
</code></pre></div>    </div>
  </li>
  <li>
    <p>Visit https://travis-ci.org/ and login with your github.com credentials—the same ones you use to maintain the github repo where the github pages site is stored.</p>
  </li>
</ol>

<p>…</p>

<p>Eventually, the page you’ll visit is the same page as for your github.com repo, except with github.com replaced with travis-ci.org</p>

<p>For example:</p>

<p>For the repo:</p>

<p>https://github.com/ucsd-cse-spis-2016/ucsd-cse-spis-2016.github.io</p>

<p>Access:</p>

<p>https://travis-ci.org/ucsd-cse-spis-2016/ucsd-cse-spis-2016.github.io</p>

Dates

Dates in Jekyll are formatted using the “Liquid filter”.

More information is here: https://help.shopify.com/themes/liquid/filters/additional-filters#date

An example is:

12-hour time (%I:%M:%S %p)


<!-- 03:20:07 PM -->

Syntax of Templates

The template used by Jekyll is called Liquid.

The following page summarizes the syntax of things such as if statements, for loops, variable assignment, etc:

https://github.com/Shopify/liquid/wiki/Liquid-for-Designers

Liquid Gotchas

A common problem I run into with using conditions in liquid templates is that you must have space around your operators.

CORRECT: {% if page.textbook == "HFJ" %}

INCORRECT: {% if page.textbook=="HFJ" %}

Fenced code blocks

Fenced code blocks with line numbers

http://stackoverflow.com/questions/25133223/jekyll-fenced-code-blocks-with-line-numbers


<figure class="highlight"><pre><code class="language-python" data-lang="python"><table class="rouge-table"><tbody><tr><td class="gutter gl"><pre class="lineno">1
</pre></td><td class="code"><pre><span class="c1"># code goes here</span>
</pre></td></tr></tbody></table></code></pre></figure>

Enabling LaTeX on a Jekyll Site on Github Pages

TBD

For loops and other control structures (using “liquid syntax”)

See: https://help.shopify.com/themes/liquid/objects

More on Jekyll