A Blog Is Born

Creating a blog

Over the years I have frequented many developers blogs, read their articles and ultimately learned an awful lot from doing so.

I therefore decided that now I have a comfortable amount of time to work on my own projects, the first thing I should do is create myself a blog.
The blog will provide a means to cement the things I learn by writing them down, and hopefully, help out others along the way.

So, here you have it.
It's a simple Jekyll powered static site, hosted on GitHub Pages which also utilises the literate programming tools in the brilliant FSharp Formatting project for content generation.

Getting things started - Jekyll and Liquid

I won't go into huge detail on how to setup the initial blog itself as there are numerous guides for this purpose already out there on the web; Including the documentation on the Jekyll/GitHub sites themselves. Instead I will focus on a few key areas and then turn to some of the more interesting parts, such as the use of FSharp formatting.

Right then, let's get started with a brief intro to Jekyll followed by a look at its finer points.

The basic premise of a Jekyll blog is that you adhere to a basic folder structure and the Jekyll engine will take care of generating your site from the source files you create.
The files consumed by Jekyll have various purposes; From templates and includes, to page content such as blog posts.
The content of your pages can be written in a mark-up language such as markdown (various incarnations are supported) or simply HTML.


Layouts

So, I went ahead and created the directory structure required and began creating some basic layout pages.
Layout pages act as templates for your site content. You can specify a global layout and/or separate layouts for various parts of your site depending on your use case.

In addition, Jekyll supports the incredibly easy to use Liquid template engine.
Liquid allows you to display content in a variety of interesting ways and makes it easy to generate content such as lists or conditional segments.

As an example, I created a simple default layout to act as the overall site template and used some basic Liquid tags for content generation:

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
    <title>{{ page.title }}</title>
    <link rel="stylesheet" type="text/css" href="{{site.url}}/content/css/main.css">
    <link type="text/css" rel="stylesheet" href="{{site.url}}/content/css/style.css" />
    <script src="{{site.url}}/content/tips.js" type="text/javascript"></script>
</head>
<body id="{{page.id}}">
    {% include header.html %}
    <div id="page-content" >
        {{ content }}
    </div> 
    {% include footer.html %}
</body>
</html>

This HTML snippet looks normal enough, except it is littered with liquid tags (enclosed in {} ).
These tags are used to include content from other files when the sites static content is being generated by Jekyll.
In the example above you can see the title tag has its content set to page.title. This causes the tag to be replaced with the value of the title variable on the current page. (page itself is also a variable - more on variables shortly)

Another key element used in the above code are the include statements such as {% include header.html %}. Let's see what these includes have to offer then.


Includes

Includes are a way of including (Who knew!) blocks of code or markup in various places throughout your site. Thus giving you a simple way to re-use HTML fragments.
So, in the above example, the header include is replaced by the contents of the header.html file.

But that's not all Includes have to offer. They also allow us to pass parameters to them.
This is useful to further increase code re-use as we can write a small HTML file that creates content based on the value of a parameter.

We can utilise this approach in order to customise the output of particular pages. I found a good use of include parameters is for displaying lists of posts under tags or categories, as we can pass in the tag/category as a parameter to a single include.
This technique comes in especially handy when hosting on GitHub as the use of plugins (A technique to extend Jekyll behaviour) is prohibited for safety reasons.

Parameters passed to a liquid include statement can be referenced from within the contents of the target file by referencing the include variable. This can be seen in the example below, which is the tags page of this site.

<h1>Posts Tagged With "{{ include.tag }}"</h1>
<ul>
    {% for post in site.tags[include.tag] %}
    <li><span>{{ post.date | date: "%d %B %Y" }} : </span><a href="{{ post.url }}" title="{{ post.title }}">{{ post.title }}</a></li>
    {% endfor %}
</ul>

In order to utilise this include we have to manually create a page for each tag we use (due to plugins not being enabled).
I know, I know, that's a bit of a pain, but it's a small price to pay for excellent free hosting via GitHub Pages.
Each tag page consists of a single include statement with the tag name we want to display posts for passed in as a parameter.

Here is my FSharp tag page in all its single line glory!

{% include tagposts.html tag="fsharp" %}


Variables and Front Matter

You will have noticed that in the previous snippets there are a fair few variables being used to display particular data.
These variables, such as page.title are either generated by Jekyll or manually specified on a global, or per page/post basis. When declaring global variables, they are added to a _config.yml file in the sites root directory.

