GitHub Pages, Jekyll and Liquid on Much Ado About IT

Alternate static site generators to Jekyll

Julian Knight — Sun, 07 Jan 2018 22:00:00 +0000

Jekyll is built on Ruby which is a pain to work with on Windows. It also doesn't match my chosen development language of JavaScript. Here are some possible alternatives to Jekyll along with some strengths and weaknesses.

GoLang Based

Hugo - By far the best I’ve found out of all possibilities. Although I don’t know Go, with Hugo, I only need to know a few basics and I don’t need to install it.
- ✅ Can use YAML configuration and Front Matter like Jekyll does. (TOML also supported)
- ✅ Simple initial set-up. A single executable is everything required. Although Hugo is based on GoLang, it is packaged into a single executable for those who don’t want or need to mess with Go itself.
- ✅ Being able to easily run the build locally means full access to any error messages.
- ✅ Executable has a development server built in.
- ✅ Supported by a number of free, cloud-based deployment and CMS tools such as Netlify and Forestry.IO.
- ✅ Easily handles both page- and post-based sites and combinations of both.
- ✅ Active and helpful online community, regular updates.
- ✅ Lots of automation hooks available such as multiple output types for generating alternative forms of data.
- ✅ Simple integration of data-driven outputs.
- ✅ Relatively simple to generate new themes. I built a new theme from scratch in less than a week of casual, out-of-hours writing.
- ❌ Logic and flow can be complex to comprehend and reason about. Usually takes several readings of the documentation to work out how to do things if it isn’t immediately obvious.
- ❌ Use of GoLang as the underlying code language results in distinctly non-standard structures for templates.
- ❌ Some of the built-in templates and shortcodes are hard to understand without digging through the Hugo source code as they are poorly documented.
- ❌ The speed of change of Hugo can result in documentation lagging behind the actual code. (Generally, the key contributors do a good job of keeping up though).

Node.JS Based

All of this list use Node.JS to underpin the generation of static pages.

Hexo - seemed promising at first sight. But a quick dig through the impressive list of addins reveals many of them to be out of date or not working properly.
- ✅ Uses YAML configuration and Front Matter like Jekyll does.
- ✅ Large list of plugins, all published on NPM.
- ✅ Simple initial set-up.
- ❌ Many plugins out-of-date or not fully working.
- ❌ Many plugins very poorly documented or documented in Chinese.
- ❌ Does not handle page-based sites well. Focussed on blogging (posts).
- ❌ Needs plugins to provide more rounded capabilities.
Gatsby - Complex but comprehensive
- ✅ Large list of plugins published on NPM & GitHub.
- ✅ Large number of contributors.
- ✅ Powerful.
- ❌ Complex to configure, lots of moving parts.
- ❌ An awful lot of “magic” happens! While the file system is reasonably well arranged it is very hard to reason about the logic.

Jekyll default variables

Julian Knight — Fri, 05 Jan 2018 22:00:00 +0000

These are the default attributes (variables) that you get with each part of the Jekyll domain.

Front Matter

Front matter is a simple YAML-based specification for adding metadata to Jekyll files. You can add it to pages, posts and collections. It goes at the top of the file between two lines containing ---.

There are some standard front matter attributes:

layout If set, this specifies the layout file to use. Use the layout file name without the file extension. Layout files must be placed in the _layouts directory.

Using null will produce a file without using a layout file. However this is overridden if the file is a post/document and has a layout defined in the front matter defaults. Starting from version 3.5.0, using none in a post/document will produce a file without using a layout file regardless of front matter defaults. Using none in a page, however, will cause Jekyll to attempt to use a layout named “none”.
permalink If you need your processed blog post URLs to be something other than the site-wide style (default /year/month/day/title.html), then you can set this variable and it will be used as the final URL.
published Set to false if you don’t want a specific post to show up when the site is generated.
date A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts. A date is specified in the format YYYY-MM-DD HH:MM:SS +/-TTTT; hours, minutes, seconds, and timezone offset are optional.
category, categories Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a YAML list or a space-separated string.
tags Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a space-separated string.
title While not specifically a standard, many templates make use of page/post titles
description While not specifically a standard, many templates make use of page/post descriptions. Start the description value with “> " to enable multi-line text, indent the multi-line text.

