The Design Portfolio Workflow

A complete guide to code and deploy a site, all from the terminal

So I was updating my portfolio, editing some footer links on every page, and thought… WTF am I doing with my life?! Isn’t there a smarter way? I had my face in palm when James suggested I try Jekyll. My journey commenced from there.

I’m sharing a step-by-step guide because I think this portfolio workflow can be valuable to anyone who desires robust engineering capabilities without compromising their perfectionist design sensibilities. Designers love clean processes and systems, so why not apply that to our code?

I also hope this post shows code-curious designers you need not fear modern web development tools. Sound good? Let’s goooo!

What is Jekyll?

Jekyll is a “simple, blog aware, static site generator,” meaning you create dynamic content and templates locally (on your own computer), and Jekyll spits it out into static HTML and CSS files that you can upload to your hosted site. Each portfolio piece is treated like a blog post and is extremely easy to create and edit. It also has built-in server testing and Sass support.

Fast ✔ Clean ✔ Easy ✔ Full-featured ✔
K I’m sold.

Let’s build a portfolio!

Sound compelling? Let’s create and deploy a site together to demo the workflow. First, we’ll open the terminal and work with the command line.

Even if you don’t have much experience typing commands, you can manage by knowing the basics, like maneuvering around your computer’s folders. Learn the basics here and here. Otherwise, copy and paste ain’t a bad way to start learning.

Let’s install Jekyll! In the terminal, I’ve entered:

By default, the terminal starts in your computer’s root directory. You can see the files and folders by entering ls. I’m cool with my new portfolio living here, so I’ll enter:

Awesome! I now have a folder on my computer called my-site holding my portfolio. The command jekyll serve creates a server to preview your site at http://localhost:4000. I’ll keep this open in my browser.

Dive into the files

Let’s check out the structure of our Jekyll site by opening my-site in our text editor of choice. I was using Sublime Text for years, but recently switched over to Atom. It’s well-documented and the community packages are pretty badass — pigments, Emmet, and bezier-curve-editor to name a few.

For this guide, I’ll be using Atom. You’ll notice the folder directory pane on the left. Lemme break it down for you:

These are the defaults. Any folder with an underscore _ before it will not be built out. For example, when Jekyll builds your site, it won’t create a ‘posts’ folder. But it will build ‘index.html’ since there isn’t an underscore.

You can create any folder you want to organize your icons, thumbnails, Javascript, etc. It’ll be copied over to your generated site exactly as is. Do whatever feels comfortable for you. Here are some example folders:

Change your site settings

Jekyll includes this awesome file called _config.yml in your root directory. You can control just about any global settings for your portfolio here. Let’s open it up and personalize it!

I added a permalink setting to configure how I want my post URL’s to look (by default, it’s the date). I also added a dribbble_username variable.

Any time we edit _config.yml, we’ll need to reset the Jekyll server. So once we’re done editing, save the changes and stop the server via command line with ctrl-c. Enter jekyll serve again and take a look at localhost!

This flexibility is what makes Jekyll so fun and easy to work with. Let’s see how this concept is applied to our site posts.

Add our first post!

What good is a portfolio without a showcase of our work?! Let’s make a post about my side-project cat food delivery app, Food Right Meow. In the _posts folder, I’m going to create a new markdown file using the naming convention, ‘YEAR-MONTH-DAY-title.’ Thus, my post is titled ‘2016–01–12-cat-food-delivery.markdown.’

You’ll notice this chunk of content at the top of Jekyll’s intro post. Let’s copy that over to our new post and understand its awesome powers.

YAML front matter

Front matter is a powerful tool that defines variables specific to any page. The variables can be accessed anywhere via Liquid tags, which I’ll talk about soon.

Let’s edit our front matter at the top of the post between triple-dashes:

Jekyll has pre-defined front-matter variables, but you’ll get the most out of your templates by creating your own! Let’s see how our first post users the front matter:


So how does this all work? These front matter variables are being referenced in the HTML and markdown using Liquid, a very easy-to-use templating language. Liquid allows you to do logic, such as if/else statements and for loops, and assign strings to variables. The stuff in {{ }} or {% %} is Liquid doin’ work!

If you open up post.html in the _layouts folder, we’ll see it in practice.

By pre-pending ‘page’ to our variables, Liquid will search your page for the corresponding front matter in those triple-dashes. If it exists, we can write out the text stored in those variables to HTML. Amazing, right? More on variables here.

How about we add a few more of our own variables to the front matter to spice up our posts:

Now that we have all these awesome variables, how can we use them? Let’s edit our post.html layout template by using page.type and page.intro tags:

Cool! You can of course use CSS as you normally would to style all of your nifty tag outputs. Let’s try some more stuff. How about we add thumbnails for each post on index.html? Maybe its caption, too.

