How to install and use Hakyll

Note: This is a Hakyll usage guide aimed at people completely new to Linux.

What is Hakyll?

Hakyll lets you generate a static site. For now, you can think of it as something that converts your Markdown files into HTML. When you put your HTML files on some web-hosting site, other people can view them from their browsers.

This is different from dynamic sites like WordPress, where you don’t have access to the actual HTML or Markdown files for your own website. You have to write stuff in some online editor and WordPress updates everything magically. You can only do what WordPress allows you to - you don’t have full control over your website.

How does Hakyll work?

You write each blog post in a separate Markdown file. You use Hakyll’s instant preview ability to see how your website looks at each point. You add how many ever posts you want, in whatever order you want. You do all of this offline. When you’re happy with your changes, you upload the Hakyll-generated HTML files to some web-hosting site.

In short, you write Markdown; Hakyll turns it to HTML; and you send the HTML to some website. You only need a web connection for the final step.

Also, we use a time-machine program called git to save and send the HTML. This way, if we break something or lose our local copy or just screw it up in any way, we can go back in time to a version of the website that looked fine. Github is a free site that will let you put up time-machined HTML pages.

Overview

Let’s take this one baby step at a time instead of trying to get the whole thing going in one shot.

First, we install everything needed for Hakyll. Then, we set up a basic site for the first time and view it in our browser. Next, we learn how to make changes locally and view the updated website. Finally, we learn how to upload our website to Github so that everyone can view it.

Installation

To install ghc, simply install haskell-platform

Haskell is a programming language, like C, C++, or Java.

$ sudo apt-get install haskell-platform

I’m assuming you already have the git package. Still,

$ sudo apt-get install git

Install hakyll using cabal

First, install cabal.

$ sudo apt-get install cabal-install

Then, install hakyll

$ cabal install hakyll

If you’ve come so far, pat yourself on the back. You’re almost there.

Finding hakyll-init

First, you need to make sure the terminal can find hakyll-init. It can only do that if the directory containing the hakyll-init program is in the PATH variable. So, let’s put it in the PATH.

hakyll-init is found in the directory called ~/.cabal/bin. So, we need to add ~/.cabal/bin to the PATH.

Put the following line at the end of the file called ~/.bashrc

$ export PATH=~/.cabal/bin:$PATH

If there is no such file in the home directory (which is called ~), then create one - using Gedit, maybe. After you have saved that file, run

$ source ~/.bashrc

in the terminal. (Or just restart the terminal)

Setting up your site for the first time

Now, let’s create a basic site.

Decide where you want to put your website files. Let’s say you have created a ~/Website directory. Go there (using the command cd)

$ cd ~/Website

The terminal prompt should show that you are in the ~/Website directory.

Now, create a basic site:

$ hakyll-init my-site

You’ll now have a new directory called my-site with default configurations.

Create the site generator

Let’s start adding lots of changes to the website and make it perfect within 5 minutes.

No.

Let’s first test it as it is. Test first, then make changes.

We need a program that will turn your Markdown files to HTML That is called the site program.

Go into the my-site directory (using cd, as usual)

$ cd my-site

The site.hs file in this directory contains the configuration for your website (check it out). By compiling it, you get a site program that you can use to build your website.

Compile the site.hs configuration file:

$ ghc --make -threaded site.hs

You need to do this every time you make a change to the configuration, which you will do quite rarely.

Build your website

You haven’t added anything yet, but let’s just see what the default website looks like. Tell the site program to build your website.

$ ./site build

You should now be able to see a directory called _site. It will contain HTML files, CSS files, etc. This is your website.

Let’s view your website in the browser. First, you need to tell the site program to run a preview server.

$ ./site watch

This will let you to view your pages in the browser. Open http://localhost:8000/ in Firefox or Chrome or whatever. There you go! You now have a working local website.

Everyday usage

To change an existing Markdown page, just go into one of the pre-existing Markdown pages (using Gedit or some other editor). Make your changes. If ./site watch is running, you will be able to see the changes in your website by refreshing your browser page. You can change different parts, like the title, etc. and watch the website getting updated.

To add a new page, just create a new file. Let’s say you want to create Foo.markdown. Just copy an existing page (so that you get the formatting and initial details like title, etc.) and rename it to Foo.markdown. Check the website in your browser. If you can’t see the new page in your browser, then you may have to restart the preview server. Stop it by pressing C-c C-c. Then, run ./site watch again.

Coming Soon

How to set up a Github repository for your website; how to get your website ready to be uploaded; how to actually upload it so that everybody can view it online.

Notes

Thanks to the official Hakyll installation page. I expanded each step so that my non-programmer friend could use Hakyll to create a personal static site.

FAQ

I don’t have an idea what am doing. I just do as is given in some website that I come across.

Check if the above instructions have given you a good idea of what you’re doing.

How do you know if they have given you a good idea? Well, do you have a working website at the end of the day? Do you know what you need to do to add new pages, change existing ones, upload your website, etc.? Then, it means you have got a good idea.
I don’t know how to know if the installation has been performed correctly.

How do we check our installation, Master Wayne?

We test the program immediately, before making any changes.

First of all, if you had some errors while installing the program, apt-get will tell you right away - “ERROR: something something something”. If it worked correctly, it will just stay silent. That is part of the Unix philosophy (Linux is an open-source version of Unix).

Rule of Silence: When a program has nothing surprising to say, it should say nothing.

One of Unix’s oldest and most persistent design rules is that when a program has nothing interesting or surprising to say, it should shut up. Well-behaved Unix programs do their jobs unobtrusively, with a minimum of fuss and bother. Silence is golden.

– Eric S. Raymond, The Art of Unix Programming

Just to convince yourself, try running the program. Say you installed git. Now, go to the terminal and say git or git --help. If you haven’t installed the program right, you’ll get a message saying “command not found”. If you have installed it right, then you will get some basic help messages.
I don’t know what is the difference between package, software. Is cabal a package, is git a software? Basics of types of things encountered while using UBUNTU.

Roughly, software is what you can run, like Firefox. Package is like the… um… package or box that the software comes in. People use both of them interchangeably.

Most of the time, if you want to use some software (aka program) called foo, you need to install it by using sudo apt-get install foo. That’s it. Even easier, you can use the Ubuntu Software Center for popular programs.

Further notes:

Theoretically, you need to download the package and then unpack it and install the software. apt-get install does both things without telling you.

So, when you say sudo apt-get install git, git is the name of the package. Now, apt-get will unpack and install the software. Fortunately, like in most cases, the program is called git too. So, you can use git to run the software.
You say it takes a day to get hakyll done. What does that mean. How about you say it in terms of hours.

It will take a day for you, as a new user. In terms of hours, that’s like 24 hours, depending on the relative position of the Sun and the Earth. It’s just like setting up Ubuntu for the first time, which can take a while.
How much of Cabal and Hakyll and git basics do I need to know to set up this page.

Basically, just what I wrote in the above tutorial. A bit of git, and almost nothing of cabal or hakyll.

Created: September 1, 2015

Last modified: January 25, 2016

Status: in-progress

Tags: hakyll