Global Variables

site Site wide information + configuration settings from _config.yml. See below for details.
page Page specific information + the YAML front matter. Custom variables set via the YAML Front Matter will be available here. See below for details.
layout Layout specific information + the YAML front matter. Custom variables set via the YAML Front Matter in layouts will be available here.
content In layout files, the rendered content of the Post or Page being wrapped. Not defined in Post or Page files.
paginator When the paginate configuration option is set, this variable becomes available for use. See Pagination for details.

site.xxxx Variables

site.categories.[CATEGORY] The list of all Posts in category [CATEGORY].
site.collections A list of all the collections.
site.data A list containing the data loaded from the YAML files located in the _data directory.
site.documents An array of all the documents in every collection. Each entry contains the page. properties for the document. To get a list of all collection documents and pages: {{ site.pages | concat: site.documents }}
site.html_files A subset of site.static_files listing those which end in .html.
site.html_pages A subset of site.pages listing those which end in .html.
site.pages An array of all Pages. Each entry contains the page. properties for the page
site.posts A reverse chronological list of all Posts.
site.related_posts If the page being processed is a Post, this contains a list of up to ten related Posts. By default, these are the ten most recent posts. For high quality but slow to compute results, run the jekyll command with the –lsi (latent semantic indexing) option. Also note GitHub Pages does not support the lsi option when generating sites.
site.static_files A list of all static files (i.e. files not processed by Jekyll’s converters or the Liquid renderer). Each file has three properties: path, modified_time and extname.
site.tags.[TAG] The list of all Posts with tag [TAG].
site.time The current time (when you run the jekyll command).
site.url Contains the url of your site as it is configured in the _config.yml. For example, if you have url: http://mysite.com in your configuration file, then it will be accessible in Liquid as site.url. For the development environment there is an exception, if you are running jekyll serve in a development environment site.url will be set to the value of host, port, and SSL-related options. This defaults to url: http://localhost:4000.
site.[CONFIGURATION_DATA] All the variables set via the command line and your _config.yml are available through the site variable. For example, if you have foo: bar in your configuration file, then it will be accessible in Liquid as site.foo. Jekyll does not parse changes to _config.yml in watch mode, you must restart Jekyll to see changes to variables.

site.documents and site.pages

Both of these are arrays of objects. The objects contain the following properties.

categories
collection
comments

page.xxxx Variables

page.content The content of the Page, rendered or un-rendered depending upon what Liquid is being processed and what page is.
page.title The title of the Page (if set)
page.excerpt The un-rendered excerpt of the Page.
page.url The URL of the Post without the domain, but with a leading slash, e.g. /2008/12/14/my-post.html
page.date The Date assigned to the Post. This can be overridden in a Post’s front matter by specifying a new date/time in the format YYYY-MM-DD HH:MM:SS (assuming UTC), or YYYY-MM-DD HH:MM:SS +/-TTTT (to specify a time zone using an offset from UTC. e.g. 2008-12-14 10:30:00 +0900).
page.id An identifier unique to a document in a Collection or a Post (useful in RSS feeds). e.g. /2008/12/14/my-post /my-collection/my-document
page.categories The list of categories to which this post belongs. Categories are derived from the directory structure above the _posts directory. For example, a post at /work/code/_posts/2008-12-24-closures.md would have this field set to [‘work’, ‘code’]. These can also be specified in the YAML Front Matter. Available to collection documents but not to Pages(?).
page.tags The list of tags to which this post belongs. These can be specified in the YAML Front Matter.
page.path The path to the raw post, page or collection document. Example usage: Linking back to the page or post’s source on GitHub. This can be overridden in the YAML Front Matter.
page.next The next post relative to the position of the current post in site.posts. Returns nil for the last entry.
page.previous The previous post relative to the position of the current post in site.posts. Returns nil for the first entry.

These are not described in the Jekyll docs section on Pages but are certainly available

dir - Only available to pages, not to collection documents.
name - Only available to pages, not to collection documents. Source name of document.

