Throughout the construction of this page, I thought it would be very helpful to record the creation of this page for future references. This tutorial will also be used to teach students within the CCNY ACM how to build their own personal portfolios. If you would like to build your own portfolio, continue reading!
What is Jekyll?
Jekyll is a simple, static site generator. It uses a template directory which contains raw text files in various formats (either markdown or html), and runs it through
Liquid converters, and outputs a static website ready to be served. Jekyll is also the engine behind Github Pages, and in this tutorial I will be demonstrating how to host your portfolio using
In order to start, first you’ll need to install jekyll via Ruby Gems. To install Jekyll, simply type into your terminal:
gem install jekyll. To test a working configuation of Jekyll, perform the following steps:
If you were successful in serving up that page, then we’re ready to move onto the next step.
In order to go through this tutorial, you’ll need to have the following skills/tools:
- Basic HTML/CSS/JS skills
- A Github account as well as the ability to clone a repository
- Understanding of your terminal and how to use it for creating/moving files around
At the end of this tutorial, your project directory structure should look like the following:
To clone a repository containing the final product, you can do so here.
Building your own portfolio
Now that we have jekyll up and running, we are ready to start our portfolio. Starting out, first navigate to a directory where you would like to store your files. For the sake of this tutorial, I’ll be working within the
Jekyll uses a
_config.yml file for setting up configurations that will be used across your site. For the sake of this tutorial, we will simply create
_config.yml as shown below:
Inside of this file we will simply put in:
The reason for this is that the
Maruku interpreter for Markdown has been deprecated, so we now use the
Choosing a Jekyll Theme
In this tutorial, I’ll be using the minimalistic theme. To put get it up and running, do the following:
Now we create a css file named
style.css, grab the code from here
and copy it into that file.
We need one more CSS file for our theme,
pygment_trac.css. Let’s create it:
As for the source code itself, you can grab it here.
Now that we have applied a new theme to our site, it’s time to start with some content.
Building our first template
Jekyll uses Templates, which are parsed and can be reused in multiple pages. We first start off with a default template,
Within our new
default.html file, we write the following code:
Between lines 1-4, we define a section which will be parsed by the markdown interpreter. All files will begin with this same format, each containing a
layout and a
layout here references our
default.html template we created earlier, and
title can be an arbitrary name, which will be reflected at the top of your browser. At this point, we have created our first page which we can navigate to!
As you’ve probably noticed in the
head of the above file, we included some
css/js files that we haven’t created yet. These are for using the image carousels, which we will create soon. For now, let’s gather the necessary files.
The source code for
jquery.bxslider.css is located here.
The source code for
jquery.bxslider.min.js is located here.
With that, we have all the
css/js files needed for the future.
Creating our home page
To host our webpage on
github pages, we’ll need to create an
index.html file within the root directory.
Within our new
index.html file, we place the following (duplicated code from the about page, except there is no title):
If you go into your root directory and perform the following steps:
You can now see your layout and new webpage! Currently, the
blog links to the left don’t do anything. Let’s get started with adding content!
Creating our first page
After creating our first template, we can now build our first page. Each page of our webpage will be inside its own folder, each with its own
index.html file within it. Let’s start with an
index.html page, we place the following code inside of it:
To navigate to your
about page, make the following change to
When you navigate to your
about page, you’ll see the following content shown below. We now move onto creating a
Creating a portfolio page
As mentioned earlier within this tutorial, each page of our webpage will live within its own folder along with a corresponding
index.html file. To begin:
portfolio/portfolio/index.html, we place the following code:
We must also link our new
projects page. To do this, make the following change inside of
With this, we have listed our first project! Let’s make it a little more fancy by adding an image carousel on top of each project. To do this, we will be using a jQuery plugin named
bxSlider. By requiring the necessary
js files within our
default.html template, all we need to add is the following to our
And within the
body of our page, we place the following code:
This is all that is needed to get an image carousel working! All that is left is to add the images into the designated folder path.
And now your first carousel should show the images you placed within the
To create new carousels, inside of the
head section in your
portfolio/portfolio/index.html file, you can create a new carousel like this:
Notice how each new carousel begins with
$('#slider(number)'). To create new carousels, simply switch the
number to a new one. These
numbers refer to the
div id, which allows us to manipulate the content within it.
Likewise, after initializing a new carousel, we need to actually place the content in it as such:
Where we also create a subfolder inside of
img which will hold some new images for our new carousel.
Putting it all together, here is our final
That concludes our portfolio page! It is easy to extend this page and add as many projects to it as you like, along with image carousels. The next page we will tackle is our
Creating our blog page
We now move onto what Jekyll was actually designed for: a blog. Even if you don’t like to write about technical things, you can still use this page to link to more detailed descriptions of your projects. These descriptions can vary from features, to challenges faced and experiences learned, and you can even include code snippets! These posts are great ways to show anyone who visits your page (from recruiters to friends) that you know what you are talking about, and can think critically about your project organization.
blog/index.html, we place the following code:
The above code loops over all files within the
posts subfolder within the
_site folder. The
_site folder is automatically generated when running
jekyll serve --watch, and we never interact with it. Also, each post will have a date which is parsed and displayed, and if an
image attribute is defined, then it will display the image as a banner. Lastly, the last lines in the above code will take the first paragraph of your post and display it, along with a
read more link that will take the user to the full post. Very powerful stuff.
To make the
blog link available, make the following change to
Currently, there are no posts. Before we create a post, we’ll need to create a new
template within our
_layouts folder to render our posts. Let’s create a new template
portfolio_entry.html within the
This template will render the contents of all our posts. It will grab the title of the post, as well as the date, image and content and render it on the page.
Creating your first post
markdown when creating posts, which is parsed and displayed. All of our
blog posts will live within a
_posts folder. Let’s create that now:
_posts/2014-10-10-firstproject.md, we place the following:
With this, we now have our
blog page set! To create more posts, simply create more
markdown files with the format:
YYYY-MM-DD-name.md within the
_posts folder. With our
blog/index.html file, it will automatically populate our blog page with all blog posts due to the
for loop which iterates over every post we have!
We now move onto our last page, the
Creating a contact page
As we already know from all the previous steps, we need to create a new folder called
contact and within, we create an
index.html file. To begin:
contact/index.html, we place the following code:
And to navigate to the
contact page, we make the following change to
And that concludes all of the pages! We have successfully created a full personal webpage. All that is left is to add your own contact, links and whatever else you like! We now move onto deploying our web page on
Deploying your webpage
After coming this far, we are ready to deploy our new portfolio. To do so, you’ll first have to create an account on Github, it is free to join. We then want to create a new repository by clicking the top right plus sign, and click
create new repository. You’ll then be taken to this page:
repository name field, provide the name using the format:
accountname.github.io. This will allow Github to know that this page should be served. After creating this repository, you’ll need to clone it. Navigate to your repository, and clone it by copying the link shown in the red box below:
Copy the link, and inside of your terminal:
url is the one copied to your clipboard.
After cloning your repository, you’ll need to copy all of your files from your
portfolio folder and put it into your new cloned repository. Simply copy every file inside of
portfolio/ and paste it into
your_new_repo_folder. To do this, you can do the following in your terminal:
The above bash command will copy all files within
portfolio/ into your
cloned_repo_folder/. Now, we simply perform the following steps:
This will push up all of your files for your new repository. It takes a few minutes to take effect, but you can visit your new web page at
accountname.github.io! I hope this tutorial was helpful for anyone who attempts to use it. Enjoy your new personal web page!