Wilson Mar bio photo

Wilson Mar

Hello. Hire me!

Email me Calendar Skype call 310 320-7878

LinkedIn Twitter Gitter Google+ Youtube

Github Stackoverflow Pinterest

Getting started with Jekyll


This article contains notes on getting started with Jekyll and other static websites.

This is one in a series:

  1. Static website development
  2. Jekyll site development
  3. Jekyll templates and themes
  4. Email from Jekyll sites
  5. Add search to Jekyll sites
  6. Authenticate on static sites
  7. Clickable maps in Jekyll sites

There is no need to repeat excellent tutorials:

Jekyll is currently the most popular among static site builder options.

Bundle install

After downloading, have Maven pull in dependencies based on the Gemfile:

bundle install

NOTE: Technically, “install” is not needed since it’s the default command for bundle.

Bundling makes the list of dependencies in the Gemfile to be downloaded.

Grunt tasks

Behind the scenes is a running of the Gruntfie.js that comes with the theme. It defines the parameters of various tasks that are downloaded:

  • clean clears files and folders.
  • jshint validates files with JSHint, based on the .jshintrc configuration file at the root folder.
  • uglify minfies files with UglifyJS.
  • watch runs tasks whenever watched files change.
  • imagemin minifies PNG graphics files.
  • grunt-svgmin minifies SVG graphics files.

NOTE: File names beginning with a dot are hidden.

Serve Jekyll landing page

Theme programming goes to work generating HTML files in folder _site when this command is issued when the present working directory is the site’s folder:

To see the site the way GitHub would generate it (without additional plug-ins some templates provide):

   bundle exec jekyll serve --safe

The precise version of plug-ins used by GitHub on-line is listed here.


   bundle exec jekyll serve

PROTIP: Leave this terminal instance running and open another Terminal instance to work on the content of the site.

The generated HTML files can then be accessed from an internet browser at this URL:


The landing page of the site is defined in the index.md file at the root folder.

The theme by itself does not show much. The template’s author assumes that technical people will be using his creation.

When the web server starts, it is industry standard for the index.html file to be rendered.

  1. Edit file index.html file. By default it contains this:
layout: archive
author_profile: true
Ù% include base_path %}

<h3 class="archive__subtitle">Recent Posts</h3>

Ù% for post in paginator.posts %}
Ù% include archive-single.html %}
Ù% endfor %}

Ù% include paginator.html %}

Between the two triple-dash characters is the “front matter” for Jekyll to interpret.

Jekyll uses the layout tag’s value archive to build out the page according to the archive.html file within the _layouts folder.

Another layout type, splash, arranges the page with thumbnail pictures.

The other layout types are default, single, and compress.

Jekyll converts index.md files to index.html files.

Edit index.html author_profile

Having author_profile: true tells Jekyll to add the profile on the left side.

  1. If you would rather have text greet your visitors, add it.
layout: home
excerpt: "By Wilson Mar"
tags: [Jekyll, theme, responsive, blog, template]
feature: sunrise-1900x500.png
  1. If you would rather have text greet your visitors, add it.
<meta name="keywords" content="Jekyll, theme, responsive, blog, template">

TODO: Substitute the image file name in the feature: variable with an alternative file you placed in the images folder.

Return to this page from any other by clicking on the site’s title presented at the upper left corner.

Change README.md content

  1. Use a text editor program to open the README.md file at the root.

    This file is not shown on the website.

    It was written for those who work with the site’s code, not readers of the resulting website.

    So the content of this page should be changed from being about the theme to about the website derived from the theme template, such as:

    “I hope you’ll file an issue or send a Pull Request. I need the help.”

  2. File mm-theme-post-600.jpg within the images folder can be deleted.

Edit _config.yml and reset server

  1. Use a text editor to edit _config.yml.

    # Site Settings
    locale                   : "en-US"
    title                    : "Home"
    title_separator          : "-"
    name                     : "Wilson Mar"
    description              : "Hello. Hire me."
  2. Change the title text from “USER_” to "Home" or whatever you want.

  3. Change the name value to your screen name.

  4. Save and exit the file.
  5. Stop the server so the changes take.
  6. Start the server again.

  7. When you view the page again, notice the heading has changed to your title value.

