Make a pretty site, learn Jekyll: Tutorial

Trying to learn my way around GIMP the other day led me to Sirar Salih's developer blog.

I thought it looked SO GOOD:

Helpfully, Sirar links to the original theme on his page: Hydejack, built with Jekyll and hosted on Github pages. Obviously, I had to try it myself.

Here's my working version:

For some helpful tips and a better how-to than what you'll find elsewhere, read on.

Installation

The Hydejack site gives several installation options.

I don't know much about Ruby/gems, so I didn't go that route. Going the zip file route just sounded messy, and I've been known to mix up my git clone and my git fetch.

That left installing via starter kit, which gives you a decent quick start guide in its ReadME.

I elected to start by setting up my GitHub pages site, just because it sounded the easiest, but I had to change a few of the steps:

1. Fork the hydejack starter repo.
2. Go to the Settings tab in your new repo. Rename the repository.
3. Still in Settings, scroll down to GitHub pages.
4. Set source to master branch
5. Copy the URL this generates.
6. Go back to the code (still in GitHub). Open the _config.yml file.
7. Uncomment the url line and replace the url with your new GitHub page.
8. Uncomment the baseurl line and replace with the repository name in single quotes.
9. Commit the changes.
10. To see the site, go to the GitHub pages URL.

Running Jekyll locally

Now, I did all of this before I had my own local copy of the site. So it was satisfying to see the blog theme immediately live and hosted, but is obviously not ideal for development. Onward to setting up local development.

1. Create a new directory on your computer where your project will live.
2. cd into your new directory.
3. Run git clone [YOUR_PROJECT_REPO] (NOTE: I didn't have to git init in the folder before cloning, which surprised me)
4. cd into the root directory (which is where you _config.yml file is stored.
5. Run bundle install (NOTE: this requires Bundler. If you don't already have it, run gem install bundler)
6. Run bundle exec jekyll serve
7. To visit the site, go to localhost:4000
8. To start developing, open this project directory in your code editor of choice

Now, a note about the local site: although the jekyll server continues running as you make changes in your code base, I have had to stop and restart the server for changes to take effect. I need to research more to find out if there's a way for the jekyll server to be watching for changes and update accordingly.

Digging into the development

I ran through the HydeJack Configuration page to start customizing my website, and it's great.

But, I started to notice that there were some files and folders in my GitHub repo that weren't in my local copy. What's the deal?

Well, the .gitignore file includes the _site folder. Which, you know, contains pretty much the whole site.

I commented out that line so that I could get into the meat of those pages.

*~*UPDATE~*~

So guys, the _site file is what gets built when you run the Jekyll server. If you try to put anything in there, it will be deleted when you build. So, keep that shiz in your .gitignore.

Resources 'n learnin

I didn't know anything about Jekyll before starting this site. And honestly, not a lot of great resources out there on it. A lot of the videos and articles I found are from 4 or 5 years ago, which makes me feel like Jekyll is a little passe?

In any case I liked this video for an intro:

Just like HydeJack is free to use, there are a bunch of other Jekyll themes out there!

Go to this link to peruse a bunch of free and paid options.

Finally, for the pared-down intro to Jekyll for blogging, check out this dev post:

Getting Started with Jekyll

Jarret Bryan ・ 4 min read

#codenewbie #jekyll #githubpages #ruby