GitHub Pages with Jekyll's Static Web Framework

Jekyll is a great tool if you want the simplicity of a static website but with more complicated functionality. It offers a load of plugins and maintenance saving methods.

The primary advantages are:

• templating
• variables and loop functionality
• support for GitHub pages (a free webhosting platform for anyone with a GitHub account)
• plugins, database free solutions, and niche cases

If this is tempting strap in and I’ll describe my weekend setting up Jekyll.

Set up

You will want to give the Jekyll [quick setup] (https://jekyllrb.com/docs/) page a look (For this tutorial do only steps 1 & 2). Very friendly if you are on Linux or Mac, not so much on Windows.

Windows

Lucky for you, I am on Windows which means we’re on Linux. Head over to the WSL2 (Windows Subsystem for Linux- what a time to be alive) page and set it up. grab a Linux distro from the Microsoft store (Ubuntu) and run these commands:

• launch WSL from command prompt
  wsl
• run update (sudo is like as adminastrator in windows)
  sudo apt update && sudo apt upgrade -y
• clean system
  sudo apt-get autoremove
• install Ruby
• sudo apt-get ruby-full
• install GCC and Make
• sudo apt install build-essential
• follow quick start from Jekyll (Steps 1 & 2)

Nice, now we windows users are caught up to the Max and Linux.

Choosing a theme

This is the fun part of the project. Jekyll has been around for a decent amount of time and the community is mature enough to be both helpful and provide loads of materials. Do a google search for Jekyll themes and you will find a ton. For this tutorial we will use https://jekyllthemes.io/

Now that you have found a theme you fancy click on the “Theme Name on GitHub” button on the right-hand side of the page. If you have never used GitHub before don’t be intimidated, it is at its core a file hosting site for developers.

Figuring out Git

Ok I take it back; this next part may be a little intimidating. Open your terminal (if you are on Windows, open CMD and type WSL) and type the following git command:

git --version

If you are greeted with a version number, you are good to go. Otherwise give this article a read. Use Linux / Mac instructions.

Pick a folder where you’d like to work on your computer and copy the address. You can navigate to it using the cd (Change Directory) command. If you would like to follow my setup do the following:

**You are going to want this in a Linux/ Mac location
go to home directory
cd ~
create projects folder
mkdir projects
create web folder inside projects
cd projects
mkdir Web
you should see Web after running the above. ls command just lists files
ls

Now you will clone the theme you selected from GitHub in the folder of your choosing. To do this, go back to the theme’s GitHub page and find CODE button and copy the link that appears when it is clicked.

make sure your terminal is at the right location (see the prompt’s address). and use the git clone command
git clone [URL]
Typing the ls command should show a new folder with that projects default name. We wont worry about changing the folder name for now. Let’s give our new site a test run.

Running Jekyll

Start by changing directory into our theme folder
cd theme-folder-name
update and install jekyll plugins
bundle update
bundle install
launch a local web server to see your site in action (only available to you)
bundle exec jekyll serve
go to your web browser and go to
http://127.0.0.1:4000/
To stop the local server CTRL + C in your terminal

Balmy! Could not locate Gemfile

Most themes have a Ruby configure file already, but if you run into this issue simply create one. We will do this through the terminal, but a note editor works the same if you save it in the folder as Gemfile

• create the file
  nano Gemfile
• paste the following configurations

	# Hello! This is where you manage which Jekyll version is used to run.
	# When you want to use a different version, change it below, save the
	# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
	#
	#     bundle exec jekyll serve
	#
	# This will help ensure the proper Jekyll version is running.
	# Happy Jekylling!
	gem "jekyll", "~> 4.1.1"
	# This is the default theme for new Jekyll sites. You may change this to anything you like.
	gem "minima", "~> 2.5"
	# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
	# uncomment the line below. To upgrade, run `bundle update github-pages`.
	# gem "github-pages", group: :jekyll_plugins
	# If you have any plugins, put them here!
	group :jekyll_plugins do
	  gem "jekyll-feed", "~> 0.12"
	end

	# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
	# and associated library.
	platforms :mingw, :x64_mingw, :mswin, :jruby do
	  gem "tzinfo", "~> 1.2"
	  gem "tzinfo-data"
	end

	# Performance-booster for watching directories on Windows
	gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]

