Publish Github Pages Using Jekyll

Ever thought of how to build a website without having to write an application code, or having to access databases. To solve this problem, we use Jekyll.

Jekyll is a simple, free, easy-to-use static site generator. You can use Jekyll to create simple websites/blogs/GitHub pages. It takes your content, renders markdown and liquid templates and convert to HTML that can be hosted on a web server. You can place your content in the form of text, markdown or HTML in the root directory of your project, or /docs folder and it processes these files in build time and generates HTML files from the layouts in your theme.

It is a static site generator as it isn’t actually running the live website, but hosting a static website by using the static site files which you have placed in your project. It is simple, static and has an easy GitHub Pages Integration which makes it a top reason why developers prefer it.

In this blog, I am going to show you how I learnt and created a simple, easy-to-use static GitHub Page, the issues I faced, and how I resolved it.

I hope this helps you!!

Let’s Get Started

PS: I’m using a mac.

Jekyll Set Up

1. Open terminal, and check if ruby is installed.

ruby -v

2. If ruby is installed, then install Jekyll

gem install jekyll

Create a GitHub repo

1. To create a repository , first login to GitHub, Click on the “New” icon in the GitHub page.

2. You can provide any name you want. I have created the repo with the name jekyll-poc as below.

3. Once created, clone the repo to your local machine by clicking on the “Code” icon -> Copy the link -> run the command in terminal in your local machine as shown below.

git clone https://github.com/Naina-Gurung/jekyll-poc.git

Create a Jekyll site in local

1. You will see a folder named jekyll-poc appear in your terminal. Go to the folder and run the command-

jekyll new .

Note: Don’t miss the dot(.) in the command.

If you have cloned the repo with a README.md file, the command will show conflict like below.

To resolve this conflict, run this command instead.

jekyll new . --force

This creates all gem based theme in the root path. You can confirm this by running an ls command in the same path. You can see files like Gemfile, _config.yml, index.markdown, about.markdown and other files being auto created.

2. Now let’s test if the site is working and publishing the content, run the command.

bundle exec jekyll serve

This will show a server address. Copy the url to address bar and hit ENTER.
You will see this webpage-

Press Ctrl+C to stop it.

Publish a GitHub Page

1. Add these changes to git by running the following commands-

git status
git add .
git commit -m "comment your changes done"
git push

2. Refresh your git repo in GitHub to see the files reflecting . Go to settings and click “Pages” , you will see something like this -

3. At first you will not see any GitHub pages link under “GitHub Pages” section , but once you select the branch from the dropdown option, it refreshes and you can see the GitHub link finally.

Open this GitHub link shown-

4. Oops!! the format of the content doesn’t look the same way as it reflected in the local host url.

What can we do to resolve it?

5. Now go back to your local machine to your repo project, and open your “_config.yml” file. You can see there are title ,email , description and other keys mentioned in the file.

Also notice there is a “baseurl” and “url” key with no values.

6. Copy your GitHub page url in this file as shown below.

7. Since the change was made to config file, we first update it by running the command to reflect the changes.

bundle update

8. Once the bundle gets updated, we can test it locally by running the command.

bundle exec jekyll serve

The page looks the same as before.

9. Push these changes to GitHub using git commands shown earlier.

10. Now refresh the page and voilà!

Here you go!! You have now the same format of the page as your local host url.

You can even confirm by clicking on the “About” or “Welcome to Jekyll” hyperlink , it opens another page with contents .

Hmmm!!! We did not add any content yet, how did those appear ?

Well here is how -

When you created a new jekyll site, it created a default gem based theme at the path specified . Since we used “.” (dot) and not any name , so you saw those files and folders appear in the root path.

Take a look at the about.markdown page , you can find the same content which is published on the website .

Yes, this is where you have to write your content specific to “About your page”

There is another hyperlink with the name “Welcome to Jekyll”. Notice that it is appearing below “Posts” section in the webpage.

Go back to your local repo and open the “_posts” folder , you see a markdown file with a date and welcome-to-jekyll. Open the file, and there is the content written for that page.

Notice in both “about.markdown” and “welcome-to-jekyll.markdown”, you see a block of lines with triple dash at the beginning and at the end of the block.

That’s called the Front Matter. Here, you can set predefined variables for the page and call them in liquid using page variables. Whatever value mentioned in the title in that block, is what appears in the webpage.

11. let’s try adding another page to the “_posts”.

📝 : the name of folder _posts should end with an “s” like _posts , and not _post. While, the value of the layout in the Front Matter should be “post” (without an “s”)

---
layout: post
---

Let’s add a file name “2021–05–29-how-jekyll-works.markdown” , and add some content in it.

Also let’s add a title of the Page in the “_config.yml” file.

Run “bundle update” and push the changes to GitHub.

Refresh the webpage to see the changes. If you can’t see immediately , wait for sometime and refresh it.

Awesome job!! Now we can see both posts appear in the webpage and can view the contents of the posts.

Convert Gem based theme to Regular based theme

I have used a gem based minima theme , which is internally referring to the minima-2.5.1 when you install Jekyll at the beginning.

Let’s check that out-

Run the below command to view the path of the minima installed.

bundle show minima

Navigate to this path , and you can see folders like _includes , _sass, _layouts, assets

Now let’s try not to point to gem based minima theme, and create a regular based minima theme.

1. Go to your repo project , open “_config.yml”, and search for the line
   “theme: minima”

# comment this line by adding hash at the beginning
# theme: minima

Open Gemfile , and comment these lines

gem “minima”, “~> 2.5”
gem “github-pages”, group: :jekyll_plugins

2. Copy all the below directories in the minima-2.5.1/ to your repo location in local. ( _includes, _layouts, _sass, assets directories)

You should be able to see those folders reflecting in your repo project in local.

3. Run “bundle update” for the changes to reflect.

4. Then run“bundle exec jekyll serve”

You might counter this error below.

In such case, add this in your Gemfile -

gem "jekyll-seo-tag", "~> 2.6"

After this change, run the command again and you will see a new local server address. This is because of the “url” value you provided in the “_config.yml” file earlier.

bundle exec jekyll serve

Open the server address url and view the page.
It shows the same page as we have seen earlier. The difference being- this time it is not referring from the gem based minima theme, but the regular based minima.
Let’s push this to GitHub and view the same.

Refer convert-gem-based-to-regular-based-theme for more info.

GitHub Pages Themes

You can also use other themes provided by GitHub from the GitHub Pages directly.

For that, navigate to Settings after creating an empty repo (as done earlier).

Go to Pages → GitHub Pages section → Theme Chooser subsection → Click on “Choose a Theme”.

You will see a page like this -

Select the theme of your choice and commit the changes.

View the page by clicking on the GitHub link created.

“git pull” these new commit to your local, add contents and push to GitHub to see your contents reflecting.

I hope this blog helped in someway for you to get started on setting up and creating your own website for your project.

I would encourage you to read Jekyll and GitHubPageWithJekyll .

Happy Learning!!