This config file contains general Jekyll options (a list of which can be found on the Jekyll site - here) as well as global variables which we can access on every page we create. Alternatively, we can declare variables in the YAML front matter that is required on each page/post we create.

A YAML what now!? I hear you say.
YAML Front Matter of course!

Front Matter is a block of YAML that you place at the beginning of every file you wish Jekyll to process as a special file, be it Markdown or just plain HTML.

Every file in the _posts folder is treated as special regardless of front matter presence. However, if the page resides elsewhere and there is no front matter block in the file, it will not be treated as special. In this block of YAML you can declare custom variables for use within the page, as well as specify the layout template to use and other standard Jekyll configuration options.
Setting options at this level will overwrite the options in the global _config file I mentioned earlier. The following example is taken from this very blog post:

---
layout: post
title: A Blog Is Born
date: 17/02/2015
tags: ["fsharp","general"]
---

At this point, we have everything we need to create our blog. All that is left to do is create some content.
I opted to role my own design (I actually enjoy it!) but there are numerous themes and base projects out there that provide the initial setup needed for a Jekyll blog.
Once we have a site design finished all that's left is to create some posts.

Time to get posting! (Well, I'm half way through my first post already)

Creating a post is as simple as creating a quick markdown file, specifying some options in a front matter block (such as layout), and placing the file in the _posts folder.
Jekyll will then automatically create us a nicely formatted blog post by parsing the markdown and applying out templates. Best of all, our site will auto update as soon as we make the commit to our GitHub repo.

This standard setup is great, but as I hope to use F# for most of my projects in the future, I thought I would look at using the FSharp.Formatting project.

The immediate benefits of this are two fold:

  • It generates awesome syntax highlighted code blocks with added tooltips for token info.
  • F# Code samples within our posts are fully typed checked and executable!

Sounds great - Let's take a look.


F Sharp Formatting

The literate programming tools supplied with the FSharp.Formatting project allow us to take FSharp script (.fsx), or markdown files and generate HTML, or latex outputs from them.
In order to fully utilise the type checking and give me the ability to quickly execute the samples while writing my posts, I opted for the .fsx option.

To create a post in a script file, we include standard markdown syntax in side multi-line comment blocks (** *) for text (or other non FSharp.Formatting rendered code snippets etc) and then simply include snippets of F# directly in the file which are then rendered like so:

1: 
let printDesc() = printfn "ooh look, what lovely tooltips!"

We can now be sure that all of our code samples in our blog posts are valid before posting.

I did have a couple of issues getting FSharp.Formatting setup.
At first I couldn't see a way to both generate the posts using FsFormatting and satisfy Jekyll's want for front matter (In order to allow me to use the standard layout templates and variable assignments).
My initial solution was to live with having to use a template within FSharp.Formatting itself in order to add the YAML block to the front of the files as needed.

This was obviously not a brilliant solution as I couldn't easily change options or declare custom variables on a per post basis.

This is when I came across this post by Colin Bull which solves the problem entirely.
The use of the raw command mentioned in the linked post allows us to insert raw text -- with no mark-up at all -- into our pages (prior to consumption by Jekyll).

This is exactly what we need! Once I had this in place, I could simply utilise the command line tools, as Colin also suggests, in order to generate and publish my posts.

With this final piece in place, the blog is ready to go.


Some other points of interest

As much as I love the formatting of F# snippets provided by FSharp.Formatting. I also dislike the formatting of snippets for other languages.
Luckily for me, Jekyll provides code highlighting too.

It offers two options, Pygments, or Rouge.
Both of these options can be used with the same CSS for their Syntax highlighting and so are pretty interchangeable. (I did opt for Rouge locally however due it being easier to install on windows - No Python dependency)
Using the standard highlighter for all other code blocks allows me to get the best of both worlds.

In order to utilise this highlighting we need to tell Jekyll to treat a text block as highlighted code.
In addition I found it useful to instruct Jekyll to ignore Liquid tags wherever present in my code blocks.
This allows us to show Liquid examples like so:

{% highlight html %}
{% raw %}
<div> Some HTML </div>
{% endraw %}
{% endhighlight %}

That's all there is to it!
Happy blogging.

val printDesc : (unit -> unit)
val printfn : format:Printf.TextWriterFormat<'T> -> 'T

Full name: Microsoft.FSharp.Core.ExtraTopLevelOperators.printfn
Next Post