Edit _config.yml author info

  1. Again use a text editor to edit the _config.yml file to change other values.

  2. Scroll down the file to:

    # Site Author
    name             : "Wilson Mar"
    avatar           : "bio-photo.jpg"
    bio              : "Hello."
    location         : "Everywhere"
  3. Change the default author name, bio text, and location.

    <a href=”#avatar>Change the avatar</a>. PROTIP: Don’t change more than one or two values before you reset and view again so you know what change break the system.

Tabs, folders, and index.md files (for SEO)

Links at the top of the page (“QUICK-START GUIDE”, “ABOUT”, etc.) are specfied by the navigation.html file within the _data folder.

  1. Edit that file.

    The title: key specifies the text of each tab, such as “About”.

    NOTE: CSS in the theme automatically turns all letters into capital.

  2. Change url values such as this:

- title: About
url: /about/

- title: Sample Posts
url: /posts/
  1. Save and restart the server.

index.md under About folders

Next let’s use a text editor to look into that about folder specified in the .yml file.

github: repo: https://github.com/user/Proj # “GitHub project” link on sidebar

index.md under folders

Jekyll converts the contents of each index.md file (containing markdown text) into index.html files containing HTML.

Open the index.md file in the about folder.

HOORAY: The use of folders above an index.html file enables calls using SEO-friendly links. For example, to reference the about link:


HOORAY: This technique does not require use of mechanisms in the underlying web server container (such as IIS).

The text is added to page titles that appear in browser tabs through this HTML:

<title>All Posts &#8211; WilsonMar.GitHub.io</title>

Parsing of post file names

The posts tab link to files within the _posts folder. In the case of the sample file named “2011-03-10-sample-post.md”, Jekyll programming parses the “sample-post” out of the file name and uses that as if it’s named “sample-post.html”.

UI Text Translation

An addition

Metadata within .md files

At the top of each markdown file, between a set of 3 dashes, are key-value pairs providing metadata about the page, such as this example from the index.md file within folder about:

layout: page
title: About
tags: [about, Jekyll, theme, responsive]
modified: 2014-08-08T20:53:07.573882-04:00
comments: true
   feature: pic pic blue black stars spin 1900x500.jpg
   credit: Jeremy Thomas
   creditlink: https://www.flickr.com/photos/132218932@N03/page2

EXTRA: Detailed YAML specifications are at: http://www.yaml.org/spec/1.2/spec.html

HOORAY: Such metadata takes the place of a database referenced to dynamically generate pages (as WordPress does). Jekyll’s lack of a database vastly simplies matters and speeds up processing. This enables static page HTML to be distributed in CDNs (Content Distribution Networks) around the world. That maximizes download speed for visitors.

Layout types

The various layout types are defined in files (with no extension) within the _templates folder:

  • archive
  • page
  • post

HOORAY: This approach enables additional types to be defined.

layout: {}
tags: []

Text within square braces define an array of several values.

Liquid engine

Tags within { curly braces } are processed by the Liquid templating engine.

Liquid can perform if/then/else decisions and loops.

EXTRA: More detail about Liquid is at: https://docs.shopify.com/themes/liquid/basics#If_.2F_Else_.2F_Unless


One of the most powerful features provided by Liquid is Collections.

Collections is explained at:

Collections refer to a custom folder containing many markdown files, each having front-matter than can be parsed by Liquid code.

Ben has a great decision diagram:

fig white jekyll page post collection decision

NOTE: site.categories and site.tags only works on _posts.

In the list of posts, post titles with a link icon get that way because in its YAML is a line link post line such as this:

link: http://www.wilsonmar.com

.yml metada

Default values are specified in a _config.yml file at the root of the site folder.

EXTRA: All keys are detailed at http://jekyllrb.com/docs/configuration/

Here are the first few lines of a sample file:

# Site wide configuration

title:            WilsonMar.GitHub.io
locale:           en_US

# Jekyll configuration

permalink:   /:categories/:title/
markdown:    kramdown
highlighter: rouge
sass_dir: _sass
style: compressed
- jekyll-sitemap
- jekyll-gist

PROTIP: Changes in the _config.yml file are applied only when the Jekyll service is recycled. At the command terminal window where Jekyll was launched, press control+C, then invoke the command to start the server again.

Another theme (Poole Hyde) adds:

repo:  https://github.com/user/Proj # "GitHub project" link on sidebar

sitemap.xml in _site

Theme programming also generates the _site folder and in it generates feed.xml and sitemap.xml files for web crawlers to read.

Bing it on