Posts

categories
tags
content
date
dir
draft?
excerpt
excerpt_separator
id
next previous
path
title
url

Collection document variables

page.categories
page.collection
page.comments
page.content
page.draft
page.excerpt
page.id
page.layout
page.next
page.output - rendered output of collection document
page.path
page.previous
page.relative_path
url
layout

Collections variables (site.collections.xxxx)

Files

Files can be accessed via site.static_files. They are typically kept in the assets folder.

path - The relative path to the file, e.g. /assets/img/image.jpg
modified_time - The Time the file was last modified, e.g. 2016-04-01 16:35:26 +0200
name - The string name of the file e.g. image.jpg for image.jpg
basename - The string basename of the file e.g. image for image.jpg
extname - The extension name for the file, e.g. .jpg for image.jpg

While front-matter variables can’t be added directly to files, they can be made accessible via the defaults section of _config.yml.

Includes files variable

When using the _includes folder, any include files that allow parameters gain an include object variable.

The object will contain a key for each variable passed as a parameter in the calling page.

Example - in the calling page: {% include note.html content="This is my sample note." %} and in the include page: {{ include.content }}

If you need to send the contents of Jekyll/Liquid variables to the included page, you can do so directly. For example: {% include note.html title=page.title %} - note the lack of quotes.

Github Metadata (site.github.xxxx)

versions object containing version numbers for Jekyll, Ruby and other plugins (e.g. keys: jekyll, kramdown, liquid, maruku, rdiscount, redcarpet, RedCloth, jemoji, jekyll-mentions, jekyll-redirect-from, jekyll-sitemap, github-pages, ruby)
hostname “github.com”

pages_hostname: "github.io",
api_url: "https://api.github.com",
help_url: "https://help.github.com",
environment: "dotcom",
pages_env: "dotcom",
public_repositories: [ Repository Objects ],
organization_members: [ User Objects ],
build_revision: "cbd866ebf142088896cbe71422b949de7f864bce",
project_title: "metadata-example",
project_tagline: "A GitHub Pages site to showcase repository metadata",
owner_name: "github",
owner_url: "https://github.com/github",
owner_gravatar_url: "https://github.com/github.png",
repository_url: "https://github.com/github/metadata-example",
repository_nwo: "github/metadata-example",
repository_name: "metadata-example",
zip_url: "https://github.com/github/metadata-example/zipball/gh-pages",
tar_url: "https://github.com/github/metadata-example/tarball/gh-pages",
clone_url: "https://github.com/github/metadata-example.git",
releases_url: "https://github.com/github/metadata-example/releases",
issues_url: "https://github.com/github/metadata-example/issues",
wiki_url: "https://github.com/github/metadata-example/wiki",
language: null,
is_user_page: false,
is_project_page: true,
show_downloads: true,
url: "http://username.github.io/metadata-example", // (or the CNAME)
baseurl: "/metadata-example",
contributors: [ User Objects ],
releases: [ Release Objects ],
latest_release: [ Release Object ],
private: false,
license:
 key: "mit",
 name: "MIT License",
 spdx_id: "MIT",
 url: "https://api.github.com/licenses/mit"
source:
 branch: "gh-pages",
 path: "/"

defaults:
 - scope:
 path: "assets/img"
 values:
 image: true

List of problems and issues with Jekyll and GitHub Pages

Julian Knight — Fri, 05 Jan 2018 17:05:00 +0000

While sites generated using GitHub pages can use Jekyll to enhance them, there are some limitations and, it seems, a number of problems.

Advantages (not matched by alternatives)

The Jekyll build process runs on the GitHub back end, no need for the horrible (on Windows anyway) installation of Ruby and Jekyll. (UPDATE: See Hugo alternative for a better alternative).
GitHub provides an existing set of data about the owning organisation/person and their repos.

Sorry, can’t think of any others that aren’t matched by alternative tools.

GitHub Pages Issues

Build failures generate error messages that are worse than useless. Often not even identifying the page that the build failed on.

