22 Jul 2017
Last weekend, I decided to build my own personal website and I thought it would be a helpful resource to document the steps that I took to get jared-johnson.com up and running.
I decided to set my website up using GitHub Pages. For those who aren’t familiar with GitHub, it’s a version control repository for code. What this means is that developers use it to preserve iterations of their projects and applications. It’s a great tool and for those new to programming, I highly recommend checking it out.
Ok so what is GitHub Pages? GitHub offers a relatively easy way for users to host projects and personal websites to the web for free. And you’re able to manage your website using the same workflow that you’ll be familiar with from working with code projects on GitHub.
To start using GitHub Pages for your website, the first think you will need to do is create a repository with your GitHub username and the extension ‘.github.io’ – it should look something like this:
Once you have this repository set up, the only file you need to create your website something called index.html. I cloned my repository down locally and set my website up with it’s own directory but if these words mean nothing to you, I would recommend downloading the GitHub app to interface with your website repo.
Using a text editor like Atom, try typing ‘it’s my website’ in your index.html file and sending those changes up to GitHub using the code below if you’re using the terminal, or by syncing your changes if you are using the GitHub app.
git add . git commit -m "my first commit" git push
Now go to your-username.github.io in your browser and you should see something like this!
Your website is now live and you have the freedom to make it anything you want. Once I got to this point, I only partly felt satisfied. I have a functioning website but I have to type in the full .github.io URL to access my site. Wouldn’t it be cooler if I could pull my website up with a snappy ‘.com’ address? Well, you can be the judge of that but I knew my next step was to buy a domain.
First thing I did? High-tailed it to GoDaddy.com. Dot com domain names can get pricey and I was lucky to find jared-johnson.com at an affordable price (Although I did opt to pay a premium to insert a dash between my name rather than purchasing jaredjohnson.net or jaredjohnson.us).
To get my GitHub site to be served to my fancy new domain name, I had to complete a few more steps. First, I had to let GitHub know that I was using a custom domain. In the ‘settings’ tab of your repository, you should find a box to enter a different URL (see below).
After letting GitHub know to serve your custom domain, you will need to let your DNS provider (GoDaddy in my case) know where to route your URL. I found a really helpful blog post by Kristen Swanson that details the steps needed to set this up if you are also using GoDaddy.
As awesome as it is to own a URL on the internet that just says “it’s my website,” I knew that I wanted to use my site for blogging. By now, I know enough programming to build something from scratch that looks good but my experience has also taught me just how much work can go into maintaining something as simple as a blog. Drawing routes for all my posts, formatting my plain text and designing my site in plain HTML/CSS was starting to look like a part-time job. That was until I discovered Jekyll.
Jekyll is a static-site generator built by one of the co-founders of GitHub. Ok but what is a static-site generator? This just means that Jekyll is an application that can render all of the pages of your website from plain text and a template. Jekyll uses Markdown Syntax, which is mostly plain text that renders to HTML, to tell your site what the contents of each page or post should be. It makes managing your site so much easier. With all of this said, understanding a little bit of HTML and CSS is extremely useful when using Jekyll, which I will demonstrate later.
Allow me to show you an example to better hammer home why this is so useful and then I’ll discuss setting up Jekyll.
This is what the Markdown syntax looks like for my last blog post.
And this where my blog post content is pulled into my HMTL file.
All of this is rendered to my site to display like this.
I didn’t have to set up a database or write logic that tells my site how to deal with each individual post. Following the convention of Jekyll projects, I was able to get my post content rendered to my site in minutes. Pretty cool, right? Now let’s discuss setting up Jekyll.
Jekyll is a RubyGem. This means that, assuming you have a version of the Ruby programming language installed on your machine, Jekyll can be installed using the following commands.
gem install jekyll jekyll new my-website
You should now have a new Jekyll project at ‘my-website’ on your computer. Since I already have a working site via my GitHub pages repository, I moved all of the files that Jekyll gave me into the same folder. Now is a good time to discuss what these files are.
# from the Jekyll official documentation . ├── _config.yml ├── _layouts | ├── default.html | └── post.html ├── _posts | ├── 2017-07-02-quit-being-difficult.md | └── 2017-06-13-4-things-i-learned-toying-around-with-nested-resources-in-rails.md ├── _sass | └── _layout.scss ├── _site └── index.html
For simplicity, I’ve pared down the file tree example from the official Jekyll documentation. The first file that you should edit is _config.yml, which is the configuration file that contains settings and variables that become available for use throughout your site.
In the _layouts folder is where your page templates are stored. I am currently only using two different templates for my site, one for blog posts – post.html – and another for my home page called default.html. As I mentioned earlier, these templates are just HTML files that are populated with content from associated Markdown files (where you write your plain text). Content from your posts and variables defined in your _config.yml file will be available to these templates using double brackets.
New posts must follow a certain naming convention (see below) to be recognized by the Jekyll logic.
# post example in _posts folder YYYY-MM-DD-title.md
The ‘.md’ here denotes Markdown syntax. Anything I write in these files is sent through my post.html template and a ready-to-serve HTML file is generated in my _site folder. In the _site folder lies the magic of Jekyll. All of the HTML files, images and CSS/styling elements used in my website are copied over or generated in this folder. As you make changes to your ‘.md’ files in your _posts folder, the accompanying HMTL file in the _site folder gets re-generated. With GitHub pages, the only thing I need to do after creating or editing a post is pushing my commits up to my repository. It’s that easy – No part-time job necessary.
The last that I want to touch on is using themes in Jekyll. Pre-made themes make it really easy to spin up a site that looks great in minutes. If you initialize your Jekyll project using the ‘jekyll new’ command, your site will come with a default theme named minima. While this theme looks great, I wanted something even more pared down and swapped the theme for one called minimal.
Jekyll makes changing your theme extremely easy. In your config.yml file, you can swap out your theme for a number of options available in the RubyGems library. I narrowed my search by reviewing the list of themes supported by GitHub Pages. Each theme comes with it’s own default template for pages, so I would recommend copying this over from the GitHub repository for your chosen theme.
I genuinely hope that this post has been helpful and that I’ve inspired you to create your own website. Don’t hesitate to reach out to me @yungpanko if you have any questions about my experience.