I woke up today and thought, “I should put some work into the Technical Documentation Project”. It’s a lazy, easy-going Saturday: the perfect time to put in about an hour of work or so and go from there.

I filled up my water bottle, threw on my headphones, went to Spotify to play some music- today was an I The Mighty kind of day- and got straight to work. I started with some styling that was giving my trouble yesterday: I couldn’t get <code> blocks to render how I wanted them to. Today? No issues at all, I got it with minimal effort.

From that moment on, every task I wanted to complish would just get done. I get to a point where I felt like the site was done, so I peeked at the clock.

2:27PM

Holy cow, it’s been like 3 hours! I didn’t care though, I finished the project. The trouble began when I wanted to host it on Github Pages.

Breaks are important

Hosting a website on Github Pages is not hard. It’s a really wonderful thing in my opinion. You just have to remember to do the right things and everything will work! (Great advice, I know).

Here’s what I did

• I created a new repository on Github
• I cloned it to my computer
• I copied in some files generated by Jekyll from a different project that I also want to host on Pages one day
• I edited some files:
  • _config.yml: to change the title of my site to the name I want
  • _layout/default.html: this is where I copy in the HTML I wrote for this project
  • _sass/minima.scss: this is where my styling goes to override the default theme for a Jekyll site
  • assets/js: I don’t think I’ve written JavaScript for my sites before, but this is where it goes for Jekyll to put it in the right place
• I committed everything and pushed to Github

Can you see where I went wrong in the list of things I did? It’s a wonderful learning experience that I hopoe you never experience yourself. I think if I had taken a break after finishing the project, I would’ve caught the error sooner. Or not, I’m still new at this and make tons of mistakes with Jekyll.

Here’s what I forgot

I didn’t change the baseurl option in the _config.yml file. The site was loading just fine on Github, minus the fact that no styling was being applied. After messing with the stylesheet link for a while, I got it to take on the stylesheet from my main site.

That’s when it clicked: I needed the stylesheet found in the subdirectory for this particular project, but I wasn’t saying that in the HTML file.

You can bet that I am never making this mistake again.

How to Set Up a Project on Github Pages

Assumptions

• You have a “main” site set up there already
• You have Jekyll properly set up locally. If not, here are the instructions
• You have some HTML+CSS+JavaScript you are trying to host
• You know some basic command line commands

Procedure

I am a fan of setting up the local development before pushing stuff to Github, so you’ll need to run

jekyll new projectName
cd projectName

to set up a new Jekyll project and change into that directory.

Next, we’ll set up version control by running git init.

Add a .gitignore

Before we do an initial commit we have some preliminaries to take care of. Let’s set up a .gitignore. Here’s what mine looks like because I’m on a Mac:

.DS_Store
Gemlock.file
_site
.sass-cache

Edit _config.yml

Now we’ll edit two of the files Jekyll gave us. Starting with _config.yml, open it in the editor of your choice. Change these to whatever you want:

title
email
description
twitter_username
github_username

Pay attention to baseurl and url!

• url will likely be the custom domain you set up for your Github Pages. Or it will be yourUserName.github.io.
  • If this is your main site, I would definitely fill in this line.
  • If this is a “side project”, so not your main repository where a Pages site is already up and running, you can leave this as url : ""
• baseurl
  • If this is your main site, my advice is to set this a baseurl : "/"'
  • If this is a “side project”, set this as the repository name, exactly how it appears when you go to github.com/myUserName/someRepo. So it should look like baseurl : "/someRepo"

Save the _config.yml file.

Edit the Gemfile

Moving on to the Gemfile, open it up in an editor.

• Find the line that starts with gem "jekyll" and just add a # in front to comment it out
• Find the line that starts with gem "github-pages" and uncomment that line

Save the Gemfile file and run the following in the command line:

bundle update github-pages

This should make your local environment match the build environment on Github.

Time to turn our atttention to adding the files for the site.

A quick note, I like using .scss files, but I’ll include directions for plain .css as well. We’ll start there actually.

Adding CSS or Sass files and JavaScript

CSS + JS

Create some folders for your .css and .js files:

mkdir ./assets
mkdir ./assets/css
mkdir ./assets/js

Sass + JS

If Sass more of your style, do this instead:

mkdir ./assets
mkdir ./assets/js
touch ./assets/main.scss
mkdir ./_sass

Go ahead and place your CSS/JS/SASS files in their respective homes.

For the Sass people, open the assets/main.scss file we created earlier and add:

---
---

@import "minima"

I’m pretty sure the @import is for whatever your Sass files are named and if you have multiple in the _sass folder, import them in this file. In the Jekyll Docs, it says to override the default theme by creating similarly named files in our project. Read them for yourself and let me know if doing this in the best way.

Adding HTML

Moving on to the HTML files, go back to the root of the project and add:

mkdir ./_layouts
touch ./_layouts/default.html

Copy your HTML into the default.html file.

Before we can see your HTML render, we have to edit /about.md or /index.md, whichever was created by Jekyll for you. The file should look like this:

---
layout: default
---

Run the site

To locally run the site, just type

bundle exec jekyll serve

It should tell you to go to localhost:4000, open that up in your browser of choice. You should see your site!

Commit the files

Last but not least, we need to commit all of these files to git.

Congrats on your new site!