Hint: Connect the repo to cloundcannon.com - it will do builds and give more detailed error messages.
Looks like there may be some issues when creating pages directly from the GitHub web interface. I’ve managed to create several pages that show inconsistent metadata - I suspect they were all created via the web interface first. See Issue #6661 and this test page. You can see that the test page is not able to reference its frontmatter metadata.
Jekyll uses Kramdown to render markdown files. This does not quite match the default GFM format. While this is improving, the version used is typically behind the current one, often by a fair margin.

Minima Theme Issues

While the Minima theme is pretty good, it has a few issues of its own.

The documentation states that all you need to do to enable Disqus is to add your shortcode to _config.yml. However, this is not quite correct as Disqus in only added to posts and not to pages or collection documents, nor to the home page.
The main menu does not work quite as expected. If a page doesn’t have a title, it is ignored, not terribly safe an assumption since an xml document might have a title but shouldn’t be shown or perhaps a page needed in the menu doesn’t have/need a title. Also, it excludes collection documents which isn’t too helpful if trying to switch to collections for better content management. A better selection would be {%raw%}site.pages | concat: site.documents | where: "layout","page"{%endraw%} or something similar.

Jekyll Issues

This list is about Jekyll failings, not specific to GitHub Pages.

The sort filter does not work correctly. I have some code that includes {% for item in collection | sort: "title" %} but several entries are incorrectly sorted.
Jekyll documentation is, in my opinion, poor. Information is badly spread between pages. For example, trying to find a comprehensive list of variable filters that actually work with Jekyll is difficult. Some documentation is left up to the core documentation of the Liquid templating engine. However, while that is comprehensive, it applies to the use of Liquid in its original environment, not everything works in Jekyll.
There are too many inconsistent differences between different parts of Jekyll. For example, why are there so many differences in the schema definitions for Pages, Posts and Collection Documents?
In the page object, not all properties are set as one might expect. page.date for example is not set unless you create it manually in the frontmatter. Again, not all page properties actually apply to “Pages”, some only apply to posts or collection documents. Highly confusing.
In variable filters, the : is an unnecessary source of bugs. It serves no real purpose, a simple space would be sufficient.

How to generate a list of collection documents

Julian Knight — Fri, 05 Jan 2018 17:00:00 +0000

The following code automatically generates a list of collection documents. It assumes that the collection uses `output: true` and optionally includes a collection title and description defined in the `_config.yml` configuration file.

collection_doc_lister.html include file

Create this as a file in your _includes folder

{% assign colName = include.collection %}
{% assign col = site.collections | where: 'label',colName | first %}

<div class="collection-list">
{% if col %}

 {% assign collection = site[col.label] %}
 {% assign colTitle = col.title | default: colName | replace: '_',' ' | replace: '-', ' ' | capitalize %}

 <h2><a href="{{ colName | prefix: '/' | append: '/' }}">{{ colTitle }}</a></h2>

 {% if col.description %}<p>{{ col.description }}</p>{% endif %}

 <div>
 <ul>
 {% for item in collection | sort: "title" %}
 <li>
 {% assign mytitle = item.title | default: item.url %}
 <a href="{{ item.url }}">{{ mytitle | replace:'_',' ' | replace:'-',' ' }}</a> {% if item.date %}({{ item.date | date: "%Y-%m-%d %H:%M" }}){% endif %}
 <p>{% if item.description %}
 {{ item.description }}
 {% else %}
 {{ item.excerpt | strip_html }}
 {% endif %}</p>
 </li>
 {% endfor %}
 </ul>
 </div>

{% else %}

 <p>There is no site collection called <code>{{ colName }}</code>.</p>

{% endif %}
</div>

Using the include file

To use, place the following code wherever you want a list of the output files - such as the index.md for the collection folder.

{% include collection_doc_lister.html collection='github-pages' %}

Note the reference to the collection name which is passed to the include file.

How to generate a list of pages in a given folder

Julian Knight — Fri, 05 Jan 2018 17:00:00 +0000

The following code automatically generates a list of pages that exist in a given folder.

page_lister.html include file

Create this as a file in your _includes folder