Hey, not too shabby. I’m sure you can already see how Jekyll will automate your site by using Liquid and YAML.

Actually writing the post

You’ll notice the .md or .markdown extension for your _posts. This is short for Markdown, a lightweight language that seamlessly converts plain-text into HTML. I’ve found that writing in Markdown syntax allows me to focus more on my content, rather than which tags to close.

The beauty of Markdown is that you can still use HTML wherever necessary. To render Markdown inside the HTML tags, add markdown=“1” and voila! The best of both worlds. Here’s some of the post when built:

Another .md post example

When I was migrating my old portfolio projects to Jekyll, I felt mixing HTML and Markdown looked clunky and defeated the purpose of Markdown’s cleanness. I created a demo that demonstrates what I do to achieve tidier posts while still maintaining desired styling! This is by no means a requirement or the right way to do it — just a technique for my neat-freak self. 😊 Feel free to download and play around with the files on GitHub.

Throw some CSS on it

Now that we’re familiar with Jekyll’s capabilities and have some content to work with, let’s add some styling! You can copy over CSS or Sass from your existing portfolio or start from scratch.


You probably noticed Jekyll projects come packaged with Sass files (the .scss extension). While you don’t need to know Sass in order to use Jekyll, it’s a well-loved and recommended tool in the CSS development workflow. Seriously, your CSS will be so much more organized and coherent once you adopt it. These beginner guides helped a lot when I first started. Jekyll has built-in support for Sass, so no reason not to convert. 😉

Version control with Git

Now that you’re accommodated with the terminal, I highly recommend using Git for version control of your portfolio. Git takes “snapshots” of your repository/repo — your project directory — every time you make a commit, so you can revert to older versions of your work whenever you need to. If you collaborate with another person, both of you can work on your own branch of the project and merge them back into master, the core project that all collaborators see.

Set up Git

Download and install Git. Back in the terminal, enter these commands (and add your own info between the quotes):

Great, we’re Git to go! But our project won’t have Git enabled until we initialize it. In the my-site directory, I’ll enter:

That was easy! Our new Git repo is empty, so let’s add all our files to it.

Great, our project is added to the local repo and is staged for commit. Let’s take a snapshot of the repo by making our first commit! Use -m followed by a meaningful message in quotes.

Our project officially has a history! Git works locally, but GitHub is a remote storage location to push our repositories to the web and share with the world. Let’s connect our local repository to a remote repository on GitHub and push our first commit.

Make a repository on GitHub

Now that we have Git initialized for our portfolio, let’s set up a remote repository on GitHub.

  1. Sign up for an account if you don’t already have one.
  2. Make a new repository.

3. Add a repository name and description. Create repository!

4. Now that you’ve created the repo, you’ll see this page on GitHub:

We want the “push an existing repository from the command line” bit. I’m going to copy that text and paste it in the terminal. git remote add origin connects the two repos to enable pushing. git push adds your local commits to the remote repository!

5. Refresh your remote repository and high five yourself! WE DID IT. Now the world can check out your cool portfolio!

For more in-depth explanations, this is a nice guide.

GitHub Pages

From here, you can take it another step further and setup your repository with GitHub Pages — a free webhost, no FTP required. Yup, this means you can commit and push your changes, and immediately see those changes live!

It’s a complete ecosystem, right from your trusty terminal.

More stuff I recommend

Because this guide isn’t already long enough.

Testing on mobile

Mobile testing is standard! Let Jekyll allow mobile access by running the server like this in the terminal:

Then, grab your local wifi IP and bind to the 4000 port. Altogether, you’ll type 192.168.x.x:4000 in your device’s browser. Learn more about how this works here.

Grid System

For a portfolio, a lightweight grid system is easy to implement and doesn’t get in the way of your CSS. I use Jeet because I like the syntax and its adaptability. There are tons of great ones though, like Neat and Toast.

Vertical Rhythm

Vertical rhythm is consistent spacing and scaling of paragraphs, margins, padding, font sizes, and line-heights. Setting the right rhythm improves legibility and flow of a site. I use modular-scale on my own portfolio. Learn more about vertical rhythm here and here.


And that’s how you create and deploy a beautiful and templated portfolio, all from the terminal. You only need to create a simple text post for new projects, and type a few commands to publish via GitHub Pages.

I hope you enjoyed building a portfolio for Food Right Meow with me. Creating/redesigning your portfolio should be fun and informative, so get typing and command lining!

Product designer @GitHub building inclusive communities, huge nerd, here for a e s t h e t i c, Splatoon 2 player

Product designer @GitHub building inclusive communities, huge nerd, here for a e s t h e t i c, Splatoon 2 player