TODO: Get a value for the bing-verify: variable in your _config.yml.

  1. Open a Webmaster Tools account at bing.com/toolbox/webmaster/

  2. Sign In with a Windows Live ID. If you don’t have a Microsoft account already, get one.

  3. Type in your Site Name (mine’s wilsonmar.github.io) and click Add a site.

  4. Type in the URL to your Site Map. (mine’s http://wilsonmar.github.io/sitemap.xml).

    The sitemap.xml file is generated in the _site folder, but will be the root folder when deployed on a web server.

  5. Fill out the other fields (contact info and preferences), then click Save.

  6. In the Verify ownership page, copy the string from:

   <meta name="msvalidate.01" content="73A60A207FC7D42B6F428E462079B001" />
  1. Paste that string to the right of the bing-verify: variable.

  2. Click the BingSiteAuth.xml link to save the file.
  3. Move the file into the root folder where the _config.yml file is (NOT in the _site folder, which gets deleted and repopulated automatically).

  4. Recycle the Jekyll server to see the BingSiteAuth.xml in the _site folder.

Google Ownership

This is explained in https://support.google.com/webmasters/answer/35179?hl=en

  1. Access Webmasters Tools using your Google account.

  2. Add a Property (such as http://wilsonmar.github.io).

  3. Download the html file (such as google923b0745fb3293c1.html) to the Downloads folder.

  4. Move the file into the root folder where the _config.yml file is (NOT in the _site folder, which gets deleted and repopulated automatically).

  5. Download the file.

Disqus comments

  1. Use an internet browser to get to: Disqus.com.

This is about creating a publisher account such as “wilsonmarcom”.

  1. PROTIP: Create a separate personal commenter account (such as “wilsonmar”) to track your responses on other websites.

  2. Click the cog next to your picture to select Add Disqus To Site, or https://publishers.disqus.com/engage?utm_source=Home-Nav

  3. Click Install on your site.

  4. Specify a site name such as “wilsonmar-github-io”.

  5. Click Next and answer the demographic questions (how many visits, etc.).

  6. You don’t need to select installation for Universal code and copy paste JavaScript because the theme has already done that in file _disqus_comments.html within folder _includes.

  7. Copy the site.owner.disqus-shortname, such as “wilsonmargithubio” from:

<script id="dsq-count-scr" src="//wilsonmargithubio.disqus.com/count.js" async></script>
  1. Open for edit file _config.yml in the root folder.

  2. Paste the Disqus short name as the value to key disqus-shortname:.

  3. Read more about configuration of Disqus at: https://help.disqus.com/customer/en/portal/articles/2158629

Disqus Setup Disqus on a New Site.

Multiple authors

Lower in the file is information about the default author displayed on all pages. This can be overridden in a particular index.md or post file by a line such as:

author: billy_rick

“billy_rick” is a key to more information in the authors.yml file within the _data folder:

  twitter: @billyrick

HOORAY: This mechanism presents the photo and links to multiple alternative authors to appear on the website.

If you’d like more links, add them in folder _includes file _author-bio.html:

Social sharing

On the bottom of every page of the minimal-mistakes theme are large buttons for sharing tweets, Facebook, and Google.

Unlike links on the left pane of every page, clicking on these links pops up a new browser window.

You can change that pre-populated text (the URL) by changing the _social-share.html file withing folder _includes. The default pulls in the value of variables:

https://wilsonmar.github.io and /jekyll-site-development/

The pop-up relies on cookies previously created when the visitor signed into Twitter, Facebook, and Google on the same browser used to access this site.


Images can be defined in GFM or standard HTML.

In-line GFM images

Positioning of GFM-specified images can be specified using a special tag.

![Smithsonian Image](https://wilsonmar.github.io/images/3953273590_704e3899d5_m.jpg)
{: .image-pull-right}

renders as:

Smithsonian Image

NOTE: Most images are stored in the site’s images folder.

Clickable images

GFM is not yet able to handle code to specific clickable images, either as HTML image maps nor as CSS.

One Up

<a href="http://farm9.staticflickr.com/8426/7758832526_cc8f681e48_b.jpg"><img src="http://farm9.staticflickr.com/8426/7758832526_cc8f681e48_c.jpg"></a>
<figcaption><a href="http://www.flickr.com/photos/80901381@N04/7758832526/" title="Morning Fog Emerging From Trees by A Guy Taking Pictures, on Flickr">Figure: Morning Fog Emerging From Trees by A Guy Taking Pictures, on Flickr</a>.</figcaption>

renders to:

Figure: Morning Fog Emerging From Trees by A Guy Taking Pictures, on Flickr.

Half/Three Up

The theme has a half class to split the available horizonatl space in half to display two images side by side (and share the same caption).

<figure class="half">
<a href="/images/image-filename-1-large.jpg"><img src="/images/image-filename-1.jpg"></a>
<a href="/images/image-filename-2-large.jpg"><img src="/images/image-filename-2.jpg"></a>
<figcaption>Figure: Two images.</figcaption>

renders to:

Figure: Two images.

Three Up

The theme has a third class to split the available horizontal space in thirds to display three images side by side (and share the same caption):

<figure class="third">
<img src="/images/image-filename-1.jpg">
<img src="/images/image-filename-2.jpg">
<img src="/images/image-filename-3.jpg">
<figcaption>Figure: Three images.</figcaption>

is rendered as:

Figure: Three images.

Layout responsive to screen size

The MadeMistakes themes make use of the Semantic Grid System to define fluid grids for each major page layouts with a few lines of CSS code referencing @media queries. This makes the theme responsive – adapting to various size screens:

  • Desktop default (up to the largest HD & 4XHD screen)

    Min-width: 780px

  • Tablet Portrait (to landscape and desktop)

    Min-width: 768px / Max-width: 979px

  • Smartphone (and all smaller screens)

    Max-width: 480px

Image sized to screen?

The size of screens.

The image for Twitter Cards is a square image around 120 x 120 pixels.

Markdown coding

The next few sections are based on


Notice boxes

To put text in a box, add {: .notice} under the text to be boxed:

**CAUTION:** Invalid markup can crash the server.
{: .notice}

renders to:

CAUTION: Invalid markup can crash the server.

PROTIP: Make a small change (one phrase) then verify rendering. Commit to git at every verified set.


A leading > marks a line as a blockquote:

> Lorem ipsum

renders as:

Lorem ipsum


A paragraph ending with the &Vcirc; “circumflex” character (upper case of the number 6 key) between square brackets defines the footnote number:

Footnotes are Syntax Highighting1.

A repeat of the sequence at the beginning of a paragraph defines the definition:

[^1]: <http://en.wikipedia.org/wiki/Syntax_highlighting>

Button colors in HTML

Use pre-defined classes:

<div markdown="0"><a href="#" class="btn">Primary Button</a></div>
<div markdown="0"><a href="#" class="btn btn-success">Success Button</a></div>
<div markdown="0"><a href="#" class="btn btn-warning">Warning Button</a></div>
<div markdown="0"><a href="#" class="btn btn-danger">Danger Button</a></div>
<div markdown="0"><a href="#" class="btn btn-info">Info Button</a></div>

renders to:

Primary Button
Success Button
Warning Button
Danger Button
Info Button

If you are viewing this on a desktop, mouse-over each button to see the color change.


To change the colors, edit in folder _sass file variables.scss, then compile the file to .css.

    sass variables.scss  variables.css

Sass, or Syntactically Awesome StyleSheets, is an extension language for CSS.



   $background-transparent :


Paragraph Indents

By default, the theme assumes formatting is for books by removing extra lines and adds indents to second and subsequent paragraphs. Well, we’re in the internet age where long paragraphs are the exception.

To disable the indents and add spacing between paragraphs, edit in folder _sass file variables.scss to change:

$paragraph-indent: true !default;


$paragraph-indent: false;

PROTIP: This change in the theme enables use of indented items using GFM.

Numbered lists

As with GFM, numbers in front of ordered list items can be preceded by zeros since they are automatically numbered:

0. Item one
0. sub item one
0. sub item two
0. Item two

some text after 3 spaces.

0. Item three

renders to:

  1. Item one
  2. sub item one
  3. sub item two
  4. Item two

some text after 3 spaces.

  1. Item three

Code Snippets

Instead of a set of three back quotes, blocks of programming code are enclosed with special tags like this:

{% highlight css %}
#container {
float: left;
margin: 0 -240px 0 0;
width: 100%;
{% endhighlight %}

renders as:

#container {
float: left;
margin: 0 -240px 0 0;
width: 100%;


Snippets of code on Gist.com can be displayed on the web page with a simple line containing the gist.com userid and snippet number:

{% gist userid/6589546 %}

Standard GFM mark-up

Several coding techniques ar the same as in GitHub Flavored Markdown.

  • Asterisks precede text in unordered lists preceded with bullets.
  • The number of # characters preceding heading text specifies the level.
  • One asterisk enclosing text makes it italics.
  • Two asterisk enclosing text makes it bold.

Just as with GFM, regular HTML is recognized and processed as such.

<strong>bolded text</strong>

Custom Includes

Jekyll can process several special tags beyond what GFM can do. An entire HTML file can be inserted:

{% include _toc.html %}

The tag is processed by Kramdown which generates the Table of Contents displayed on the right side of the screen.

A custom include can be coded within markdown like this:

{% include evangelist_links.html %}

Doing this takes some mental contortion because of the automatic processing.

The evangelist_links.html file referenced needs to be in the _includes folder.

 During processing, the folder "_includes" is automatically added to the link.
 Therefore you can't put the include file anywhere else, or you'll get a message such as:

 Error: Included file '_includes/includes/1loadrun_map.html' not found

However, there can be markdown in the evangelist_links.html file, such as:

In this series:

* [Budget](Budget)

* [Future1](Future1)

NOTE: HTML code above to ignore can be included in the file.


A rule can be specified for formatting tables coded in GFM:

| Header1 | Header2 | Header3 |
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
| Foot1   | Foot2   | Foot3
{: rules="groups"}

renders to:

Header1 Header2 Header3
cell1 cell2 cell3
cell4 cell5 cell6
cell1 cell2 cell3
cell4 cell5 cell6
Foot1 Foot2 Foot3

Affiliate Ads

Amazon Affiliate Ads

  1. https://affiliate-program.amazon.com/gp/associates/network/main.html

  2. Search for a product to get its URL, such as: http://www.amazon.com/gp/product/B00IR2VEUS/ So Amazon’s product code is “B00IR2VEUS”.

  3. Specify the product code to get the HTML containing your affiliate tracking code, such as:

<a target="_blank" href="http://www.amazon.com/gp/product/B00IR2VEUS/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=B00IR2VEUS&linkCode=as2&tag=wilsonslifenotes&linkId=LGM2HVV7JYHE5QRS">Cabin Max Metz Backpack Flight Approved Carry on Bag 44 Litre Travel Hand Luggage - 55x40x20 (Black)</a><img src="http://ir-na.amazon-adsystem.com/e/ir?t=wilsonslifenotes&l=as2&o=1&a=B00IR2VEUS" width="1" height="1" border="0" alt="" />

Note the link has a one-pixel image link Amazon uses to track the number of impressions.

If you would like to list products you make on Amazon, get an account Seller Account at sellercentral.amazon.com/gp/homepage.html.

Google Affiliate Ads

Ideally, I would put a vertical ad under the table of contents.

A Node.js library to add search functionality to any Jekyll blog Demo here is available from this repo.

Theme http://mmistakes.github.io/so-simple-theme/theme-setup/#jekyll-search activates each page using it with the search_omit: true front matter.


This list of folders and files is about what processing occurs locally.

{$ endhighlight text %} _site .sass-cache .DS_Store *.sublime-project *.sublime-workspace codekit-config.json node_modules _asset_bundler_cache .jekyll-metadata {$ endhighlight %}

Additional features

Make Jekyll multi-lingual

Deploy to server

  • http://help.github.com/articles/using-jekyll-with-pages/

  • http://goo.gl/hE3Zj2 to http://nicolasgallager.com/simple-git-deployment-strategy-for-static sites/

  • jekyllrb.com/docs/deployment-methods/


QUESTION: How to add regular .html files to the site.

TODO: Inspired by Shamime’s photomap building, I added a Photomap tab and folder on my site.


QUESTION: Spell checking in GitHub?


  • Tutorial: http://jekyll.tips/jekyll-casts/

Jekyll MinimalMistake users in the wild

  • http://udaypal.com/jenkins-workflow-getting-started/
  • http://udaypal.com/2015-04-08-continuous-delivery-using-jenkins-workflow/

More on front-end styling

This is one of several topics:

  1. Text Editors
  2. Markdown text for GitHub from HTML
  3. 508 Accessibility

  4. JAM Stack Website Project Plan
  5. HTTP/2 Transition Project Plan
  6. Static websites
  7. Jekyll Site Development

  8. Website styles
  9. Website Styling

  10. Email from website
  11. Search within Hyde format Jekyll websites
  12. Windows Tile Pin Picture to Website Feed

  13. Data Visualization using Tableau