Between Squarespace and Replit, I was spending $45 a month to have a site for Git Cute and one for my personal portfolio page. I enjoyed the custom terminal that I built, but realistically, a portfolio is supposed to show a recruiter, potential client, or anyone who you are without fanfare. That’s when I remembered that GitHub Pages was an option. I knew that there were going to be restrictions in terms of bandwidth and technologies used. I’m not a front end engineer and have never pretended to be, so I took on the challenge of the migration.
This project took me roughly 2 days to complete from design, implementation, and content migration. The thing that saved the most time was to use Jekyll, a static page builder that already has inherent support for GitHub Pages. Learning a new technology and it will save me time and headaches in the end? A win/win.
The Constraints
Now, GitHub is straight-forward when it comes to the constraints that they implement, especially if you want to take advantage of absolutely free hosting. These are the ones that I care the most about:
- GitHub Free repos must be public
- Published sites must be < 1GB
- Bandwidth limit of 100GB
I quickly got over my apprehension of someone being able to see or fork any content from the repo of my portfolio because this is exactly what .gitignore intended for. The limitations for the size of site and bandwidth were of minimal risk to me because that signaled to me that what I design would need to have zero images and keep it to CSS, Sass, and vanilla Javascript. Challenge accepted.
The Jekyll Theme
The thing that slowed me down the most in the process was the theme design. I am both terrible at implementing but particular about how I want myself represented on the Internet. I love anything that involves millenial pink, magic girl, and my current hyperfixation of Frieren and her favorite magic spell. I wondered, “Can I implement this with one of Jekyll’s base themes” The answer was no: Minima or the others would not be able to cover this.
Note: There’s a limited list of Jekyll themes that work with GitHub Pages!
GitHub’s list of supported themes and also has a Ruby Gem where you can install other themes that you find hosted on GitHub, so you don’t have to be difficult like me and build something from scratch unless you absolutely can’t find something that suits your needs.
This is where I used Claude to save time with design implementation. I had looked at other engineer’s GitHub Pages portfolios that I liked as ideas and took small elements from a number of them to come up with something simplistic but would still implement. The most complex part of the design would be the cherry blossom flowers that had to be made with Javascript, but they are the aspect of the idea that I enjoyed the most and became the centering motif for my page.
To Save You Time
To reiterate, I spent 2 days building my portfolio out to my MVP, but that included a few hours of research through the process. Here are the things that I encountered during my build that I found to be the most useful and some that may have taken up more of my time than I care to admit.
1. Sass Rules Deprecated
When you are building your Jekyll site locally, you will see the Sass warning of @import rules are deprecated. Ignore this. The version of Jekyll will not allow you to implement @use petal. I am saving you 20 minutes of frustration that I could not save myself from.
2. Hide your _site folder
Your _site folder is where the build artifacts for your project live. To avoid wondering why your .scss isn’t, make sure that you are putting them in the correct folders or at root and NOT inside of the build folder. Also be sure to add _site/ to your .gitignore.
3. Add Blog Post Drafts
If you are going to be using your site primarily as a blog, be sure to add _drafts/ to your project directory. You do not have to follow the date formatting for your Markdown files in this project and can use it to store future blog posts that you don’t want published right away.
Tip Add
_drafts/to your .gitignore if your repo is public
4. Use a Separator for Scrolling Posts
I decided that my collection of blogs were going to be on the front page of my site. Instead of the full post showing, I wanted to show excerpts to allow people to click through to the full blog.
Add this to your _config.yml:
excerpt_separator: "<!--more-->"
Add the separator in your post wherever you want your excerpt to end.
5. Implement SEO for your Page
This Dev.to post walks you through what Jekyll plugins to add to index your website and posts.
6. Use Own Domain with GitHub Pages on the Free Tier
Here’s the direct link to setting up a custom domain on the GitHub Free Tier. This process was fast and painless, but I also use Porkbun for my domain management and they had a quick setup for GitHub Pages already.
Overall, I am glad that I removed the monthly expense of hosting my portfolio through other sites and moving to GitHub Pages. It more than covers my need for a portfolio site. I only wish that I would have migrated sooner.