Zero to Minimum-Viable-Jekyll-Website

• How Done Is This Post?
• Step 1: mkdir new directory
• Step 2: Pick theme from Jekyllthemes.io
• 2.01 git clone the theme
• Step 1: jekyll new
• Step 2: jekyll server
• Step 3: Update config file?
• Step 4: Restart jekyll server
• Step 5: git init, git push
• Step 6, configure github account
• Step 6.01 Site not reachable
• Step 6.02 Still Broken, nothing at https://josh.works/aftd/
• Step 6.03 try adding custom domain (our end goal anyway)
• Step 7: Set up Google Domains
• Step 7.01 Set up cloudflare
• Step 7:02 Cloudflare: Select the free plan (I often see upsells here. Hunt around for the free plan button.)
• Step 7.03 Cloudflare: CNAME? MX records? huh?
• Step 7.04 add a file to your repo (CNAME)
• Step 7.05 Get Cloudflare nameservers, add to google domains account
• Step ???: IT WORKS
• Step 9: Change Theme, see updates on your website
  • Notes

How Done Is This Post? #

Anything I write ranges from “super rough notes-as-i-go, don’t even expect full sentences” to “this post is done and proven to deliver what it promises to deliver”

1. Scratch-pad, take-notes-as-I-go <– we are here
2. Review post, clean up for first ‘share’
3. I mkdir new directory, follow my own steps, clarify
4. Integrate feedback/answer questions from others
5. Final cleanup, post is considered done unless someone reaches out with further questions

I was chatting with a turing Alumni recently, about blogging and setting up a personal website.

I’ve told so many Turing students that they should blog, at least via Medium, but sometime shortly thereafter, they should move to a personal website.¹

Someone just said:

Also working on my website as well and having a tough time grasping Jekyll so thats next on my to-do list. I not sure how to get the page layout like your while using markdown :thinking_face: or did you use HTML and CSS?

And I wrote back with:

I just bought a new domain recently - afailuretodisagree.com I want to set it up as a bare jekyll site, via google domains, tied to github pages. I don’t know what theme I’ll use - something from https://jekyllthemes.io/. And I’ll write down all the steps, including how to set up a bare version of something that looks like my site. I’ve been wanting to write this guide for a while. It’ll >live on…. https://intermediateruby.com/

So, let me hook up afailuretodisagree with a jekyll template.

I made this statement about ten minutes ago, lets see how long it takes.²

Step 1: mkdir new directory #

I plan on doing something Interesting with this new website, so it lives in my /me directory. aftd stands for A Failure To Disagree:

$ mdir aftd

Step 2: Pick theme from Jekyllthemes.io #

Pick a theme. I’ll be using a free theme from https://jekyllthemes.io/. They have many beautiful-looking themes.

At least - they’re beautiful to this mostly back-end software developer. (That’s why I’m using a theme. Couldn’t roll-my-own.)

I’m choosing https://jekyllthemes.io/theme/almace-scaffolding:

Check out this live demo: https://sparanoid.com/lab/amsf/

I like it. So, next, hit the “get this on Github”

2.01 git clone the theme #

Head to to https://github.com/sparanoid/almace-scaffolding

And grab the git clone url, and paste it into your new empty directory:

git clone https://github.com/sparanoid/almace-scaffolding
cd almace-scaffolding
bundle install
bundle exec jekyll server

Gar, super stuck, making it easier…

Start here: https://jekyllrb.com/docs/themes/

