So you’ve built quite a portfolio in your career (so far), and you want to showcase yourself online. The first thing that would come to mind is to pay for hosting and pre-made website design for advertising your work. What if a Jekyll website to github pages?
Wouldn’t it be even cooler to build your own site and have it hosted for free? The only other thing that’s needed is some coding skills – which you probably already have, too!
In this article, you will learn how to setup create static websites using Jekyll, either from scratch or from a template. Also, publish that website to GitHub Pages – free of charge.
Table of Contents
This article is a how-to guide, and the objective is that, in the end, you will have created your own static website hosted in GitHub Pages and Jekyll. To be able to follow along with this article, you must have the following requirements in place.
- A Windows 10 computer with Windows Subsystem for Linux (WSL) enabled, and a Linux distribution installed such as the Debian GNU/Linux.
- Linux is required because Jekyll is a Ruby Gem, and it needs Ruby to be installed. While Ruby can be installed on Windows, it is my experience that Ruby on Linux is a lot less problematic than when running it on Windows.
- However, it is your choice to skip Windows and WSL altogether and just run everything on a Linux machine if you prefer. But, note that some of the instructions in this article may not be applicable.
- In this article, a Windows 10 computer with Debian GNU/Linux distribution will be used.
If you want to learn how to enable WSL in Windows 10 and install Debian, you can go to the following links: Windows Subsystem for Linux Installation Guide for Windows 10Windows Subsystem for Linux (WSL): The Ultimate Guide
- A code editor of your choice for editing your website. Like, Notepad++, Atom, and Visual Studio Code (recommended). In this article, Visual Studio Code will be used.
- A GitHub account where your static website will be hosted. It is recommended to sign up for a new account for the purpose of testing.
- A Git client such as GitHub Desktop which will be used in this article.
Installing Jekyll on Debian
Now that you have the necessary requirements, you can start installing the static site generator program – Jekyll. In this example, Jekyll will be installed inside the Debian Linux distribution inside WSL.
First, launch the Debian console. Then use the command below to make sure that the package list is updated.
sudo apt-get update
After running the command above, you should see a similar output, as shown in the image below. You need to wait for the update process to complete.
Once the update is completed, use the command below to install all the required dependencies for Jekyll.
sudo apt-get install ruby-full build-essential
You might be asked to provide your consent to continue the install, similar to the prompt below. Agree to it to continue the installation.
The installation may take several minutes depending on the speed of your system and internet connection. In this example, the installation took approximately 10 minutes to finish.
After completing the dependency installation, copy the command below and run it in your Debian console. The command below will add environment variables to avoid having to use
sudo when using Ruby.
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc source ~/.bashrc
Lastly, use the command below to install Jekyll and Bundler. Copy the code and paste it to your Debian console window to run it. The installation may take another 5 to 10 minutes to complete.
gem install jekyll bundler
Once the installation is complete, you can confirm that Jekyll is successfully loaded by checking its version. To check the Jekyll version, use the command
jekyll --version. As you can see from the screenshot below, the version installed on this development computer is jekyll 4.1.0.
Creating the GitHub Pages Repository
At this point, you would have already installed Jekyll. Before doing anything with it, you must first create the GitHub repository where your website will be hosted.
It was mentioned earlier in this article that you must have a GitHub account already available. It is also assumed that you have GitHub Desktop already installed and that you have logged in to it.
First, log in to GitHub Desktop using your GitHub account. Then, to create a new repository, click on File —> New repository.
In the New repository pop-up window, you need to provide the Name of the repository you are creating and the local path where the files will be stored.
The name of your repository must follow a specific naming convention. The name should be in this format – <username>.github.io – where <username> is your GitHub username. This naming convention must be strictly followed; otherwise, your website will not work.
In this example, the GitHub account name is jekylldev, so the resulting repository name is jekylldev.github.io. Once you’ve entered the repository name and the local path, click on the Create repository button.
As you can see from the image below, an empty repository has been created in C:\GitHub\jekylldev.github.io.
In the Debian Console, the path is obviously different. In this example, it can be found in /mnt/c/GitHub/jekylldev.github.io
Back in the GitHub Desktop window, you should see a similar image like the one below. At this point, do not publish the repository yet.
You should see a button that says Open in Visual Studio Code, click on it.
The repository folder will be opened in Visual Studio Code, as shown in the image below.
Creating a Site from Scratch
In the previous section, you’ve opened your repository in Visual Studio Code. In this section, you will create a website from scratch, build the site, and test.
Adding the Homepage to Your Site
In Visual Studio Code, under the Explorer pane, click on the New file icon. Then, name the new file as index.html.
Then, copy the code below, paste it into your HTML file in VS Code, and then save it.
<!doctype html> <html> <head> <meta charset="utf-8"> <title>Sample Home Page</title> </head> <body> <h1>Hello, Welcome to JekyllDev</h1> </body> </html>
The image below shows that index.html file is created, populated with code, and saved.
Initializing Your Site
You’ve already created your home page file named index.html. But, before you can test it, you must initialize your website first.
To initialize your website, go to the Debian console and change the working directory to where your repository is stored. In this example, the path is /mnt/c/GitHub/jekylldev.github.io.
Next, use the command below to initialize the site and create a GemFile.
After running the command above, you will get a similar output, as shown below. You’ll notice that a new file has been created with the name GemFile.
Next, go back to Visual Studio Code, click on the GemFile under the Explorer pane. The GemFile will be opened in the editor pane.
Go to the end of the file and append this code below. Then save the GemFile.
The contents of the GemFile would look similar to the image below.
After you’ve saved the GemFile, go back to the Debian console and run this command below.
The command above installs the site’s dependencies, and you should see a similar output like the screenshot below.
Building and Testing Your Site
Now that the site has been initialized, it is now ready to be built and tested. To build the website, go back to your Debian console and run this command below.
After running the code above, Jekyll builds the site and places the files under the _site folder in the repository. Assuming that the build was successful, you should see no errors, and the output would be similar to the screenshot below.
Next, if you want to test or preview your site, run this command below instead.
You will get an output similar to the one shown below. As you can see, there is a server address that you can use to view the site being served locally. In this example, the server address is http://127.0.0.1:4000
Using your browser, navigate to the specified server address to view your site.
To terminate Jekyll’s serving of the site, go back to the Debian console and press
Publishing Your Site
Your site has been built and tested. It is not yet published on the internet, and you can only access it locally on your machine. What’s left for you to do is publish the GitHub repository that you have created, which will result in your published website.
To publish your repository, go back to GitHub Desktop and type a summary to the summary box. In this example, the summary is “initial commit” – this can be anything that you deem appropriate. After entering the summary, the description is optional. Then, click on the Commit to master button.
Next, after the commit has completed, you must click on the Publish repository button to publish the repository to GitHub.
Next, you will be presented with the Publish repository pop-up window. You may add a description if you prefer. Make sure to uncheck the Keep this code private checkbox. Otherwise, your website will not be available to the public. Then, click on Publish repository.
Once publishing is done, wait for at least two minutes, then use your browser and navigate to your newly published website. The URL would be the repository name itself. In this example, the website URL is https://*jekylldev.github.io.
Congratulations! You have now successfully published your first static website created in Jekyll GitHub Pages.
Creating a Site Using a Jekyll Theme
At this point, you have already created a sample website that contained nothing but the words “Hello, Welcome to JekylllDev”. From there, you can opt to develop your own website design by following the Jekyll documentation.
Another option is to find an already existing Jekyll template (free or paid, the choice is up to you), and use that template as your site’s base design. Many websites offer free Jekyll themes, and some are listed below.
As an example, you can use a Jekyll theme named Mediator to use as the base design of your website.
Before going any further, you first need to delete your repository in GitHub, delete the repository on your computer, and delete all the files associated with it. This is because you will be recreating your repository from another Jekyll template.Using or applying a template to your Jekyll site may change depending on how the template owner designed it. The process that will be used in this article is a generic way of using a Jekyll theme.
Forking the Theme
Jekyll themes are typically hosted in GitHub as well. Simply go to the themes repository, in this example, the repository is at https://github.com/dirkfabisch/mediator.
From the theme’s repository, click on the Fork button.
Forking will create a copy of the repository into your GitHub account. Once the theme is forked, click on Settings.
Renaming the Repository
Inside the settings page, locate the Repository name box. You will see that the name is still the original name of the repository (mediator). You should change the name of the repository to <username>.github.io.
In this example, the repository name will be changed to jekylldev.github.io. Once you’ve typed in the name, click on the Rename button.
After renaming the repository, go back to the Settings page and confirm that the site has been published in GitHub Pages by similar to the screenshot below.
Then, when you click on the link or visit the address, you should see that it is already accessible, and the template has been applied.
Cloning the Website
You have successfully published a static website in GitHub pages with a beautiful Jekyll theme at this point. But, the contents of the website is still the same content from the original source.
Naturally, you will want to modify the contents of the website along with some of its components like the title, header, icon, banner photo, etc. Before you can do that, you will need to download or clone the website using GitHub Desktop.
To clone your website, open GitHub Desktop and click on Clone a repository. Then, you should be able to see the repository of your website from the list. Click on the repository and click Clone.
When you’re prompted with “How are you planning to use this fork?“, select For my own purposes, then click Continue.
Once the repository is cloned to your computer, you can then open the repository in Visual Studio Code, where you can start modifying the code.
For example, change the site’s title by editing the _config.yml file, as shown in the screenshot below.
Testing the Changes to the Site
So you’ve modified the code of the site, and you want to test it. The way to test the changes to the website is similar to the process that was done when you tested the site created from scratch (refer to the Building and Testing Your Site section in this article).
If this is the first time you’re testing the website after you’ve cloned it, you will need to first install the website’s dependencies by running the command below in the Debian console.
The above code will install the dependencies of the website. You must wait for it to complete as the installation may take several minutes.
Next, to test the site, run this command below.
bundle exec jekyll serve
Again, the server address to access the site locally is http://127.0.0.1:4000. And as you can see in the screenshot below, the title of the page has changed.
Once you’re done testing the website, do not forget to stop the Jekyll server by pressing
CTRL+C in the Debian console.
Pushing the Site Updates to GitHub Pages
When you’re done and satisfied with the site changes to made and wanted to update your live website, you can do so by pushing the updates using GitHub Desktop.
From GitHub Desktop, type if the summary (required) and description (optional) of the changes made to the repository. Then, click on Commit to master.
Once the changes are committed, click on the Push origin button to push the site’s updates to GitHub pages.
In this article, you’ve learned how to create a static website using Jekyll and publish it in GitHub pages for free. You’ve also learned how to prepare your machine to install Jekyll and its dependencies.
You’ve also learned how to create a GitHub Pages repository by creating a new repository locally and publishing it to Github. As well as by forking an existing repository, renaming, cloning and republishing it using GitHub Desktop.
There’s a lot more to Jekyll and GitHub pages than what can be covered in this article. Luckily, there is a lot of official and community documentation available. It is up to you to explore them and learn from them.