• save the Gemfile
  CTRL+x
Y
enter
• Nice. Now jump back up and run both the bundle commands.

Publishing your site

funky site you got there. Unfortunately, if you try and type in http://127.0.0.1:4000/ on your cell phone with your Wi-Fi off you’ll get nothing.

In the past this is the part where you’d have to shell out for a domain name, a webserver, and set up some sort of https service. Luckily, GitHub will circumvent the past.

GitHub Pages

GitHub pages is a free service that allows you to host sites for free, but with certain limitations. Because our page is effectively a static site we won’t have to worry about those limitations, but we will need to alter our template before we can get it up and running.

You could edit your site to match your information, but I found it less troublesome to get the site on GitHub pages first and then make your changes incrementally in case things go awry.

Creating the Repository

1. login to GitHub
2. make a new repository by clicking New
   
3. Name it what you’d like your site to be called (NOT the theme name)
4. confirm with the Create repository button

Configuring to GitHub’s liking

We need to change our Gemfile and our _config.yml file to satisfy these requirements.

• Gemfile
  using the terminal,
  nano Gemfile
  comment out this line by adding a ‘#’ to the beginning
  gem "jekyll"", "~> 4.1.1"
  uncomment the following line by removing the ‘#’ from the beginning of the line
  gem "github-pages", group jekyll_plugins
  exit and save
  CTRL + x
y
enter
  cool onto

_config.yml
pop the following lines into the file where you please:

important: before pasting make sure your _config.yml does not already have any of these elements. if they do update them to reflect these values
change “[ ]” to your values

url: 'https://[YOUR GITHUB USERNAME].github.io' # or other github assigned domain
baseurl: '/[YOUR GITHUB REPOSITORY NAME]'
lsi: false
safe: true
source:
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

Exit and save the file as we have before. Mine looks like this now

pushing to the web
Almost Done. You got this.

1. set your project to know what URL to send info to you can get this URL from your repository page
   git remote set-url origin [YOUR REPOSITORY URL]
2. upload
   git push origin
3. refreshing your GitHub repository page should now be populated with files. Jump to settings
4. Scroll down to the GitHub Pages section and select Master where the None dropdown is. Save.
5. This should generate a message and a link that looks like this.
   
   Your site is ready to be published at https://calmcoconut.github.io/test/.
6. follow the link and try it out on your cellphone

editing the theme for your purpose

I highly recommend the tutorials offered by CloudCannon on Jekyll. They have included both video and written formats. The cover most use cases. Follow this link for the blogging setup tutorial.

Common Problems

I am greeted with a 404 error when I click the link
something has gone wrong either with your local Gemfile or _config.yml file OR you have not uploaded to GitHub.

• redo the Configuring to GitHub’s liking section then reupload to github by issuing the following commands in the terminal.
  git remote set-url origin [YOUR REPOSITORY URL]
git add .
git commit (write any message and hit enter after running this)
  git push origin

The site loads but it has no images or looks like a 90’s website
Very annoying problem caused by how the CSS and images are referenced. if you know anything about HTML it is a simple fix. Otherwise try the following:

• open the _includes folder in your project
• find the head.html file
• open and edit any href tag to start with the following
  /diasDiaz
  instead of absolute paths. for example:
  <link rel="stylesheet" href="/diasDiaz/assets/css/style.css" /
• save but do not exit. push your changes by running the following commands
  git add .
git commit (write any message and hit enter after running this)
  git push origin
• clear your browser history and refresh your website (this is to clear the cache).