Part 2 - Setup

This part of the tutorial revolves around setting up the default Jekyll 3 Minima (jekyll 2019)¹ them to facilitate understanding Jekyll website structure, which is essential when modifying a Jekyll website.

Installation

Installing Git

Git is a version control system that enables detailed tracking of project changes. Version control with Git is a useful skill prevalent among most popular software projects.

Installing Git will offer additional benefits including Git Bash (i.e., a command line prompt with Linux tools, e.g., ls) and hosting project repositories on GitHub. GitHub also provides GitHub pages, which uses the Jekyll build system to provide free hosting of static websites.

Git can be installed from here.

Successful Git installation can be verified via opening Git Bash and checking the git version:

$ git --version
git version 2.16.2.windows.1

Installing Ruby

Since Jekyll is a Ruby-based SSG, the Ruby language environment must be installed. The environment enables installing Ruby applications (commonly referred to as “gems”) via the Ruby gem package manager, which facilitates installing, updating, or removing these applications.

Development in this tutorial uses a Windows machine, however, Ruby hence Jekyll are cross-platform.

Ruby can be installed via an installer from RubyInstaller. It is recommended to download and install the Ruby+Devkit 2.5.X which provides necessary tools and dependencies. The installer wizard will guide the installation process, however, ensure the option to add Ruby to the computer’s Path is selected to enable its access via a command line prompt (e.g., CMD).

On installation completion, verify Ruby is correctly installed via opening a command line prompt (e.g., CMD) and entering ruby -v, which should display the installed version of Ruby:

$ ruby -v # input
ruby 2.5.3p105 (2018-10-18 revision 65156) [x64-mingw32] # output

Similarly ensure the gem package manager is installed:

$ gem -v
2.7.6

Installing Jekyll

The gem package manager can be used to install Bundler, which aids Jekyll dependency management by installing gems from a Jekyll website’s Gemfile hence enabling the website to be built on any computer with Ruby, Bundler and Jekyll installed.

Jekyll and Bundler can be installed via:

$ gem install jekyll bundler
Successfully installed jekyll-3.8.5
Parsing documentation for jekyll-3.8.5
Done installing documentation for jekyll after 1 seconds
Successfully installed bundler-1.17.3
Parsing documentation for bundler-1.17.3
Installing ri documentation for bundler-1.17.3
Done installing documentation for bundler after 5 seconds
2 gems installed

Installation of both gems can be verified via:

$ jekyll -v
jekyll 3.8.5
$ bundler -v
Bundler version 1.17.3

Understanding Jekyll Website Structure

Understanding Jekyll website structure will facilitate developing Jekyll websites since the websites are built from a pre-build directory structure (containing source files) to generate the static website withing a post-build directory structure.

Creating a Basic Blog

To obtain build structures for study, a basic blog website can be rapidly created via the default Jekyll 3 Minima theme using jekyll new <website_name>:

$ jekyll new basic_blog

For brevity, verbose output is omitted in above code-snippet. However, the output would include dependencies handled by bundler and website installation via jekyll.

The newly created basic_blog website can be built and served locally via the following steps:

1. Verify the basic_blog directory was created by listing current directory contents:

    $ ls
    basic_blog/
   

2. Enter the basic_blog directory:

    $ cd basic_blog
   

3. The pre-build structure of basic_blog can be viewed:

    $ ls
    _config.yml  _posts/  404.html  about.md  Gemfile  Gemfile.lock  index.md
   

4. Build and locally serve the basic_blog website:

    $ jekyll serve --watch
   

   The --watch flag allows the server to automatically restart when source files change avoiding a manual restart. To avoid future problems, it is important to note that the --watch flag does not affect _config.yml hence a manual restarted is required to reflect _config.yml changes.

   The basic_blog website can be viewed by entering the server address in a web-browser. The server address (formatted as Server address: ...) is given in the output of jekyll serve --watch (the port is commonly 4000 hence the local server address is commonly localhost:4000).

   The displayed basic_blog webpage provides several basic blog features including blog title, page navigation-bar (currently displaying the “About” page), and a list of posts:

   The local server can be closed via the Ctrl+c shortcut in the command line prompt.

   The basic-blog website created in this tutorial is hosted via GitHub Pages (accessible here) and will be hosted on a university web-server (accessible here)

Jekyll Website Structure

In a new instance of the command line prompt, the post-build structure of basic_blog can be viewed (note the newly generated _site directory):

$ ls
_config.yml  _site/    about.md  Gemfile.lock
_posts/      404.html  Gemfile   index.md

Jekyll website structure may include several directories and files. However, some of the critical files can be explored via the basic_blog website, which include:

• _config.yml: Responsible for configuration data (i.e., website settings)
• Gemfile: Lists website dependencies (varies based on used functionalities) hence enabling easy setup (via gem and bundler) and building (via jekyll) on different computers
• _posts: Contains text-file blog posts following the required naming format of yyyy-mm-dd-title, and contain content structured and styled via the simple Markdown language
• index.md: Represents the website homepage that is displayed as an entry point to visitors hence provides navigation to other website areas
• _site: Contains the generated website structure, including built static webpages intended to be served directly to visitors.

Other important website structure components include _includes (contains reusable HTML components), _layouts (contains reusable layout templates), and _sass (contains SASS (CSS preprocessing scripting language, (Sass 2019)²) files enabling use of variables that generate respective CSS files).

Jekyll documentation provides further detail on Jekyll website structure covering various important components as shown in the following textual representation of a Jekyll website structure (originally from (Jekyll 2018)³):

.
├── _config.yml
├── _data
|   └── members.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid front matter

This tutorial will cover relevant components when necessary, however, it is important to be aware of the website structure.

References