{% assign dir = include.dir | default: page.dir %}
<div class="page-list">
{% assign mypages = site.pages | where:"dir", dir | where_exp:"item", "item.name != page.name" %}
{% if mypages.length > 0 %}
 <ul>
 {% for item in mypages | sort: "title" %}
 {% assign mytitle = item.title | default: item.url %}
 <li>
 <a href="{{ item.url }}">{{ mytitle | replace:'_',' ' | replace:'-',' ' }}</a>
 <p>{% if item.description %}
 {{ item.description }}
 {% else %}
 {{ item.excerpt | strip_html }}
 {% endif %}</p>
 </li>
 {% endfor %}
 </ul>
{% else %}
 <p>No pages found in folder <code>{{ dir }}</code>.</p>
{% endif %}
</div>

Using the include file

To use, place the following code wherever you want a list of the output files - such as the index.md for the collection folder.

{% include page_lister.html dir="/vscode/" %}

Note the reference to the folder directory name (with leading/trailing slashes as per the .dir attribute) which is passed to the include file.

Jekyll and Liquid reference information

Julian Knight — Thu, 04 Jan 2018 22:00:00 +0000

Some reference sites and links for Jekyll and Liquid.

Reference, help and tips

Jekyll Official Documentation
Jekyll Discussion Groups
Liquid Reference on GitHub
Liquid Reference - the official documentation for Liquid which is used by Jekyll
CloudCannon Academy - getting started with Jekyll
Jekyll Codex - General information plus snippets that require not plugins (useful for GitHub Pages).
Jekyll & Liquid Cheatsheet - “A list of the most common functionalities in Jekyll”

Cloud services

CloudCannon - Build and host Jekyll websites Free for test sites with GitHub and Dropbox source syncing. Can use this to do the donkey work of compiling the static site which can then be hosted anywhere. More options than GitHub Pages.

Interesting Themes

Tactile - Not perfect but I like the dark themed syntax highlighting.
Minima - GitHub supported, seems to be about the most popular.

Jekyll/Liquid Tags

Julian Knight — Thu, 04 Jan 2018 17:00:00 +0000

This is a list of `tags` that can be used in Jekyll.

Tags appear within {% tagname %} markup. Matching end-tags are shown in brackets.

GitHub pages use Jekyll which in turn uses Liquid. See also the official tags reference.

Control flow tags

case (when, else, endcase) - a switch statement
if (else, elsif, endif) - execute block only if the condition is met

Note the odd spelling of elsif (e.g. no second e)

Conditional tests support and and or to link conditions together e.g. {% if line_item.grams > 20000 and customer_address.city == 'Ottawa' %}
raw (endraw) - stops Liquid from parsing the content so that you can include double braces for example.
unless (endunless) - execute block only if the condition is not met

Iteration tags

cycle - must be used in a for-loop. Cycles through the parameters e.g. {% cycle 'a', 'b' %} {% cycle 'a', 'b' %} {% cycle 'a', 'b' %} #=> a b a

Can also specify a group name - see the documentation for more complex examples.
for (endfor, else, break, continue) - basic loop.

For-loop parameters:
- Limit the iterations using the limit parameter e.g. {% for item in numbers limit:2 %} {{ item }} {% endfor %}
- Use the offset parameter to start at a particular index.
- Use the range parameter to create a number range to loop over, range numbers can be variables. e.g. {% for i in (1..100) %} {{ i }} {% endfor %}
- Use the reversed parameter to reverse the order of the loop
  
  For-loop variables - in a for-loop, we get the forloop object (ref):
- forloop.first/last - true when the loop is at the first/last iteration
- forloop.index/index0 - 1/0-based index number for the current iteration
- forloop.rindex/rindex0 - 1/0-based reverse index number for the current iteration
- forloop.length - the length of the array being looped over
tablerow (endtablerow) - Generate rows for an HTML table.

Includes parameters: cols (defines the number of columns), limit, offset, range, first, col, col_first and others. See the documentation for details

Theme/rendering tags

