Step-by-step guide to help you save time and effort
In this article, I will share the process of building my personal website and portfolio using Jekyll. Jekyll is a Ruby gem that is easily used to create static websites whose content is predetermined at creation time and does not depend on any live user input or database connections.
Since I am not a web designer and do not want to spend time designing in CSS and HTML, I searched for a good and impressive template and stumbled upon Beautiful Jekyll (https://beautifuljekyll.com/) by Dean Attali I will adapt this post. This is my site – https://erap129.github.io, which we will learn to build, and this is the repository of the site – https://github.com/erap129/erap129.github.io.
This article will be organized as follows:
- Requirements — What do I want/need from my site
- setup and installation
- website creation
- website deployment
Before starting work, I had defined my main goals for this website. Necessary:
- Give general information about me, such as my interests, projects and hobbies, to potential and existing clients/colleagues/employers.
- A page with previews of all my articles on Medium and a link to them on the Medium platform is included. This page doesn’t have to be created manually, as I plan to continue writing on Medium, and I don’t want to copy and paste my posts to my personal website every time. Plus, it should be updated automatically so that I don’t have to update my site every time I post on Medium.
- Include additional static pages – such as my scientific publications, public code contributions, and perhaps more.
It’s important to say – Beautiful-Jekyll is an awesome template. If the site structure defined by this template is right for you and you don’t need integration with Medium – just skip my article and follow the official instructions.
I really liked the design of this template, but in order to build integration with Medium, I needed to do a lot of customization. For this, I needed the ability to deploy the site locally, which is the purpose of the following installations:
This document – https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll provides an excellent explanation Here’s how to set up your environment to work with Jekyll and the Github page, but I’ll go over the main steps here as well. I will assume that you are using Ubuntu Linux (if it is not – follow the instructions in the link above as per your OS).
- First install ruby-
sudo apt-get install ruby-full
- Now install bundler –
sudo gem install bundler
- Fork beautiful-jekyll – steps are written here -https://github.com/daattali/beautiful-jekyll#readme. they are:
1. Fork as Project
2. Clone the Project to Your PC
- To run the website locally, navigate to the local repository folder in Terminal and run
bundle install, This will install the necessary Ruby software that is used to run and serve Jekyll. Now every time you want to serve a locally running website
bundle exec jekyll serve, Congrats! will be available on website
These are the things I would do to adapt the Jekyll template to my needs:
- Create a “blog post” page that will be integrated into Medium
- Create additional Markdown-based pages: Home and Publishing
Let’s get started!
Create a “blog post” page
The first question is – how do we get information through the medium? The answer is – RSS! Medium has one RSS feed per author, which allows me to access information on all my articles using a simple URL (for me, this is https://medium.com/feed/@erap129).
I really liked how posts are shown in Pretty Jekyll, but in my case, I don’t want each preview to be linked to an internal post, but to the original post on Medium.
To generate content dynamically in Jekyll, we will need to create a generator plugin. Plugins in Jekyll are bits of Ruby code that run when you build your website and perform various tasks. Our generator will collect all my Medium post information and store it in an archive that we will use in our site’s HTML code.
Let’s create a folder named
_plugins in the main directory of our repo, and create a file called
jekyll-display-medium-posts-json.rb With the following ingredients:
This plugin is an extension/modification of the plugin presented by James Hyman in the post – https://medium.com/@jameshamann/displaying-medium-posts-on-your-jekyll-website-7eef230309e4.
Let’s move on to the code:
- In line 10, we create a new collection called . is called
medium_posts_json, We may use this name throughout the site’s code to access our posts.
- In line 12, we call the API of rss2json. The JSON format gives us better control over the content received through the medium, and thus we use this API to convert the XML format of the medium to JSON.
- In lines 18-33, we collect the information we’ll use in our “Blog Posts” page – the title, image, link, and date of the articles (we also collect categories but don’t use them)
- Note that we are using
nokogiriRuby gem to parse HTML content in line 31. Why? Since the description of each post in the RSS feed is raw HTML, we want to make a brief excerpt of the post here. To skip header and image – we extract only paragraphs (which are in)
ptags in HTML).
It is important to add the following snippet to
_config.yaml, Otherwise, the archive created by the generator will not be available for use in the Site:
Now, we need to create a layout that will use this information and convert it into HTML code provided by the browser. We will create a new file named
_layouts Directory with the following contents:
This layout is basically a disassembled version of the original layout in pretty-jekyll – https://github.com/daattali/beautiful-jekyll/blob/master/_layouts/home.html. The only change I made was to remove the irrelevant content and make the layout use the collection I created earlier –
- Note in line 5 that we iterate over the collection we created using our plugin and add the necessary HTML code for each element. Jekyll uses a syntax called Liquid to generate this content. You can read more about Liquid here – https://shopify.github.io/liquid/.
Now, we just need to create a new file named
blogposts.md in the main directory, and have it use the new layout we just created –
---layout: blogtitle: Blog Postssubtitle: This is what keeps my mind busy---
navbar-links in Section
_config.yaml To include new blog posts page.
Great! If I now serve my website locally
bundle exec jekyll serveI need to be able to access my site
http://localhost:4000 And see the changes I made.
2. Create Additional Markdown-Based Pages
Now, since we have added a blog posts page, we no longer need a homepage to list local blog content. Additionally, we want the home page to be easily editable using Markdown instead of HTML.
Thus, we will remove
index.html and replace with
index.md, I have added personal information about myself to this page, but you can do whatever you want. I added one
publications.md Page in which I list my scientific publications.
navbar-links my . section in
_config.yaml looks like this:
navbar-links:Home: "index"Blog Posts: "blogposts"Publications: "publications"
once we get to the point where we run
bundle exec jekyll serve And as we see, we’re ready to deploy.
We want our site to be deployed in two cases:
- When we push new/updated content to master branch of repository
- We want to integrate into the site whenever a new post is added to Medium.
For 1 will be easy, and for 2, we will make it a daily process. This means that at a set time each day, the creation process for the website will be created, and if I have added new content to my Medium profile, it will land on the website.
We cannot rely on the default GitHub Pages deployment actions for this because we are using custom plugins, which GitHub Pages does not officially support. Also, we want the build process to happen on time and not just based on pushing the master branch. For this, we’ll be using this custom GitHub action from the market called Jekyll Actions – https://github.com/marketplace/actions/jekyll-actions.
The link above has a very helpful tutorial, but I’ll still walk you through the steps required to activate this action. From the root directory of the site, I created the following file:
.github/workflows/github-pages.yml With the following ingredients:
Let’s see what we see here (interesting bits)
- In lines 4-8, we define when the site deployment will take place – on a push event for the master branch and every day at midnight. I’m doing this to manually edit my website if I want to, but if I publish new content on Medium, I won’t need to edit it.
- Note that in lines 23 and 26, I mention a mystery called
JEKYLL_PAT, To set this up, I created a GitHub Personal Access Token – https://github.com/settings/tokens with full repo access and added it to my project settings (Repo Page -> Settings -> Secrets -> Actions) Added as a secret to) )
- The rest of the code was taken from the original GitHub action and is fully explained here – https://github.com/marketplace/actions/jekyll-actions.
Another important step is to set the deployment branch to
gh-pages (the branch to which the static content is being pushed) So GitHub will know to host files from this branch. I would like to give special thanks to Christian from Stackoverflow who helped me solve an issue regarding this – https://stackoverflow.com/questions/74244454/helaili-jekyll-action-does-not-update- the-browser-with-d-page-branch-content. This is done through repository settings like this:
Of course, you can continue to customize your website endlessly, and I didn’t notice the little things I’m sure you’ll be able to figure out, such as changing the website title, your own photo adding, and more.
_config.yaml The file is very self-explanatory and allows for easy manipulation and customization.
Thanks guys! encourage.