How I Built It

In which I go off the 'Rails'

Welcome!

After recently being inspired to finally do something with the horde of domains I’m sitting on, today I’m going to lay out how exactly I was able to get my personal portfolio up and running with Cloudflare and Github Pages.

This guide is for Windows.

Table of Contents

Goals:

  • To be able to have a place to remember how I did that one thing
  • To be able to showcase anything (marginally) cool I built
  • To be able to use markdown as a means for creating content (HTML is just so 90s, man)
  • To spend as little as possible (having monkeying with websites for 20+ years, I’m over dealing with hosting providers [for now])
  • To have more control over the content, formatting, and layout without installing bloat or increase attack surface
  • To feel smug about having a domain that has my name

Requirements

For this effort, I’m using a domain name and Github pages. This is optional; you can just use the URL provided by Github directly.

  • Github account
  • Computing device
  • Base understanding of Git (here’s a refresher)
  • Some time and/or coffee

Ruby

Download and install ruby.

When it’s done installing, make sure to check the ridk box. RubyInstall

This opens a new prompt. Enter in options 1,3

RubyInstall2

Finally, open a new command prompt window from Start, and type ridk enable.

Bundler

Open a Powershell window. Run gem install bundler. This is successful if you see the “1 gem installed” message

Git

If you don’t already have it installed, install Git.

Also create a new repository on GitHub on your account. Once created, go to that repo and click on Settings (1), then Pages on the left (2). Here, you need to select which branch you want to auto-build from (3) with an optional embedded directory. In mine, that’s prod. Optionally, type in your domain name (4). GitHubPages

If you are, using your DNS provider, enure www is pointing to your domain apex (@). Then, create a CNAME record to <USER>.github.io, where <USER> is your github username. Give it up to an hour to propagate, then come back and check the settings to ensure it linked correctly.

Jekyll

Open a new command prompt window from Start, and run gem install jekyll bundler. When it’s done, run jekyll -v to verify it was installed properly (you’ll see a version). jekyllv

Build it!

We’ll need a place to store our site, so go choose one now. Create an empty folder there - that will be what everything (the site, git repo, assets, etc) is stored in. From here on out, we’ll be using Git Bash to do our command line kung-fu, so open that.

In Git Bash type,

git init REPO
cd REPO
git checkout --orphan BRANCH

where REPO is your remote repository name and BRANCH is your build branch from earlier.

Now, let’s make your Jekyll site. This will create the new instantiation of Jekyll in our previously navigated to directory (.). The --force flag ignores and Readme.md or other files created by GitHub. Optionally, delete everything here before running the next command.

jekyll new --skip-bundle . --force

Navigate to where you made the site in Windows Explorer. Open the Gemfile that Jekyll made. Add # to the beginning of the line that starts with gem jekyll to comment out this line. Now, add the github-pages gem by editing the line starting with # gem "github-pages". Change this line to:

gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins

Replace GITHUB-PAGES-VERSION with the latest supported version of the github-pages gem (e.g., 228). Check the version here. Save and close.

Going back to the Bash window, run bundle install. When we deploy, a different version (most likely) of Jekyll will be installed as a dependency of the github-pages gem that is compatible with GitHub so it can auto-build.

Assuming everything has gone right, you’re ready to test your site locally by running bundle exec jekyll serve! It can be found at http://localhost:4000/

To future Nick: when you want to update the site and you can’t remember how: open a terminal where the site is hosted (e.g., ‘portfolio’, then run bundle exec jekyll serve. Upload the changed files under _site.)

Push it. Push it real good.

Once you’re happy with the content, don’t forget to add, commit and push your files to the cloud. If you’re not committing to your build branch (please don’t), make a pull request and let GitHub handle the rest!

References

The info for this post was concatenated from the following sources:

SOFTWARE · WEB
web software jekyll DNS guides windows

Archive