comment (endcomment)
form
include
include_relative
javascript
layout
paginate
raw (endraw) - temporarily disables tag processing. Useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax.
schema
section
stylesheet
highlight - render a code block with syntax highlighting, optional line numbers. Note that filters are processed inside code blocks so wrap the block with and endraw tags if it contains curly braces. To find the appropriate identifier to use for the language you want to highlight, look for the “short name” on the Rouge wiki or the Pygments’ Lexers page.
link - create an html link to another page in the Jekyll site. WARNING: MUST CONTAIN A VALID SOURCE DOCUMENT NAME including folder and source extension otherwise the Jekyll build fails - on GitHub an immensely unhelpful generic error message is produced that does not allow you to identify the document causing the issue.

Variable tags

assign - Assign a value to a variable. e.g. {% assign name = 'freestyle' %}
capture (endcapture) - Combine a number of outputs and assign to a variable. e.g. {% capture attribute_name %}{{ item.title | handleize }}-{{ i }}-color{% endcapture %}
decrement
increment

Jekyll/Liquid Variable Filters

Julian Knight — Wed, 03 Jan 2018 17:00:00 +0000

A comprehensive list of filters available to modify/format Jekyll variables.

GitHub pages use Jekyll which in turn uses Liquid.

Liquid provides the variable filters that can be used to amend/format the variable for output.

This is a more comprehensive list than you will find in most places, it is combined from multiple lists including the source documentation. For more details on these filters, see the official filter documentation.

abs - absolute value
absolute_url - Prepend the url and baseurl value to the input. e.g. {{ "/assets/style.css" | absolute_url }} #=> http://example.com/my-baseurl/assets/style.css
append - append a string e.g. {{ 'foo' | append:'bar' }} #=> 'foobar'
array_to_sentence_string - Convert an array into a sentence. Useful for listing tags. Optional argument for connector. e.g. {{ page.tags | array_to_sentence_string: 'or' }} #=> foo, bar, or baz
capitalize - capitalize words in the input sentence
ceil - rounds a number up to the nearest integer, e.g. {{ 4.6 | ceil }} #=> 5
compact - Remove nils within an array provide optional property with which to check for nil.
concat - Concatenates (combines) an array with another array
cgi_escape - Replaces any special characters with appropriate %XX replacements. CGI escape normally replaces a space with a plus + sign.

date - reformat a date (syntax reference)

Reformat a date using Ruby’s core Time#strftime( string ) -> string

%a - The abbreviated weekday name (``Sun'')
%A - The full weekday name (``Sunday'')
%b - The abbreviated month name (``Jan'')
%B - The full month name (``January'')
%c - The preferred local date and time representation
%d - Day of the month (01..31)
%H - Hour of the day, 24-hour clock (00..23)
%I - Hour of the day, 12-hour clock (01..12)
%j - Day of the year (001..366)
%m - Month of the year (01..12)
%M - Minute of the hour (00..59)
%p - Meridian indicator (``AM'' or ``PM'')
%s - Number of seconds since 1970-01-01 00:00:00 UTC.
%S - Second of the minute (00..60)
%U - Week number of the current year,
 starting with the first Sunday as the first
 day of the first week (00..53)
%W - Week number of the current year,
 starting with the first Monday as the first
 day of the first week (00..53)
%w - Day of the week (Sunday is 0, 0..6)
%x - Preferred representation for the date alone, no time
%X - Preferred representation for the time alone, no date
%y - Year without a century (00..99)
%Y - Year with century
%Z - Time zone name
%% - Literal ``%'' character

