GitHub Pages with Jekyll
12 Jan 2017What is this, I don’t even…
I am now writing my first “document post” to my own websites! So… um.. Hello world!
How it all started…
Two weeks ago I started my personal website project to get a suitable online database to my project documentaries and a portfolio/CV/show-off web page. The idea started from Web Software Development course and Django seemed a fun way to create personal web pages.
Well, that long story short, I was pretty satisfied to my green fruit of a web page (although the style needed a lot of extra work) and all I needed was some G to my local. It was time to find out about the amazing world of domain administrating!
That was not so fun and free. Well, fun maybe, but not free. Dozens of options with web hotels to host my site, what kind of properties would I need from the host? Or should I go full nerd and build my own server to do the domain hosting?
After consulting couple of my friends I learned that pages could be hosted on GitHub Pages. Great! I just upload my ready-to-go Django sites to GitHub and that’s it!
Not quite. The problem was, that GitHub could only host static sites. That means, not dynamic sites like Django sites are. So back to the drawing board. I find out that using static pages would be enough for my needs right now and GitHub pages seemed easy and versatile way to approach this. The next problem was Jekyll.
Jekyll is a “Simple, blog-aware, static site generator.” Easy to install, easy to use, easy to maintain. Except… Windows is not supported…
That’s it, I’m done! (╯°□°)╯︵ ┻━┻
No wait…? It is not supported, but it is possible to use with some “small” adjustments.
┬─┬ノ( º _ ºノ)
(I can’t believe these symbols work…)
Just needed some googling, and voilà, we have Jekyll up and running. The unsupported Windows, however, caused some more problems with Jekyll themes. Because the default theme is obviously not good enough for me. So back we dive into the mysterious depths of unsupported coding.
And finally, after two days, http://Amatson.github.io is ready to go global!
Two days of research, downloading, frustration, coding, more frustration, more research and a lot of school work set aside paid off.
And now. The real deal…
How did I do it?
As I said, I started the web page creation with Django. That was a whole another adventure and I will write about it later when the adventure is over. Yes, I am planning to finish it and start hosting my own domain. So back to Jekyll and GitHub Pages.
Setting up the git
I already had a GitHub account, so start phase was easy. Just followed the instructions in GitHub Pages website. I used terminal as a git client as terminal working is my way to live dangerously. Pun intended.
Now I had the initial site online. Drag-and-drop the content from the Django site? Haha. Good one.
Getting the Jekyll
Next, to build the sites effectively and to see the results locally without pushing them to git after every minute needed the Jekyll-o-wonder. So I headed to the GitHub help article about using Jekyll to find out more. Next more googling about Jekyll usage, from the source itself. Jekyll documents were pretty good and explaining, and Windows installation possibility was also offered. So there we dive.
By following the above mentioned Windows installation guide we first installed Ruby with devkit, the Jekyll gem for Ruby, syntax highlighter (not sure if in use right now), markdown gem and wdm auto-generation-rebuild gem. That’s it. Jekyll is on.
Some little notes though.
jekyll build and jekyll serve commands end up in error, I must use bundle exec jekyll build and bundle exec jekyll serve to make it work.
The page is on
Now we can start the page building process. Jekyll does some automagic job to get you started, so with the quick start guide I was able to get the base of the site working. By examining the autogenerated files I didn’t get far. Luckily the Jekyll documentations are good as mentioned. The default theme Minima was quickly working. I didn’t quite understand much about the Jekyll at this phase, but I wanted to change the theme to something more visually appealing.
The theme
And this is where the biggest problems started.
At first tried the theme chooser from GitHub helps but it just some build errors for me. I thought it had something to do with the gems I was using and the settings as the theme chooser only changed the \_config.yml file. This file has some key configurations that Jekyll uses.
With google helping I tried to install the themes as gems. Here I also needed to install github-pages gem, and sometimes the update of that gem helped. I managed to get the minimal theme working too, but it wasn’t what I wanted but only a test theme to see if at least some theme changes were possible to do.
Next thing to try to go around this was downloading the theme files from the github. I tried a few themes and ended up with Dinky theme as it was visually good and it scaled well with smaller screens. The theme was working on its own when Jekyll was served in the theme folder, but I could not get it working when using github-pages theme gem. After couple of hours I decided to come around with the problem and copy-pasted the theme files to my page root folder. Then by adding only my own content on it I managed to keep the theme working while being able to modify it to make it my own.
That’s it. The page worked!
Modifications I made
Now that the theme worked and pages looked good, it was time to add some content and modify the theme to make it look more like me.
I started by removing the button links from the navigation header. These were located in the default.html. It took some time to understand the referencing policy, but in the end I was able to link the additional pages to the navigation buttons. The key is that /-mark refers to the root of the pages folder, so /content links the button to root folders content-folder, and Jekyll always tries to find the index.html in folders. Now I created appropriate folders and placed an index.html-named file for all of the different pages I wished to show. This way also the URL of the sub-pages is in its pretty form, without the .html extension
Next I started adding the content from the Djago-project. This was pretty straight forward, I just needed to remove Django template and variable markings and paste pure HTML content. And then we started to get groovy.
Font Awesome
Last year in the User Interface Construction course I came across with glyphicons: small symbolic icons that can be used to give more visual effect to the text. One free, easy and super sufficient glyphicon pack was Font Awesome. It is easy to implement and it has multiple effect supports, so I adapted it fast to the navigation button symbols and contact information icons.
Grande finale
The last thing to do was to start writing my first post. It needed some markdown language reference because I thought it would be nice to try something new for a change after slow days with HTML. And that’s it. Here we are!
Finally, while writing this post, I learned that markdown takes HTML tags in, so yeah, I can use Font Awesome glyphicons and CSS magic to color also my posts. Groovy.
EDIT:
The finishing touch needed some coloring, so after consulting my brother with the issue, I decided to go with inverted color palette to create a coding-friendly-theme. I checked couple of color palette tools to help me with choosing the right colors.
Paletton.com was very nice for choosing eye pleasing background and suitable contrasts over it. This is something I will get back to and maybe do some fine tuning to my colors.
However, I used Coolors.co to pick suitable colors and then manually tuned them to pleasing color palette to use.
That’s it. I admit this post is a bit messy as I am currently writing it at 1:00 am. Hopefully it offered some help with setting up your own pages, or at least gave you some good time reading. Feel free to give me some feedback so I can improve my blogging style in the future.