Portfolio Jekyll Theme
This is a Jekyll theme built using the DevTips Starter Kit as a foundation for starting, and following closely the amazing tutorial by Travis Neilson over at DevTips. The purpose of this theme is to provide a clean and simple website for your portfolio. Emphasis is placed on your projects, which are shown front and center on the home page.
Everything that you will ever need to know about this Jekyll theme is included in the README below, which you can also find in the demo site. For a guide on how to start a blog or personal website using Jekyll and GitHub Pages, please check out this article.
Compatible with GitHub Pages.
Support for Jekyll's built-in Sass/SCSS preprocessor and data files for making customizing easier.
Google Analytics support.
Commenting support powered by Disqus.
Optimized for search engines.
LaTeX support through MathJax.
Table of Contents
- What is Jekyll
- Never Used Jeykll Before?
- GitHub Pages Installation
- Local Installation
- Directory Structure
- Starting From Scratch
- Sample Posts
- Site Variables
- Adding Menu Pages
- YAML Front Block Matter
- Design Considerations
- Google Analytics
- RSS Feeds
- Social Media Icons
- Syntax Highlighting
- Everything Else
Portfolio Jekyll Theme is a Jekyll theme that was built to be 100% compatible with GitHub Pages. If you are unfamiliar with GitHub Pages, you can check out their documentation for more information. Jonathan McGlone's guide on creating and hosting a personal site on GitHub is also a good resource.
What is Jekyll?
Jekyll is a simple, blog-aware, static site generator for personal, project, or organization sites. Basically, Jekyll takes your page content along with template files and produces a complete website. For more information, visit the official Jekyll site for their documentation.
Never Used Jekyll Before?
The beauty of hosting your website on GitHub is that you don't have to actually have Jekyll installed on your computer. Everything can be done through the GitHub code editor, with minimal knowledge of how to use Jekyll or the command line. All you have to do is add your posts to the
_posts directory and edit the
_config.yml file to change the site settings. With some rudimentary knowledge of HTML and CSS, you can even modify the site to your liking. This can all be done through the GitHub code editor, which acts like a content management system (CMS).
GitHub Pages Installation
To start using Portfolio Jekyll Theme right away with GitHub Pages, fork the Portfolio Jekyll Theme repository on GitHub. From there, you can rename your repository to 'USERNAME.github.io', where 'USERNAME' is your GitHub username, and edit the
settings.yml file in the
_data folder to your liking. Ensure that you have a branch named
gh-pages. Your website should be ready immediately at 'http://USERNAME.github.io'. Note: if you are hosting several sites under the same GitHub username, then you will have to use Project Pages instead of User Pages - just change the repository name to something other than 'http://USERNAME.github.io'.
Head over to the
_posts directory to view all the posts that are currently on the website, and to see examples of what post files generally look like. You can simply just duplicate the template post and start adding your own content.
For a full local installation of Portfolio Jekyll Theme, download your own copy of Portfolio Jekyll Theme and unzip it into it's own directory. From there, open up your favorite command line tool, enter
bundle install, and then enter
jekyll serve. Your site should be up and running locally at http://localhost:4000.
If you are familiar with Jekyll, then the Portfolio Jekyll Theme directory structure shouldn't be too difficult to navigate. The following some highlights of the differences you might notice between the default directory structure. More information on what these folders and files do can be found in the Jekyll documentation site.
Portfolio Jekyll Theme/ ├── _data # Data files | └── settings.yml # Theme settings and custom text ├── _includes # Theme includes ├── _layouts # Theme layouts (see below for details) ├── _posts # Where all your posts will go ├── assets # Style sheets and images are found here | ├── css # Style sheets go here | | └── all.sass # Main SASS file | └── img # Images go here ├── pages # Menu pages ├── projects # Project pages ├── _config.yml # Site build settings ├── Gemfile # Ruby Gemfile for managing Jekyll plugins └── index.md # Home page
Starting From Scratch
To completely start from scratch, simply delete all the files in the
menu folder, and add your own content. You may also replace the
README.md file with your own README. Everything in the
_data folder and
_config.yml file can be edited to suit your needs. You may also change the
favicon.ico file to your own favicon.
Visit the the demo site to find sample posts that show what different types of text formatting look like. You can find these posts in the
_posts folder, which show what the best practices for setting up your own site are.
To change site build settings, edit the
_config.yml file found in the root of your repository, which you can tweak however you like. More information on configuration settings and plugins can be found on the Jekyll documentation site. This is also where you will be able to customize the title, description, and the author/owner of your site.
If you are hosting your site on GitHub Pages, then committing a change to the
_config.yml file will force a rebuild of your site with Jekyll. Any changes made should be viewable soon after. If you are hosting your site locally, then you must run
jekyll serve again for the changes to take place.
settings.yml file found in the
_data folder, you will be able to customize your site settings, such as setting Disqus comments, Google Analytics, what shows up in your menu, and social media information.
Adding Menu and Project Pages
The menu pages are found in the
menu folder in the root directory, and can be added to your menu in the
settings.yml file. Similarly, the project pages are found in the
projects folder in the root directory, and can be added to your site in the
settings.yml file. The images for your portfolio projects are stored in the
assets/img/projects/proj-n folder, and should be named
You will find example posts in your
_posts directory. Go ahead and edit any post and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run
jekyll serve, which launches a web server and auto-regenerates your site when a file is updated.
To add new posts, simply add a file in the
_posts directory that follows the convention of
YYYY-MM-DD-name-of-post.md and includes the necessary front matter. Take a look at any sample post to get an idea about how it works. If you already have a website built with Jekyll, simply copy over your posts to migrate to Portfolio Jekyll Theme.
There are two main layout options that are included with Portfolio Jekyll Theme: post and page. Layouts are specified through the YAML front block matter. Any file that contains a YAML front block matter will be processed by Jekyll. For example:
--- layout: post title: "Example Post" ---
Examples of what posts looks like can be found in the
_posts directory, which includes this post you are reading right now. Posts are the basic blog post layout, which includes a header image, post content, author name, date published, social media sharing links, and related posts.
In addition to the two main layout options above, there is also a custom layout that have been created for the home page. These are simply just page layouts with some Liquid template code. Check out the
index.html file in the root directory for what the code looks like.
YAML Front Block Matter
The recommended YAML front block is:
--- layout: title: ---
layout specifies which layout to use, and
title is the page or post title. Have a look at some posts in the
_posts directory to see how these variables are set.
Portfolio Jekyll Theme was designed to be a minimalist theme in order for the focus to remain on your content. For example, links are signified mainly through coloured font, in order to maximize the perceived affordance of clickability (I originally just wanted to make the links a darker shade of grey).
Portfolio Jekyll Theme supports comments at the end of posts through Disqus. In order to activate Disqus commenting, set
disqus.comments to true in the
_data/settings.yml file. If you do not have a Disqus account already, you will have to set one up, and create a profile for your website. You will be given a
disqus_shortname that will be used to generate the appropriate comments sections for your site. More information on how to set up Disqus.
It is possible to track your site statistics through Google Analytics. Similar to Disqus, you will have to create an account for Google Analytics, and enter the correct Google ID for your site under
google-ID in the
settings.yml file. More information on how to set up Google Analytics. Note: If you are not using Google Analytics, please change
google-ID to an empty string.
Atom is supported by default through jekyll-feed. With jekyll-feed, you can set configuration variables such as 'title', 'description', and 'author', in the
Social Media Icons
All social media icons are courtesy of Font Awesome. You can change which icons appear, as well as the account that they link to, in the
settings.yml file in the
Portfolio Jekyll Theme provides syntax highlighting through fenced code blocks. Syntax highlighting allows you to display source code in different colors and fonts depending on what programming language is being displayed. You can find the full list of supported programming languages here. Another option is to embed your code through Gist.
As always, Jekyll offers support for GitHub Flavored Markdown, which allows you to format your posts using the Markdown syntax. Examples of these text formatting features can be seen below. You can find this post in the
_posts directory as well as the
If you would like to make a feature request, or report a bug or typo in the documentation, then please submit a GitHub issue. If you would like to make a contribution, then feel free to submit a pull request - as a bonus, I will credit all contributors below! If this is your first pull request, it may be helpful to read up on the GitHub Flow first.
Portfolio Jekyll Theme has been designed as a base for users to customize and fit to their own unique needs. Please keep this in mind when requesting features and/or submitting pull requests. Some examples of changes that I would love to see are things that would make the site easier to use, or better ways of doing things. Please avoid changes that do not benefit the majority of users.
This theme is completely free and open source software. You may use it however you want, as it is distributed under the MIT License. If you are having any problems, any questions or suggestions, feel free to tweet at me, or file a GitHub issue.
- Be the first to contribute!
Icons + Demo Images
Open sourced under the MIT license.