date_to_long_string - Format a date to long format. e.g. 07 November 2008
date_to_rfc822 - Convert a Date into the RFC-822 format used for RSS feeds.
date_to_string - Convert a date to short format. e.g. 07 Nov 2008
date_to_xmlschema - Convert a Date into XML Schema (ISO 8601) format.
default - returns the given variable unless it is null or the empty string, when it will return the given value, e.g. {{ undefined_variable | default: "Default value" }} #=> "Default value"
default_errors -
default_pagination -
divided_by - integer division e.g. {{ 10 | divided_by:3 }} #=> 3
downcase - convert an input string to lowercase
escape - html escape a string
escape_once - returns an escaped version of html without affecting existing escaped entities
first - get the first element of the passed-in array
floor - rounds a number down to the nearest integer, e.g. {{ 4.6 | floor }} #=> 4
gist (provided by jekyll-gist plugin) - display a gist. e.g. {% gist c08ee0f2726fd0e3909d %}
group_by - group elements from array by given property: {{ site.posts | group_by:"category" }}
group_by_exp - Group an array’s items using a Liquid expression. e.g. {{ site.members | group_by_exp:"item","item.graduation_year | truncate: 3, \"\"" }} #=> [{"name"=>"201...", "items"=>[...]},{"name"=>"200...", "items"=>[...]}]
highlight - Wraps words inside search results with an HTML <strong> tag with the class highlight if it matches the submitted search.terms. Has to be used in a search form. Does this work in Jekyll? Not to be confused with the highlight tag.
highlight_active_tag - Wraps a tag link in a <span> with the class active if that tag is being used to filter a collection.
img_tag - generate an img html tag
inspect - Convert an object into its String representation for debugging. Returns a JSON stringified version of a variable so use as <pre>{{ page | inspect }}</pre> - possibly references Ruby’s inspect function?
join - join elements of the array with certain character between them
json - Converts a string into JSON format.

