Building a Portfolio Website w/ Ruby + Jekyll

 · 8 mins read

A Brand New Day, A Brand New Website

Well what kind of software developer doesn’t have a website?! How else are you supposed to share your work and learnings?! I’m Damien, you can call me Damo. This is my website. This article is focused on telling you why this website exists and why you need to make one for yourself. It’s easy, it’s only computer science! ;)

If you need help, holla at ya boy.

Why do you need a portfolio website?

Your portfolio website should be a reflection of your second self, the root of your digital presence. It should showcase a true glimpse into who you are, and what you are capable of. Why do you need it? I like getting paid, do you like getting paid? Most interviews ask you for a resume. A portfolio website is like a resume but interactive. You should probably make a portfolio website so people see what they can pay you for.

Why not use one of those website builders I see on commercials?

  • They’re slow
  • This isn’t that hard
  • That monthly subscription can be repurposed as beer money

Prerequisites

You’ll be installing Ruby and the Ruby gems needed later down the page.

You’re going to need a knowledge of:

  • HTML
  • CSS
  • Github repos
  • Markdown
    • If you don’t know markdown, take a moment to read this cheat sheet. It’s incredibly easy to take notes in markdown (.md files). All of my notes are written in this simple language. It takes a simple hierarchically organized file and turns it into this pretty html page you’re literally reading right now.

This isn’t a project for those who don’t have any software experience. Web development has a lot of little quirks and specific syntax. There were more than a few times the solution to a weird bug was due to an extra space… Yeah.. and extra one of these “ “ sent me hunting through code for a nearly invisible error.

How do I start?

I’m not going to bullshit you, this took me a few days to get the hang of. There were a lot of little hiccups that threw me for a loop but I’m happy I pushed through it. After a few days of banging my head against the keyboard, I can upload new blog posts and store items with very little overhead.

Step I: Skim the documentation

Before you start any project you should at minimum skim the associated documentation. The more time you spend reading the docs and understanding your tools now, the faster you’ll be able to develop later.

  • “If all you have is a hammer, every problem looks like a nail.” - someone.
  • “How do you expect to start building if you don’t know what equipment is in your toolbox?” - Damo.

You don’t have to read every sentence of the official Jekyll website… yet. Skim the docs. Look around and get a feel for what’s there. I’m going to step you through what you need to get started. If this website scares you, you should stop here and holla at ya boy. I’ll knock a website out for you for a few stacks and a chicken tender pubsub.

Step II: Set up your development environment

Step II.a Install Ruby

  • You can go to the official Ruby website and select a version of Ruby or you can click here to initialize the Ruby download I used.
  • When the download is complete, locate and run the .exe.
    • accept the license, click next through everything unless you have a specific location you want to install to. Press finish.
    • Ruby will open a command prompt window (aka the console). Press 1 then enter, wait for it, press 2 then enter, wait for it, press 3 then enter.
    • Close the command prompt, and open a new one. (Windows key –> typing “cmd” –> enter is how I open it)
      • Whenever you install new software for the console, you need to restart it for the changes to be applied.
    • type the command ruby --version and press enter.
    • if you get a response like ruby 2.5.3p105 (2018-10-18 revision 65156) [x64-mingw32] then you’re good to proceed. Otherwise start over.

Step II.b Check and Update Ruby Gems

  • Run gem --version in the console. Open Ruby Gems Official download page and compare the latest version number to what was printed in the console. At the time of writing this, version 2.7.6 was installed with Ruby but 2.7.7 has been released so I’m going to update mine by running the command gem update --system.
  • Allow access to your firewall when it asks.
  • The console will start printing out information as it installs the Ruby gems update.
  • Close and reopen your console.

Step II.c Install the Jekyll gem

  • At this point, you’re ready to start with the Step by Step tutorial that Jekyll has on their website. I’d encourage you to finish with my article to get your site up and then go through this tutorial to really understand the innerworkings.
  • In your freshly reopened console, run gem install jekyll bundler and watch as all sorts of fun dependencies get installed.
  • If you get prompted for overwriting, I selected y for yes.
  • Run jekyll --version to verify your install was successful.
  • Close your console.

Step II.d Install npm dependencies

  • NPM = Node Package Manager
  • go to Node.js and install the latest version
  • open your console and run npm install -g windows-build-tools
  • when finished, run npm install --unsafe-perm node-sass

Step III: Pick a theme that represents you

  • Select a theme. My criteria wasn’t just visual. I picked Jekyll-sleek because it offered an optimized load time and pre-integrated features like SEO and Disqus chat.
  • Navigate to the GitHub repository for the theme you’ve picked.

Step IV: Fork it. Clone it. Change it.

  • Sign in to your GitHub Account.
    • If you don’t have an account, make one. You’re going to need it to keep your site up to date.
  • In the top right of the GitHub repo of the theme you’ve selected is a fork button.
    • When you click this, a copy of the project will be made to your personal git repositories. This means you’ve got your own copy to do whatever you want with.
  • Clone the project to your computer. Read how to do that here.
  • Open a new console and navigate to the directory you’ve cloned the theme project into.
    • On Windows, you can use dir to view what is in your current directory and cd "folderName" to change directory.

Step V: Required Gemfile

Next we need to make a gemfile in the root of our project. This means it’ll go in the folder with “_config.yml”. The Gemfile defines the dependencies you’ll be incorporating into your project so the Jekyll bundler knows what to install.

  • Open a text editor (I use and suggest Atom).
  • Make a new file, paste the following in it, and save it in the root directory as “Gemfile”. Note there is no file extension.

    source "https://rubygems.org"
    
    gem 'wdm'
    gem 'jekyll'
    
    group :jekyll_plugins do
      gem 'jekyll-sitemap'
      gem 'jekyll-feed'
      gem 'jekyll-seo-tag'
    end
    
    # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
    gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
    
  • Run bundle install for the Jekyll bundler to install the dependencies.

Step VI: It’s alive!!!

  • Run bundle exec jekyll serve and navigate to http://localhost:4000. Don’t worry this is only live on your computer, it isn’t on the internet yet.

Step VII: Customize

Do yourself a favor and open http://localhost:4000 in an incognito window. It’ll help with weird caching issues during development.

  • Get in there and read the code.
  • Change the logos to your logos.
  • Change the names to your names.
  • Add widgets.

Step VII: How to make your website accessible to the world

GitHub is awesome enough to host your website for you for free. All you have to do is update the code on your GitHub account (also called the Remote) to match what is on your computer (aka local).

  • Using GitHub, push the changes and your website will be live at “username.github.io” For example mine is available at dgilliams.github.io but I have it permanently redirecting here to www.DamosDesigns.com since I prefer that domain.

Step IX: Go forth and create!

Start uploading blog posts and share your brand and portfolio with the universe. Good luck.

Troubleshooting

With web development there are a lot of dependencies. Sometimes set up on a new machine simply doesn’t match another.

gulp img errors

Error in Plugin “Gulp-imagemin”

<ROOT>\gulp img [19:50:30] Using gulpfile <ROOT>\gulpfile.js [19:50:30] Starting 'img'... [19:50:31] 'img' errored after 240 ms [19:50:31] Error in plugin "gulp-imagemin" Message: The system cannot find the path specified.

I had this issue moving my website to my laptop in order to edit on the go. If you find yourself getting this error

  • use cd to navigate into the node-modules directory
  • run npm i
  • run npm audit
  • review issues
  • run npm install --save-dev gulp-imagemin@5.0.3