Jekyll Setup

Overall Setup

This Jekyll setup used several guides, including Archwiki - ruby setup, kbroman - gem installation, jmcglone - overall setup, jekyllrb - post setup, for a Ubuntu based machine to test before deploying to Github Pages.

Ruby Setup

For Ruby, a local install option was used. In particular, a .gemrc file was created along with $(ruby -e 'puts Gem.user_dir')/bin. This places all of the gems into a ~/.gem folder.

.gemrc

install: --user-install

The only gem needed for jekyll is github-pages, which can be installed with gem install github-pages. Updates can be checked with gem outdated and updated with gem update github-pages. System updates may be necessary with sudo gem update --system. If the .gemrc file doesn’t work, include the switch --user-install with the update command.

Ruby should also be updated with gem update. If one gem fails to install (an error could be failed to build gem native extension), this then could be solved by manually installing the gem that failed (like etc).

A makefile is also included to launch jekyll along with having different methods like a debug or mobile mode (using make, make build-debug, or make build-mobile).

Pages

This jekyll setup uses a collection titled pages so that there is the advantages of only having a folder with titles as file names, and in each file having a date that can be changed in order to sort each page.

Therefore, this allows the usage of post-like content while using pages and allows it to be sortable by date updated in pages. This allows no year, month, or day to be shown in the url or file, and allows the date to easily be changed.

Including code

Using markdown and a _includes/ folder allows the use of embedding code from a file that can be updated. An example of this is used in this webpage as the .gemrc and in the bash script below in webcrawlers. Jekyll also provides syntax highlighting with rouge (ruby install rouge) which can create css styles for a website.

#!/bin/bash
rougify style github > ../assets/syntax_style.css

There are two ways for showing code. One allows both markdown and html, the other uses only html but can hide the code.

code here

include code

Note: In markdown each symbol is commented out with \, the jekyll syntax is commented with raw and endraw tags, and the html is commented out by substituting &lt; for < and &gt; for > (& substitues as &amp;). Also, when including files in markdown, there is an extra newline added at the end of each file unlike when using html.

To use markdown inside html, the tag <div markdown=”1”> markdown code… <div> can be used.

Mobile

For mobile testing (make build-mobile using responsive design) make sure the firewall excepts outside calls. If the firewall ufw is active, this will prevent the webpage from being shared over the local network. Running the command sudo ufw allow 4000 will allow others to view the network. More information about ufw can be found here.

Webcrawlers

There needs to be enough content for Google to actually crawl the website, along with taking some time to do so. The sitemap for this website is located here (and a robots.txt or in jekyll format here). In order for search engines to locate the webpage, a bash script is used to ping Google and Bing.

It can also be helpful to add a lastmod to let search engines know when a page was last updated. The format that should be used is W3C Datetime (ISO 8601), and can be created in jekyll liquid for the sitemap as {{ page.date | date “%Y-%m-%d }}. Another part of the format would be to have the urls go from newest to oldest, and as such the jekyll format for loop could just have a reversed keyword in it.

#!/bin/bash

# check if webpage exists, don't donwload
ping_tool="wget --spider"
site_map="https://mwyoung.github.io/sitemap.xml"

declare -a se_array=("http://www.google.com/ping?sitemap=" \
    "http://www.bing.com/webmaster/ping.aspx?siteMap=")

for i in "${se_array[@]}"; do
    echo "====================="
    echo $ping_tool $i$site_map
    echo "====================="
    eval $ping_tool $i$site_map
done

Javascript and Tracking

This website doesn’t use javascript (but does use some newish HTML5 features). It also includes no tracking for the privacy aware.

404

A good 404 page build guide is available in the jekyll docs. It can be viewed here.

Other references

SO - Google Webcrawler, Medium - CSS Footer, Hiding pages from page list, Quackit - details tag, and Jekyll tags.