You do not have to wrap the Liquid output in quotations - the json filter will add them in. The json filter will also escape quotes as needed inside the output. The json filter can also used to make Liquid objects readable by JavaScript.
jsonify - convert data to JSON: {{ site.data.dinosaurs | jsonify }}
last - get the last element of the passed in array
lstrip - strips all whitespace from the beginning of a string
map - map/collect an array on a given property
markdownify - convert markdown to HTML
minus - subtraction e.g. {{ 4 | minus:2 }} #=> 2
modulo - remainder, e.g. {{ 3 | modulo:2 }} #=> 1
newline_to_br - replace each newline (\n) with html break
normalize_whitespace - Replace any occurrence of whitespace with a single space.
number_of_words - Count the number of words in some text.
placeholder_svg_tag
plus - addition e.g. {{ '1' | plus:'1' }} #=> 2, {{ 1 | plus:1 }} #=> 2
pop - Remove an entry from the end of an array. Non-destructive, makes a copy of the array and changes that.
prepend - prepend a string e.g. {{ 'bar' | prepend:'foo' }} #=> 'foobar'
push - Add entry to the end of an array. Non-destructive, makes a copy of the array and changes that.
relative_url - Prepend the baseurl value to the input. Useful if your site is hosted at a subpath rather than the root of the domain. e.g. {{ "/assets/style.css" | relative_url }} #=> /my-baseurl/assets/style.css
remove - remove each occurrence e.g. {{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'
remove_first - remove the first occurrence e.g. {{ 'barbar' | remove_first:'bar' }} #=> 'bar'
replace - replace each occurrence e.g. {{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'
replace_first - replace the first occurrence e.g. {{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'
reverse - reverses the passed in array
round - rounds input to the nearest integer or specified number of decimals e.g. {{ 4.5612 | round: 2 }} #=> 4.56
rstrip - strips all whitespace from the end of a string
sample - Pick a random value from an array. Optionally provide a number to pick multiple values.
sassify - Convert a Sass-formatted string into CSS.
script_tag - generate a script html tag
scssify - Convert a Scss-formatted string into CSS.
shift - Add entry to the start of an array. Non-destructive, makes a copy of the array and changes that.
size - return the size of an array or string
slice - slice a string. Takes an offset and length, e.g. {{ "hello" | slice: -3, 3 }} #=> llo
slugify - Convert a string into a lowercase URL “slug”. Optionally takes a style parameter: none, raw, default, pretty, ascii, latin. Definitions for permalink styles
sort - sort elements of the array
sort_natural - Sort elements of an array ignoring case if strings provide optional property with which to sort an array of hashes or drops.
smartify - Convert “quotes” into “smart quotes.”
split - split a string on a matching pattern e.g. {{ "a~b" | split:"~" }} #=> ['a','b']
strip - strips all whitespace from both ends of the string
strip_html - strip html from string
strip_newlines - strip all newlines (\n) from string
stylesheet_tag - generate a stylesheet html tag
times - multiplication e.g {{ 5 | times:4 }} #=> 20
to_integer - Convert a string or boolean to integer.
truncate - truncate a string down to x characters. It also accepts a second parameter that will append to the string e.g. {{ 'foobarfoobar' | truncate: 5, '.' }} #=> 'foob.'
truncatewords - truncate a string down to x words
uniq - remove duplicate elements from an array, optionally using a given property to test for uniqueness
unshift - Remove an entry from the start of an array. Non-destructive, makes a copy of the array and changes that.
upcase - convert an input string to uppercase
uri_escape - Percent encodes any special characters in a URI. URI escape normally replaces a space with %20. Reserved characters will not be escaped.
url_decode - url decode a string
url_encode - url encode a string
where - select elements from array with given property value: {{ site.posts | where:"category","foo" }}
where_exp - Select all the objects in an array where the expression is true. Jekyll v3.2.0 & later. e.g. {{ site.members | where_exp:"item","item.graduation_year == 2014" }} {{ site.members | where_exp:"item","item.graduation_year < 2014" }} {{ site.members | where_exp:"item","item.projects contains 'foo'" }}
xml_escape - Escape some text for use in XML.

Liquid filters that don’t work in Jekyll

These math filters don’t work:
- at_least - Limits a number to a minimum value.
- at_most - Limits a number to a maximum value.
Not all of the string filters work:
- The hashing filters don’t work
- camelcase
- pluralize
- time_tag
Not all of the utility filters work:
- weight_with_unit - Formats a number with the default weight unit. The unit can be overridden by passing it into the filter.
- format_address
The money filters don’t appear to work.
The colour filters don’t seem to work:
- color_brightness - Calculates the perceived brightness of the given color. Uses W3C recommendations for calculating perceived brightness, for the purpose of ensuring adequate contrast.
- color_darken - Darkens the input color. Takes a value between 0 and 100 percent.
- color_desaturate - Desaturates the input color. Takes a value between 0 and 100 percent.
- color_extract - Extracts a component from the color. Valid components are alpha, red, green, blue, hue, saturation and lightness.
- color_lighten - Lightens the input color. Takes a value between 0 and 100 percent.
- color_mix - Blends together two colors. Blend factor should be a value value between 0 and 100 percent.
- color_modify - Modifies the given component of a color. {{ '#7ab55c' | color_modify: 'red', 255 }} #=> #ffb55c
- color_saturate - Saturates the input color. Takes a value between 0 and 100 percent.
- color_to_hex - Converts a CSS color string to hex6 format.
- color_to_hsl - Converts a CSS color string to CSS hsl() format.
- color_to_rgb - Converts a CSS color string to CSS rgb() format.

Add Disqus to Jekyll pages

Julian Knight — Tue, 02 Jan 2018 17:11:00 +0000

Example code to add to every page as a footer to enable the Disqus comments service.

Create footer.html in your site _includes folder or include this in the default layout in _layouts.

{% if page.comments %}
<div id="disqus_thread"></div>
<script>
 var disqus_config = function () {
 this.page.url = '{{ page.url | absolute_url }}'
 this.page.identifier = '{{ page.id }}'
 };
 (function() { var d = document, s = d.createElement('script');
 s.src = 'https://<<set_this_from_disqus_settings>>.disqus.com/embed.js';
 s.setAttribute('data-timestamp', +new Date()); (d.head || d.body).appendChild(s);
 })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
{% endif %}

<div>Updated: {{ page.date | default: site.time | date: "%Y-%m-%d %H:%M" }} <a href="#top">Top</a></div>

Note that the default minima theme for Jekyll/GitHub pages includes a setting for this in _config.yml but currently does not include the appropriate include file to let you use it!

Also note that you have very little control over the styling. In particular, the width is set to 100% so make sure that this code is wrapped in a div that is limited to your normal content width.

How to create a page toc

Julian Knight — Tue, 02 Jan 2018 17:00:00 +0000

If you want to generate a table of contents list (toc) for a markdown file, you can use the native Kramdown feature.

If you want to generate an in-page table of contents using markdown headings, you can do so with the following code.

* This list entry is required but will not be shown, it is replaced by the toc
{:toc}