We’re installing [https://github.com/jekyll/minima][https://github.com/jekyll/minima]

TAKE TWO #

Step 1: jekyll new #

gem install jekyll
jekyll new aftd
cd aftd

Step 2: jekyll server #

run jekyll server in your terminal

Open your browser, visit [http://localhost:4000/]

Boom. You’ve got a website:

Lets customize it a bit to you:

Step 3: Update config file? #

Open everything up in Atom:

atom .

Open up _config.yml in Atom, edit your name:

Step 4: Restart jekyll server #

Now, critically, you must restart your jekyll server.

It usually can live-reload content changes, but it reads from the _config file only once, when starting, so you must restart the server to catch updates to the config file.

Stop it with ctrl-c in your terminal, run it again with jekyll server. Check out the changes:

OK, lets call this good enough, push to github pages somewhere.

Step 5: git init, git push #

git init
git add
hub create # creates new repo from cli, look up github cli utility or "github hub"
git push origin main # i have aliased to `gpo`
git branch reveal # ??? I don't know what it means. i have aliased to gbr, opens up repo in browser

Now I’m looking at https://github.com/josh-works/aftd/tree/main

Step 6, configure github account #

So, in https://github.com/josh-works/aftd/tree/main, I navigate to settings, scroll down to “github pages”

siiiight I’m stuck. It’s 8:15, I have to call it for a night.

Provenance of the above 2760c20edcbdf8f5bf9538ef5461489ed7b8e80a.

note: 10:15p, i’m carrying onward a bit! My parents are in town, had a nice time hanging out, everyone’s in bed, so I wanna push this onward a bit.

Step 6.01 Site not reachable #

My site seems to be trying to get published here: https://josh.works/aftd/

It also 404s, and I get a page build error. In my inbox, specifically, I get more info:

The page build failed for the main branch with the following error:

No /docs folder was found to build GitHub Pages. Check the source setting for this repository. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#missing-docs-folder.

For information on troubleshooting Jekyll see:

https://docs.github.com/articles/troubleshooting-jekyll-builds

Bleh. It’s possible that if I didn’t already have a site published on Github pages (josh.works is “published” on josh-works.github.io. If you visit josh-works.github.io you’ll get a 301 Moved Permanently redirect to http://josh.works)³

$ curl -v josh-works.github.io

Fortunately, this site (intermediateruby.com is hosted on Github pages with a custom domain, so let me go check the settings for this very own page. git repo for intermediateruby)

So I wonder if it’s as simple as putting in a custom domain?

Nooope, that doesn’t seem right. I finally figured it out. I think I have the branch name wrong. Let me try publishing everything off of a gh-pages branch.

Gosh, I think that’s it. I remember trying to rename the master branch of my personal site to main, couldn’t, etc. I didn’t think I’d remember gh-pages, so I just left it as master.

When I jekyll new‘ed, and grabbed the screenshot of my terminal, I was like

ew, I don’t want to put a screenshot out there foreveryone to see with my git branch named master. That’s dumb.

So I did gb -b main, gpo, and expected the right branch to be up there. I remember the github support team emailing me back saying “eh, we don’t support a branch named main yet”.

Anyway, lets fix our branch situation:

git branch -mv gh-pages
gpo gh-pages
gpo :main # I was hoping this gonna delete the `main` branch on gh, but didn't work. ¯\_(ツ)_/¯ 

Update settings:

Step 6.02 Still Broken, nothing at https://josh.works/aftd/ #

Still broken - supposedly site is published at https://josh.works/aftd/, but it just loads an empty page.

When I curl https://josh.works/aftd/, nothing comes back. Try it yourself, in your terminal. If you get anything back, besides a single new line, I’ve fixed this.

Step 6.03 try adding custom domain (our end goal anyway) #

Lets try adding a custom domain instead. So, back to your settings. I punch in afailuretodisagree.com, because I own the domain, and…

I’m suspicious:

there’s no way this worked. I don’t belive Github. There’s nothing stopping me from entering stonks.com (which I don’t own, but check it out, it’s awesome: https://stonks.com/)

Step 7: Set up Google Domains #

off to domains.google.com/registrar:

If you don’t have a domain here you want/can use, buy another one. Smash the get a new domain button, or visit https://www.domainhole.com/generator/ for inspiration and ideas on cheap domains.

Find an available domain anywhere, and buy it in your Google Domains account. If you don’t have a google domains account, create one, add a credit card, etc.

Ooooh gosh, custom nameservers. That’s Cloudflare. I just looked to see how I have intermediateruby.com configured in domains.google.com, and it’s got custom nameservers pointing to Cloudflare.

Cloudflare… runs the internet, IMO. Not quite the same as AWS, but Cloudflare is everywhere. They sit “between” AWS and people’s devices, same as how Amazon’s warehouses sit close to the end-user⁴.

Step 7.01 Set up cloudflare #

Gosh this is getting complicated. I’m way over my target time of “having a new website set up from scratch in 10 minutes”. I’m about two hours into this, though, admittedly, I’m writing this blog post as I work through the process.

I last went through this process over a year ago (with intermediateruby.com) and I remember it being surprisingly difficult. So, I’m not surprised that when I say “go figure this out” to people that have run zero websites, instead of the 5+ I’ve dealt with over the years they feel sandbagged.

Onward…

Set up an account at https://www.cloudflare.com/. It’s free.⁵

As a software developer, I have to manage dozens-to-hundreds of logins to various systems. I just checked my account. I’ve got almost 900 items in 1password. Many of those are logins. If creating a strong, random password on a new site isn’t painless to you, it needs to be. Use 1Password. I don’t make money from you being their customer.

I have a free Cloudflare plan, so you should be able to have one too.

Log into your account, on the home page, click Add a Site:

Step 7:02 Cloudflare: Select the free plan (I often see upsells here. Hunt around for the free plan button.) #

Step 7.03 Cloudflare: CNAME? MX records? huh? #

You’ll see something like this:

Review your DNS records

1 CNAME Verify that DNS records below are configured correctly. These records take effect in Cloudflare after you update your nameservers.

What does that mean?

Time to check what I’ve got configured for intermediateruby:

Sigh - this still isn’t what I need.

Step 7.04 add a file to your repo (CNAME) #

I googled around, found Using Github Pages with Google Domains and Cloudflare. They said:

Github Pages Configuration

To configure Github Pages, add a file called CNAME to the root directory of your Github repository. Inside this file, you’ll put your domain name (e.g. www.randydeng.com). This tells Github where your domain is located.

Oh right!

Echo "www.aftd.com" >> CNAME
git add . && git commit -m "Adds CNAME" && git push

When you git push you’ll probably run into some conflicts; when you added the custom domain setting in Step 6, git added a CNAME file to the repo. I didn’t know that, so I was getting merge conflicts when trying to push this branch, unexpectedly.

I didn’t want to force push without knowing what I was overwriting.

Here’s what I did:

Anyway, now the repo has a CNAME file in it, the content of which is www.afailuretodisagree.com, overwrote an earlier commit: 0e901771d27ae3ec454ffc05bb83b278be738ec9

When I visit https://www.afailuretodisagree.com/, I get nothing.

Wow. Now 11:28, another hour has passed, and I don’t have a website online. I’m glad I’m writing this out, as I’m way farther into this than I would have expected. Check out this commit here: 02951b582dece6d59024dbca7000bdbea5bc58e2

JK doing a little more

Step 7.05 Get Cloudflare nameservers, add to google domains account #

OK, so you don’t have to guess on the cloudflare nameservers - they’ll probably be the same for you as they are for me, I’ve been using these for years. They are:

elaine.ns.cloudflare.com
elliot.ns.cloudflare.com

And here’s how you add them:

OK, NOW you can take a break. Cloudflare and Google both say that it can take two days for these changes to fully propogate throughout.

As of 2021-02-18 11:40p, https://www.afailuretodisagree.com/ doesn’t go anywhere.

but what about:

https://www.afailuretodisagree.com/
http://www.afailuretodisagree.com/
www.afailuretodisagree.com/
afailuretodisagree.com

Nothing. Two hours in, and I think I’m making a smidgen of progress. I’m remembering now why it felt so complicated to me last time around. It was complicated, I remember googling a lot about various record types, how they worked, etc.

I’m figuring it out, slowly. I might be able to appreciate bits of my copy of High Performance Browser Networking now.

Sigh. Do I need CNAME records? A? AAA? I don’t even know what it all means.

Found something useful in Github docs: https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site#configuring-an-apex-domain

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Step ???: IT WORKS #

Yay! I can finally visit: https://afailuretodisagree.com/ and it loads my Jekyll site.

Wow. That was difficult, confusing, full of uncertainty, and I’m not actually sure what made the difference.

I’ll do this whole thing a second time on another site at some point.

This is one more hour in (not quite a full hour, maybe 40 minutes + some email).

Step 9: Change Theme, see updates on your website #

OK, lets try changing the theme again, now that we know the changes will propogate to afailuretodisagree.com.

OK. I changed to the minimal-mistakes-jekyll theme with two configuration changes, now it looks like:

Notes #

• Why a domain’s root can’t be a CNAME — and other tidbits about the DNS
• Managing a custom domain for your GitHub Pages site
• Using Github Pages with Google Domains and Cloudflare (randydeng.com)