Earlier this month I decided to make a website. I learned just enough HTML and CSS, and JavaScript to build what you’re looking at. My advice to you is “don’t do as I did,” but if you’re determined to go at it yourself, here’s a write-up of how to do so.

The basics

This website is hosted on GitHub, an online code management service. Most things that GitHub offers are free, and hosting your website there is free as well. The downside is that you need to host a static website, which is a website that does not require server-side processing (like a database). Most webpages hosted on GitHub are generated using a static webpage generator called jekyll. Jekyll takes your content (like the text of this site), formats it into HTML and organizes it using your layout HTML files. You can have different layouts for different types of content files too. There is also a (limited) programming language called Liquid¹ that you can use to help you generate your website.

While your layouts are written in HTML, you can write your content in markdown, which is a syntax that can be formatted into HTML. To get a feel for what markdown is/does check out this online markdown converter called dillinger. Markdown is a great way to write nicely formatted content.

The hard part is designing the website.

Other write ups

Several other people have written write-ups about creating a website with jekyll and hosting it on GitHub. Joshua Lande has a post that covers much more than this one. Garry Welding has a nice write up on how to get started, particularly if you’re using Windows or migrating from wordpress². Techrepublic.com and Smashingmagazine.com both have good getting started articles as well.

Getting started

If you want to host your website on github, my best guess is you’ll probably need a GitHub account. Once that is done you basically follow the directions found here for getting jekyll installed. This will allow you to preview your website locally on your machine before uploading it for the entire world to see.

Once you have jekyll installed you can start a new site by running jekyll new my-awesome-site on the command line. Alternatively, you can get started by following the steps outlined here.

At first I wanted to get something up and running quickly – I didn’t want to spend any more than three days working on my website. This goal is reasonable if you are okay with using a layout that someone else designed. All you need to do is choose a layout, and there are lots of examples on jekyll’s wiki page. Many of the sites listed on the wiki share their source code so you can fork (copy) their code to your GitHub page, delete their content, and replace it with your own.

Jekyll-bootstrap tries to make it as easy as possible to get your website up and running with little hassle. You can get your website up and running in 3 minutes if you want to. They also have a handful of themes to choose from too. The jekyll-bootstart website has a nice description of the how jekyll works. I found their description of liquid useful too.

Designing Your Website

I wasn’t satisfied with the examples I had to choose from, so I decided to make my own³. By the way, I knew zero HTML, CSS, and javascript. I started with some lessons offered at codeacademy.com. They offer free and simple lessons on several programming languages – although it seems like they focus on languages commonly used for web development. I took their introductory course on HTML and CSS, as well as a few lessons in jQuery and javascript, which were all quick and easy lessons. Signing up for lessons was an easy process, plus they were free.

I ended up borrowing layout elements from various websites. Lots of people use GitHub to host their site, and many want you to use their code.

Who I borrowed from

I really like the simplicity of Tom Preston-Werner’s⁴ website. I borrowed some layout design elements from Doug Johnston and Miguel Mota websites as well. I really like Hossain Mohammad Faysal’s omega theme, but I only borrowed his tagging code. My blockquotes style was borrrowed from the poole theme.

The navigation thingy on the right side of this page was not my idea either; I got that idea from the jekyll-bootstrap-doc project page (although it seems like they copied it from the bootstrap docs). I found the relavent CSS file for the bootstrap docs on github. I learned enough jQuery at codeacademy.com to edit the jekyll-bootstrap-docs code for this website.

Codrops.com has a lot of cool design elements for a website. Basically everything these guys do is hot fire so check them out. The style for my links was taken from this codrops.com article, and their demo has a lot more examples to choose from. You can find even more examples of creative link effects here. Their HTML and CSS source code is freely available on github as well. I also borrowed from one of their articles on arrow navagation, the demo is here and the CSS is here. I must note that getting the arrows to work nicely in a jekyll site was non-trivial as well. I ended up editing some code that some guy posted on github.

More on my layout and style choices

• The font I’m using is Open Sans, and I got it from Google Fonts – all their fonts are free. Adobe typkit has some nice fonts but only a small subset are free. If you want to use build-in fonts, this website lists all your options.
• Turns out that having a footer stay at the bottom of a webpage is kinda non-trivial. I ended up styling this layout with Flexbox, which makes a lot of layout problems easy. Philip Walton has a good site on what you can do with Flexbox.
• You can style your code highlights. I used the jekyll-GitHub CSS file located here.
• The background pattern for this site was found on subtlepatterns.com.
• Sometimes I would visit a website and really like one particular thing that they did. Figuring out how to do that one thing is easy if you use your web browsers HTML inspector⁵. This made learning CSS a lot easier too, since you can edit a sites CSS and watch what happens in real-time.
• Right now all tags for this site are generated on one page. There are better ways to do this and Charlie Park has a nice post on how to do so.
• I use fontawsome and bootstrap’s glyphicons for my icons. You might find this fontawesome/bootstrap icon cheatsheet useful. Entypo.com is another place to get icons from, but I haven’t used them.
• I plan on writing some math on this site in the future, and jekyll provides support for MathJax, a JavaScript display engine for mathematics. Somehow, the styling of latex code gets distorted and appears orange by default. To fix this, I use the following code when loading MathJax:

<script type="text/javascript">
  window.MathJax = {
    TeX: {
      equationNumbers: {
        autoNumber: "AMS"
      }
    },
    tex2jax: {
      inlineMath: [ ['$','$'], ["\\(","\\)"] ],
      displayMath: [ ['$$','$$'], ['\\[','\\]'] ],
      processEscapes: true
    },
    "HTML-CSS": {
      styles: {
        ".MathJax .mo, .MathJax .mi": {color: "black ! important"}
      }
    }
  };
</script>
<script type="text/javascript" src="//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML"></script>

• Testing out your HTML and CSS layout is easy in jekyll. In the root directory of your website folder run jekyll serve -w and Jekyll will watch for any changes to your files. This allows you to quickly watch any changes you make to your CSS or layout files.

The domain name

The default domain name for a GitHub website is <GITHUB_USERNAME>.github.io. You can use a different domain name, but this requires some setting up. There are several places to get domain names from, and namecheap.com has really cheap domain names. David Ensinger has a post on how he setup his DNS for GitHub websites on namecheap.com. He has another post on how to transfer this to Cloudflare. This site uses Namecheap for domain name registration and Cloudflare for content delivery. Cloudflare offers a lot of their services for free (the services I use are all free).

Good web development practices

I don’t know how but I stumbled onto Mark Otto’s guild to writing good code. I don’t think I followed it much, maybe I should have.

Yahoo and Google both have guilds on designing websites that load quickly. Yahoo’s performance site can be found here, and Google’s can be found here and Google offers a free speedtest as well. There are other free online speed-testing sites such as pingdom.com.

Things To Do

There is a lot of things you can do with Jekyll on github. I don’t have the time or energy to implement them all at this time, but when I do here are some possible improvements.

• Knitr: At some point I’ll want to render some R code here. I found this quick tutorial on how to incorporate knitr into Jekyll here and here.
• Search: I found this post via Garry Welding on how to add search functionality.
• Intro effects: Codrops.com has a list of really nice into effects. I doubt I’ll do this anytime soon.

Anyway, I hope this helps.