GitLab Pages 101 For Designers

Publish your design portfolio on GitLab pages using Jekyll

We are about nine months into a pandemic, with still no knowledge of how far along we are in the larger timeline. Jobs across industries around the world have been affected and governments are struggling with policies to get the economy back on its feet. Needless to say that the design industry is not faring well to the situation either. The previous month designweek.co.uk released some findings from their recent survey within the UK to understand the impact of the pandemic on the design industry and the statistics do not look so well.

What we do know, however, is that plenty of designers are still out of work — when asked, 56% of respondents reported being on furlough and not knowing when they would be brought back into the studio.

Irrespective of the number of years spent in the industry, if you’re a designer, your portfolio is your identity. Unlike most of the other professions, it is imperative for a designer to ensure visibility for their work to attract potential opportunities, and more so now than ever. By showcasing their work to potential employers and businesses, designers could also exhibit how their work extends beyond vanity and cannot be treated as a dispensable part of their product if they want to do good business especially in such hard times.

Portfolio websites are a great way to showcase design work and lay out the process in a highly personalised setting. However, the cost for hosting, designing and publishing a decent portfolio site using no-code tools and platform such as WordPress, Wix and Webflow, is not affordable for all, and more so under current job market situation. There is absolutely no dearth of options for hosting your website for free but they come with a lot of limitations and sometimes with an un-predictable hidden cost.

I was introduced to GitLab Pages during my onboarding at GitLab as a product designer, but honestly, I did not act on it until it was time for me to renew my web-hosting subscription. On further reading and asking around I became aware of a popular and reliable static site generator called Jekyll which is compatible with GitLab Pages, is easy to maintain and is supported by a large community, ensuring a good number of plugins being available for various requirements and use cases.

In this blog, I’ll take you through the process that finally worked for me when I started to created my portfolio website on GitLab Pages from scratch using Jekyll(a static site builder).

Prerequisites

1. Create an account on gitlab.com
2. Install Atom code editor
3. Purchase a domain (optional)
4. Install command line tools on your computer by typing the following in the terminal

$ xcode-select — install 

5. Install git on your computer

$ brew install git

6. Install home-brew

/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)”

1. Create a new project

Go to gitlab.com and click on Create new project. From the options that follow, select Create from template to see a list of templates available for use. From the list, use the template Pages/Jekyll to create a new project.

2. Set up your SSH key

Generate an SSH key and add it to your GitLab account. The SSH key allows you to have secure connection between the remote and the local system for safe exchange of information. Read more about the process here.

3. Clone the project to your local

Once the project is created, Clone it to your local(computer) using SSH URL.

Open the terminal on your computer and enter the following command:

git clone <paste_the_copied_URL_here>

Now you have a local copy of your website in your computer.

4. Find a suitable theme

It’s shopping time! There are many sources to go look for Jekyll themes, but my to go website is jekyllthemes.io. Browse through the available catalogue of themes — both free and premium and download the .zip folder for the selected theme to your computer. If the theme is hosted on a GitHub repository, go to the repository and from under the Code dropdown, click on Download ZIP.

On unzipping, the structure of files inside the extracted folder should look like this:

5. Apply the theme

Copy the content of the downloaded theme to your recently cloned folder for the website. Choose to replace all the folders and files with similar names, when prompted.

You would notice that there are still some files which are unaffected in the cloned folder, and a very important one of them is .gitlab-ci.yml. This is the file that defines the configuration for your GitLab CI/CD pipeline. One of the benefits of using GitLab Pages, besides being able to keep your project private for added security, is being able to leverage the power of GitLab CI/CD. (Read more about it here.

6. Install Jekyll

Installing Jekyll on your computer would allow you view the changes you make to your website locally before you push them to the remote project (on the web) to publish them.

If you’re using MacOS/Linux, go back to the terminal and execute the following commands in order:

$ brew install ruby
$ echo ‘export PATH=”/usr/local/opt/ruby/bin:$PATH”’ >> ~/.bash_profile
$ gem install — user-install bundler jekyll

If you get stuck at any point, look into the installation guide published by Jekyll on their website.

Time for a dry run 🙆‍♀️ Execute the following to build your website locally and view it on a local host:

$ cd <name_of_the_cloned_folder>
$ bundle exec jekyll serve

This will give you a local host address to view your website structure on: http://localhost:4000.

Go to the local host address and preview your website live.

7. Edit your website

What we have until now is just the template structure for the website. To start editing and customising your website, go to Atom editor and open the cloned folder of the project on your local. This is the structure you should see:

To add or edit a blog post, duplicate the sample file under _posts. And to add a project to the portfolio/project page, duplicate the sample file under _projects ensuring you follow the established format for naming the new file. Keep the _Readme.md for the theme handy for instructions on what to do and most importantly what not to do in the layout. For starters:

• make sure you do not remove or edit the top section in the post and project file that relates to the configuration of the website and looks something like this:

• A single space mismatch in this section, the _config.yml and the settings.yml file could break the build of your website.
• Add all the images that you would need for your blogs and projects to the image folder and always make it a point to provide understandable and identifiable names to your file so you don’t reference the wrong file going ahead
• Whenever in doubt, save the changes you make, go back to terminal, make sure you are inside the website folder, and run $ bundle exec jekyll serve. If you don’t approve of the changes that appear in the local build spinner up on your local host, come back to atom and undo your edits and save again

To be able to effectively deal with markdown and control you website content like a pro, learn a few markdown syntaxes here.

8. Publish your website

If you have added your content to the website folder and are ready to take your work to the world, it is time to push the changes to the remote repository. In the terminal, make sure you are inside the folder and execute the following commands in sequence :

$ cd <name_of the_cloned_folder>

Check the status of the changes files
$ git status

Add all of the changed files to the stage
$ git add -A

Commit the staged files
$ git commit -m “A message to summarise the commit”

Push the content to the remote repo
$ git push origin

9. Configure Pages in GitLab and build

On your website project on GitLab, from the left-hand-side navigation panel, go to Settings >> Pages. Check the box for Force HTTPS and click save.

Now navigate to CI/CD>>Pipelines and on the page that appears, click on Run Pipeline button. Doing this would start the build process for your website and after sometime when you go back to Settings >> Pages, you will find a link to navigate to your published website.

10. Connect your purchased domain

Most likely, you have your own amazing domain that you would like to use for your website. To get started with the process of connecting your website with your GitLab pages website, you would also need to keep open the Manage DNS page open on your domain registrar’s website.

• Go to the Settings >> Pages and click on New Domain
• Enter the name of the new domain in the field and Create New Domain
• From the Verification status section in the Pages Domain page, copy the content on the right-hand-side of TXT

• Add two records manually to the domain settings, for A and TXT respectively. Enter the values for the A record as shown in the image above, and for the value of TXT use the text copied from the previous step
• After saving the two new entries on the domain registrar website, go back to the Pages Domain page and click on the icon next to Unverified. If the details are entered correctly in the previous step, the domain would show verified

Allow some time for the new settings to kick in and for the pipeline to run once after the new changes then go to your domain to see your published website 🎉 Congratulations! 🥳

The process seems lengthy and might not go as smooth as the written documentation, but once you get through the basic hurdles, it all seems worth because of the control this structure and method provides you over your content. Since I’m a new learner myself, reach out with any queries and I’d be happy to help you troubleshoot your way into a live and published website 🤗.

Additional updates

To get my website to run successfully, I had to additionally include the Gemfile.lock to the .gitignore file before pushing the changes to the remote project from my local.